feat: Loki log backend — first non-file log source (vertical slice)

[HumanBean17]

Summary

agctl logs * previously reached only local NDJSON files. This PR ships the first non-file log backend — a built-in type: loki source — and the shared foundation every later backend (docker, journald, syslog, ELK, CloudWatch) will inherit.

Approach: a deliberate vertical slice (one backend, end-to-end) that hardens the LogBackend patterns once, so the remaining five inherit a proven shape rather than each re-discovering the gaps. Spec: docs/superpowers/specs/active/2026-07-22-loki-log-backend-design.md; plan: docs/superpowers/plans/active/2026-07-22-loki-log-backend-plan.md.

What's in it

• agctl/clients/log_backends/loki.py — LokiBackend (5-method LogBackend): query_range fetch with full HTTP error mapping; client-side filtering; two-phase await_one (timestamp high-water, no double-count); poll-based follow (dedup + stop-event + transient-error tolerance).
• agctl/clients/log_common.py (new, extracted) — shared slot-mapping normalization (normalize_dict), per-entry filtering (entry_matches), schema inference (infer_schema). NdjsonFileBackend now delegates to it (−115 lines of triplicated logic, behavior-preserving — its existing suite stays green at the identical count).
• agctl/config/models.py — LogSource gains url / query / options (backend-specific escape hatch, mirroring DatabaseConnection.options) and extra="forbid" (so a misplaced top-level username:/token: fails loud instead of silently breaking auth).
• agctl/clients/log_client.py — BUILTIN_BACKENDS = {"file": NdjsonFileBackend, "loki": LokiBackend}.
• pyproject.toml — new loki = ["httpx>=0.27", "jq>=1.6"] extra. httpx is lazy-imported inside methods; a missing extra surfaces as ConfigError (exit 2) pointing at pip install 'agctl[loki]', never a crash.

How it works

The user authors the LogQL query in config (server-side filtering); agctl's --level/--logger/--message/--match apply client-side over fetched entries — identical semantics to the file backend, no fragile LogQL generation. scan reports honest two-signal truncation (matched > limit or Loki hit its fetch cap). follow polls query_range with an advancing start (no websocket dependency). tail_lines is ignored (a documented file-backend hint).

logs:
  sources:
    order-service:
      type: loki
      url: "${LOKI_URL}"
      query: '{app="order-service"}'
      service: order-service
      options:
        username: "${LOKI_USER:-}"      # basic auth (mutually exclusive with token)
        password: "${LOKI_PASSWORD:-}"
        token: "${LOKI_TOKEN:-}"        # bearer
        org_id: "${LOKI_ORG_ID:-}"      # X-Scope-OrgID
        verify_tls: true
        fetch_limit: 500                # > agctl --limit, for filtering headroom
        direction: forward

Error mapping mirrors HttpClient: 400 / non-stream result → ConfigError (2); 401/403/5xx/ConnectError → ConnectionFailure (2); ReadTimeout → OperationTimeout (1). The command layer (logs_commands.py) is unchanged — Loki is transparent behind LogClient; the one-JSON-envelope contract is preserved.

Testing

• 1732 unit tests pass / 32 skip (full suite green throughout — file-backend refactor preserved byte-for-byte; +~50 new tests for log_common + LokiBackend). httpx is injected via a duck-typed http_client seam, so unit tests run without httpx installed; transport-exception tests use pytest.importorskip("httpx") + MockTransport.
• Self-skipping live integration test (tests/integration/test_logs_loki.py + require_loki/_start_loki in conftest) — pushes a line to a grafana/loki container and queries it back. Skips cleanly without Docker / AGCTL_TEST_LIVE; the green path runs in CI.

Deliberately deferred (non-goals for this slice)

LogQL filter push-down · websocket /tail · mTLS/client certs · the other five backends (docker/journald/syslog/ELK/CloudWatch) · a shared remote-HTTP base class + LogBackend protocol refactor (extract after a second remote backend proves the shared surface — YAGNI).

Process

Spec → 9-task TDD plan → executed via subagent-driven-development (fresh implementer + task reviewer per task, one Important fix applied + re-reviewed, consolidated Minor cleanup). Docs synced via docs-watcher (DESIGN §2.1/§9.2, ARCHITECTURE §3/§8/§10/§11/§15, skills/agctl-config/reference/logs-sources.md).

🤖 Generated with Claude Code