@event4u/agent-config 2.13.0 → 2.14.0

package/docs/contracts/installed-tools-lockfile.md

@@ -12,7 +12,8 @@ repository.
 - **Authoritative module:** [`scripts/_lib/installed_tools.py`](../../scripts/_lib/installed_tools.py)
 - **ADR:** [`docs/decisions/ADR-008-installed-tools-manifest.md`](../decisions/ADR-008-installed-tools-manifest.md)
 - **Workflow guide:** [`docs/guidelines/agent-infra/installed-tools-manifest.md`](../guidelines/agent-infra/installed-tools-manifest.md)
-- **Active roadmap:** P1.1 of [`agents/roadmaps/road-to-multi-package-coexistence.md`](../../agents/roadmaps/road-to-multi-package-coexistence.md)
+- **Active roadmap:** P1.1 of the `road-to-multi-package-coexistence`
+  roadmap (see `agents/roadmaps/` for current status).
 
 ## Versions
 

package/docs/contracts/low-impact-corpus-format.md

@@ -0,0 +1,95 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# `low-impact-decisions.md` — corpus format contract (step-9 P4)
+
+Parser-visible invariants for `agents/low-impact-decisions.md` and any
+upstream seed at the same path. The hardened parser lives in
+[`scripts/ai_council/low_impact_corpus.py`](../../scripts/ai_council/low_impact_corpus.py)
+and ships in two modes:
+
+| Mode | Entry point | Behaviour on drift |
+|---|---|---|
+| **Lenient** (routing hot-path) | `load_validated_phrases(path)` | Silently drops the offending line. Routing never blocks on a malformed corpus. |
+| **Strict** (CI lint + intake) | `parse_corpus_strict(path)` | Raises `CorpusParseError` with a typed `reason` and 1-based `line` on the first anomaly. |
+
+## Required sections
+
+```
+## On Probation
+
+<!-- intake-anchor: probation -->
+
+…
+
+## Validated
+
+<!-- intake-anchor: validated -->
+
+…
+
+## Anti-Examples (Always Ask User)
+
+…
+```
+
+- Heading level **MUST** be `##` (two hashes). `###` → `heading_drift`.
+- Trailing punctuation on a heading (`## Validated:`) → `heading_drift`.
+- Sections may appear in any order; missing sections are tolerated by
+  both modes (an empty corpus is valid).
+- The intake-anchor HTML comments **MUST** be present for the two
+  intake-bearing sections (`probation`, `validated`) once any section
+  body is present. Strict mode raises `missing_anchor` otherwise; the
+  lenient shim ignores anchors (anchors are for the intake writer, not
+  the routing reader).
+
+## Bullet shape
+
+```
+- "<phrase>" — optional trailing metadata
+```
+
+Strict invariants:
+
+| Drift | `reason` | Example |
+|---|---|---|
+| Curly opening quote (`U+201C` / `U+2018`) | `curly_quotes` | `- “foo bar”` |
+| Single-quoted phrase | `single_quotes` | `- 'foo bar'` |
+| Non-dash list marker (`*`, `+`, `1.`) | `non_dash_bullet` | `* "foo bar"` |
+| Opening `"` with no matching close on the same line | `unclosed_quote` | `- "foo bar — meta` |
+| Phrase normalises to empty (whitespace / punctuation only) | `empty_phrase` | `- "   …"` |
+
+Trailing metadata (everything after the closing `"`) is preserved on
+the `CorpusEntry.trailing_metadata` field but is **not** consulted for
+routing — only the normalised phrase is.
+
+## Phrase normalisation
+
+A phrase is normalised before equality / similarity comparison:
+
+1. Lowercase.
+2. Replace every non-`[\w\s]` character with a single space.
+3. Collapse runs of whitespace.
+4. Strip leading / trailing whitespace.
+
+This normalisation runs in both modes and is stable across the
+routing classifier (`classify_impact_with_corpus`), the intake module
+(`low_impact_intake`), and the probation gate.
+
+## Failure-mode fixtures
+
+The seven canonical failure cases ship as fixtures under
+[`tests/fixtures/corpus-robust/`](../../tests/fixtures/corpus-robust/),
+one file per `reason`. The strict-mode suite
+[`tests/test_low_impact_corpus_robustness.py`](../../tests/test_low_impact_corpus_robustness.py)
+asserts each fixture trips the matching `CorpusParseError.reason` and
+that the lenient shim degrades silently for per-bullet drift.
+
+## Cross-references
+
+- Privacy floor — `.augment/rules/low-impact-corpus-privacy-floor.md`
+- Routing — `scripts/ai_council/necessity.py § classify_impact_with_corpus`
+- Intake — `scripts/ai_council/low_impact_intake.py`
+- Promotion / pruning — `scripts/ai_council/probation_gate.py`

package/docs/contracts/mcp-beta-criteria.md

@@ -7,8 +7,8 @@ mcp_scope: lite
 
 > **Status:** Active · governs the `experimental → beta` promotion for
 > the MCP surface (`scripts/mcp_server/` local stdio kernel + the
-> hosted `workers/mcp/` bridge). Owned by Phase 3 of
-> [`road-to-surface-discipline.md`](../../agents/roadmaps/road-to-surface-discipline.md).
+> hosted `workers/mcp/` bridge). Owned by Phase 3 of the
+> `road-to-surface-discipline` roadmap (see `agents/roadmaps/`).
 > Companion contract:
 > [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (local) ·
 > [`mcp-cloud-scope.md`](mcp-cloud-scope.md) (hosted).
@@ -91,8 +91,9 @@ ping. Evidence: the workflow file (`.github/workflows/mcp-no-drift.yml`)
 1. Open a release-candidate branch named `release/mcp-beta-rcN`.
 2. Run `./agent-config doctor --check mcp-beta-readiness` — must
    print all six gates green.
-3. Flip the wording in the **five** surfaces inventoried in
-   [`road-to-surface-discipline.md` Phase 3 Step 1](../../agents/roadmaps/road-to-surface-discipline.md):
+3. Flip the wording in the **five** surfaces inventoried in the
+   `road-to-surface-discipline` roadmap (Phase 3 Step 1, under
+   `agents/roadmaps/`):
    `docs/mcp-server.md` (status banner + Remote-MCP sub-claim),
    `README.md` (pointer line), `scripts/mcp_server/server.py`
    (initialize-result `serverInfo.name`),
@@ -125,5 +126,5 @@ delta for Phase 3: ≤ 0.
 - [`STABILITY.md`](STABILITY.md) — stability tier definitions
   (`experimental` / `beta` / `stable`) and what wording each tier may
   use in user-visible surfaces.
-- [`road-to-surface-discipline.md`](../../agents/roadmaps/road-to-surface-discipline.md)
+- The `road-to-surface-discipline` roadmap (under `agents/roadmaps/`)
   — Phase 3 acceptance criteria and step-level evidence pointers.

package/docs/contracts/mcp-cloud-scope.md

@@ -31,9 +31,9 @@ alongside auth).
 
 The package ships **two MCP surfaces** governed by named scopes. Every
 MCP-related doc, ADR, and code path carries `mcp_scope: lite|full|deferred`
-in its frontmatter (Phase 1 Step 6 of
-`agents/roadmaps/road-to-distribution-maturity.md`) so the boundary is
-machine-checkable, not prose-only.
+in its frontmatter (Phase 1 Step 6 of the distribution-maturity roadmap,
+under `agents/roadmaps/`) so the boundary is machine-checkable, not
+prose-only.
 
 ### `mcp_scope: lite` — hosted, read-only knowledge surfaces
 
@@ -239,7 +239,8 @@ The README MCP section may **only** name modes that this `## Auth
 surface` section declares. This contract must declare every mode the
 README names. The drift test
 `tests/test_mcp_contract_readme_sync.py` enforces both directions
-per Phase 1 Step 4 of `agents/roadmaps/road-to-distribution-maturity.md`.
+per Phase 1 Step 4 of the distribution-maturity roadmap (under
+`agents/roadmaps/`).
 
 ## A0-cloud invariants
 

package/docs/contracts/multi-tool-projection-fidelity.md

@@ -1,6 +1,12 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
 # Multi-Tool Projection Fidelity Contract
 
-**Status:** beta · **Phase 4 of [step-1-v2-feedback-followup](../../agents/roadmaps/step-1-v2-feedback-followup.md)**
+**Status:** beta · **Phase 4 of the `step-1-v2-feedback-followup`
+roadmap** (under `agents/roadmaps/`).
 
 Names the **per-tool guarantees** the projection pipeline (`scripts/compress.py --sync` + `scripts/compress.py --generate-tools`) actually delivers. Byte-equivalence is not behaviour-fidelity — each consumer tool has its own frontmatter grammar, its own activation model, and its own surface for skills / rules / commands.
 
@@ -106,4 +112,4 @@ These are **architectural facts**, not regressions. They are documented so insta
 - [`augment-projection`](../architecture/augment-projection.md) — pipeline B (Augment-specific)
 - [`multi-tool-projection`](../architecture/multi-tool-projection.md) — pipeline C (the per-tool emitters)
 - [`rule-router`](rule-router.md) — the `triggers:` / `routes_to:` grammar this contract pins
-- [`agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md`](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md) — origin council feedback
+- [`agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md`](../../agents/council-sessions/2026-05-14-v2-analysis/feedback/09-cross-tool-projection-fidelity.md) — origin council feedback <!-- council-ref-allowed: contract origin trace -->

package/docs/contracts/release-trunk-sync.md

@@ -11,7 +11,8 @@ keep-beta-until: 2026-08-12
 > points across the 2.x cycle. External readers landing on `main`
 > consistently saw stale README counts and missing skill catalogues
 > relative to the npm/Packagist artefact.
-> **Closes:** [Road to Productization](../../agents/roadmaps/road-to-productization.md) § P1.2.
+> **Closes:** the `road-to-productization` roadmap § P1.2 (under
+> `agents/roadmaps/`).
 
 ## Decision
 
@@ -100,5 +101,5 @@ not orphan the convention.
 - [`.github/workflows/release-guard.yml`](../../.github/workflows/release-guard.yml)
   — tag/version-file integrity gate (orthogonal: this contract handles
   trunk position, release-guard handles version-string integrity).
-- [`agents/roadmaps/road-to-productization.md`](../../agents/roadmaps/road-to-productization.md)
-  § Phase 1.
+- The `road-to-productization` roadmap § Phase 1 (under
+  `agents/roadmaps/`).

package/docs/contracts/tier-3-contrib-plugin.md

@@ -26,10 +26,9 @@ Last refreshed: 2026-05-12.
 | **Tier-2** | Shipped | Named in roadmaps + has plausible audience | Imperative bridge, same pattern as Tier-1 |
 | **Tier-3** | **Deferred** | Named in scoping/council but zero user demand | Manifest YAML in `agents/manifests/contrib/` (not yet implemented) |
 
-Phase 2.1 + 2.2 of
-[`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
-closed Tier-1 and Tier-2 at **16 AIs**. Tier-3 is the explicit
-overflow bucket.
+Phase 2.1 + 2.2 of the `road-to-global-first-install` roadmap
+(under `agents/roadmaps/`) closed Tier-1 and Tier-2 at **16 AIs**.
+Tier-3 is the explicit overflow bucket.
 
 ## Candidate list (frozen at proposal time)
 
@@ -126,5 +125,5 @@ not "preemptively scaffold" Tier-3 entries.
 - [`ADR-008`](../decisions/ADR-008-installed-tools-manifest.md) —
   `agents/installed-tools.lock` for per-project state, distinct
   from this maintainer-side contract.
-- [`road-to-global-first-install`](../../agents/roadmaps/road-to-global-first-install.md)
-  Phase 2.6 — completion trigger for this contract.
+- The `road-to-global-first-install` roadmap (under
+  `agents/roadmaps/`) Phase 2.6 — completion trigger for this contract.

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 65 rules. No configuration needed.
+This is enforced automatically by 67 rules. No configuration needed.
 
 ---
 
@@ -146,7 +146,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 108 active commands](../.agent-src/commands/)
+→ [Browse all 109 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -4,7 +4,8 @@ Project-committed bill of materials for AI tooling. Answers the
 question "which AIs does this project use, where do their bridges live,
 and is everyone on the team on the same set?". Canonical schema is
 ADR-008 ([`docs/decisions/ADR-008-installed-tools-manifest.md`](../../decisions/ADR-008-installed-tools-manifest.md)).
-Phase 3 of [`road-to-global-first-install`](../../../agents/roadmaps/road-to-global-first-install.md).
+Delivered under the global-first-install roadmap (Phase 3) — see
+`agents/roadmaps/` for current status.
 
 This file lives at **`agents/installed-tools.lock`** — committed,
 machine-managed, and orthogonal to `.agent-project-settings.yml`

package/docs/installation.md

@@ -646,6 +646,38 @@ the symlinks and regenerates derived files (`.windsurfrules`,
 
 ---
 
+## AI Council local state
+
+The AI Council ([`docs/contracts/ai-council-config.md`](contracts/ai-council-config.md))
+writes two local-only files outside the repo contract:
+
+- `~/.event4u/agent-config/cli-calls.json` — per-day call counter for
+  `mode: cli` members. Daily UTC reset. Inspect with
+  `agent-config council quota`; clear today's counter for one provider
+  with `agent-config council quota --reset <provider> --confirm`.
+- `agents/council-events.log` — JSONL audit trail. One line per
+  necessity-gate decision and per quota block. Gitignored by the
+  installer (managed `.gitignore` block); never committed.
+  `original_ask` is hashed `sha256[:12]` before write — the raw prompt
+  is never persisted.
+
+Both are opt-in by construction: the quota counter only fires when a
+provider has `cli_call_budget.max_calls_per_day.<provider>` set, and
+the events log is purely additive (deletable at any time).
+
+### Kill-switches
+
+Per-feature environment overrides for ephemeral worktrees, CI runners,
+or sandbox testing:
+
+- `AGENT_CONFIG_NO_EVENTS_LOG=1` — disables every write to
+  `agents/council-events.log` in-process. Quota counter and council
+  output stay untouched.
+- `AGENT_CONFIG_LEGACY_ANCHOR=1` — opt back into the pre-step-7
+  legacy-anchor behaviour for `.agent-settings.yml` migration.
+
+---
+
 ## Windows
 
 Native Windows is not a first-class target. Use one of the following:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.13.0",
+    "version": "2.14.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_doctor.py

@@ -36,6 +36,7 @@ import argparse
 import hashlib
 import json
 import re
+import shutil
 import sys
 from pathlib import Path
 from typing import Any
@@ -287,6 +288,7 @@ CHECK_IDS = (
     "offline-readiness",
     "python-runtime",
     "tier-usage-readiness",
+    "council-cli",
     "unsupported-combos",
 )
 
@@ -675,6 +677,137 @@ def _check_tier_usage_readiness(project_root: Path) -> dict[str, Any]:
     }
 
 
+#: Provider → (default binary, billable flag). Mirrors the
+#: ``CliClient`` subclass attributes in ``scripts/ai_council/clients.py``
+#: without importing them at module load time (keeps doctor lightweight
+#: and robust if council deps fail to load).
+_CLI_PROVIDER_META: dict[str, tuple[str, bool]] = {
+    "anthropic": ("claude", False),
+    "openai": ("codex", False),
+    "gemini": ("gemini", False),
+    "xai": ("grok", True),
+    "perplexity": ("perplexity", True),
+}
+
+
+def _check_council_cli(project_root: Path) -> dict[str, Any]:
+    """Health-probe each enabled ``mode: cli`` council member.
+
+    For every CLI member in ``agents/.ai-council.yml`` reports binary
+    presence (via ``shutil.which``), billable flag, daily-quota state
+    (used/cap or used/—), and rolls up to a single status icon.
+
+    No subprocess is spawned: ``--version`` probes would defeat the
+    cheap-by-default contract and surface flaky network paths (Codex
+    talks home on first run). Binary presence + the cached
+    ``cli-calls.json`` counter cover the actionable failure modes.
+
+    Status rules:
+
+    - ``ok`` — every enabled CLI member has its binary on PATH AND
+      (when capped) usage is below ``warn_at``.
+    - ``warn`` — at least one binary is missing OR usage crosses
+      ``warn_at`` for at least one capped member.
+    - returns ``ok`` with "no council config" if
+      ``agents/.ai-council.yml`` is absent (consumer project that
+      hasn't enabled the council yet).
+    """
+    council_path = project_root / "agents" / ".ai-council.yml"
+    if not council_path.exists():
+        return {
+            "id": "council-cli", "status": "ok",
+            "message": "no council config (agents/.ai-council.yml not present)",
+            "remedy": "",
+        }
+    try:
+        from scripts.ai_council.clients import load_cli_call_counts
+        from scripts.ai_council.config import load_council_config
+    except Exception as exc:  # noqa: BLE001 — defensive: doctor must not crash
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": f"council deps unavailable ({type(exc).__name__})",
+            "remedy": "install PyYAML and ensure scripts/ai_council is importable",
+        }
+    try:
+        cfg = load_council_config(council_path)
+    except Exception as exc:  # noqa: BLE001
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": f"council config invalid: {exc}",
+            "remedy": "fix agents/.ai-council.yml and re-run doctor",
+        }
+    cli_members: list[tuple[str, Any]] = [
+        (name, m) for name, m in cfg.members.items()
+        if m.enabled and m.mode == "cli" and name in _CLI_PROVIDER_META
+    ]
+    if not cli_members:
+        return {
+            "id": "council-cli", "status": "ok",
+            "message": "no enabled CLI-mode members",
+            "remedy": "",
+        }
+    counts = load_cli_call_counts()
+    caps = cfg.cli_call_budget.max_calls_per_day
+    warn_at = float(cfg.cli_call_budget.warn_at)
+    missing: list[str] = []
+    over_warn: list[str] = []
+    lines: list[str] = []
+    for name, member in cli_members:
+        default_bin, billable = _CLI_PROVIDER_META[name]
+        binary_name = member.binary or default_bin
+        resolved = shutil.which(binary_name)
+        binary_glyph = "✅" if resolved else "❌"
+        if resolved is None:
+            missing.append(name)
+        used = int(counts.get(name, 0))
+        cap = caps.get(name)
+        if cap is not None:
+            ratio = used / cap if cap > 0 else 0.0
+            quota_glyph = "⚠️" if ratio >= warn_at else "✅"
+            if ratio >= warn_at:
+                over_warn.append(name)
+            quota_str = f"{used}/{cap}"
+        else:
+            quota_glyph = "—"
+            quota_str = f"{used}/—"
+        billable_str = "billable" if billable else "subscription"
+        lines.append(
+            f"{name}: binary {binary_glyph} ({binary_name}) · "
+            f"quota {quota_glyph} {quota_str} · {billable_str}"
+        )
+    detail = " | ".join(lines)
+    if missing:
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": (
+                f"{len(missing)}/{len(cli_members)} CLI member(s) missing binary "
+                f"({', '.join(missing)}) · {detail}"
+            ),
+            "remedy": (
+                "install the missing CLI(s) — see `council:estimate` pre-flight "
+                "for per-provider install hints, or flip "
+                "ai_council.members.<name>.mode to 'api'"
+            ),
+        }
+    if over_warn:
+        return {
+            "id": "council-cli", "status": "warn",
+            "message": (
+                f"{len(over_warn)}/{len(cli_members)} CLI member(s) at/over "
+                f"quota warn_at={warn_at} ({', '.join(over_warn)}) · {detail}"
+            ),
+            "remedy": (
+                "wait for UTC rollover or run "
+                "`python3 scripts/council_cli.py quota --reset` to clear the counter"
+            ),
+        }
+    return {
+        "id": "council-cli", "status": "ok",
+        "message": f"{len(cli_members)} CLI member(s) healthy · {detail}",
+        "remedy": "",
+    }
+
+
 def _check_unsupported_combos(manifest: dict[str, Any]) -> dict[str, Any]:
     """Flag tools whose ``scope`` violates the global-only or project-only rules."""
     global_only = {"droid", "qoder"}
@@ -720,6 +853,7 @@ def _run_checks(
         "offline-readiness": lambda: _check_offline_readiness(),
         "python-runtime": lambda: _check_python_runtime(),
         "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
+        "council-cli": lambda: _check_council_cli(project_root),
         "unsupported-combos": lambda: _check_unsupported_combos(manifest),
     }
     out: list[dict[str, Any]] = []

package/scripts/ai_council/airgap.py

@@ -0,0 +1,165 @@
+"""Airgap detection for the AI Council installer / first-run (step-9 P11 · U1).
+
+Probes DNS for the three primary council provider hosts with a short
+timeout. If **all** probes fail the environment is treated as airgapped
+and the installer is expected to seed ``defaults.member_mode: api`` (the
+CLI default would otherwise launch ``codex``/``claude``/``gemini``
+binaries that cannot reach their backends).
+
+Why DNS, not HTTP:
+- DNS is cheap (UDP, ~1 packet), HTTP probes are billable surface.
+- A DNS hit is sufficient to disprove airgap; the actual reachability
+  of the host is checked at first use, not here.
+- No auth required, no false negatives from corporate proxies that
+  block HTTPS but allow DNS.
+
+Public surface:
+- ``COUNCIL_PROBE_HOSTS`` — tuple of hosts to probe.
+- ``probe_host(host, timeout)`` — single-host probe, returns bool.
+- ``detect_airgap(*, hosts, timeout, resolver)`` — returns ``True`` iff
+  every host fails. ``resolver`` is injectable for tests.
+- ``airgap_banner()`` — the one-liner the installer prints when airgap
+  is detected.
+"""
+
+from __future__ import annotations
+
+import socket
+from collections.abc import Callable, Iterable
+
+COUNCIL_PROBE_HOSTS: tuple[str, ...] = (
+    "api.anthropic.com",
+    "api.openai.com",
+    "generativelanguage.googleapis.com",
+)
+
+DEFAULT_TIMEOUT_S: float = 1.0
+
+# Banner string the installer prints when airgap is detected. Wording
+# is part of the Phase 11 contract (roadmap step-9 line 147) and is
+# asserted by tests/test_airgap_detection.py.
+AIRGAP_BANNER: str = (
+    "airgapped environment detected — defaulting to mode: api"
+)
+
+
+def airgap_banner() -> str:
+    """Return the canonical airgap banner (step-9 P11)."""
+
+    return AIRGAP_BANNER
+
+
+Resolver = Callable[[str], None]
+
+
+def _default_resolver(host: str) -> None:
+    """Resolve ``host`` via ``socket.getaddrinfo``.
+
+    Raises ``socket.gaierror`` / ``OSError`` on failure. The timeout is
+    enforced by the caller via ``socket.setdefaulttimeout`` because
+    ``getaddrinfo`` itself has no ``timeout=`` kwarg.
+    """
+
+    socket.getaddrinfo(host, None)
+
+
+def probe_host(
+    host: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    resolver: Resolver | None = None,
+) -> bool:
+    """Return ``True`` iff ``host`` resolves within ``timeout``.
+
+    Any DNS / socket error is treated as unreachable. Test code can
+    inject ``resolver`` to simulate reachability without touching the
+    network.
+    """
+
+    resolver = resolver or _default_resolver
+    previous = socket.getdefaulttimeout()
+    try:
+        socket.setdefaulttimeout(timeout)
+        try:
+            resolver(host)
+        except (socket.gaierror, OSError):
+            return False
+        return True
+    finally:
+        socket.setdefaulttimeout(previous)
+
+
+def detect_airgap(
+    *,
+    hosts: Iterable[str] = COUNCIL_PROBE_HOSTS,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    resolver: Resolver | None = None,
+) -> bool:
+    """Return ``True`` iff **every** host in ``hosts`` is unreachable.
+
+    A single reachable host is enough to disprove airgap — CLI members
+    only need one provider to be usable. Empty ``hosts`` is treated as
+    airgap by definition (no providers to reach).
+    """
+
+    hosts_list = list(hosts)
+    if not hosts_list:
+        return True
+    for host in hosts_list:
+        if probe_host(host, timeout=timeout, resolver=resolver):
+            return False
+    return True
+
+
+def recommended_member_mode(
+    *,
+    hosts: Iterable[str] = COUNCIL_PROBE_HOSTS,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    resolver: Resolver | None = None,
+) -> str:
+    """Return ``"api"`` when airgapped, ``"cli"`` otherwise.
+
+    Convenience wrapper for the installer: matches the Phase 8 default
+    of ``cli`` and the Phase 11 airgap override of ``api``.
+    """
+
+    return "api" if detect_airgap(
+        hosts=hosts, timeout=timeout, resolver=resolver,
+    ) else "cli"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry-point: print recommended mode + banner if airgapped.
+
+    Used by the installer / first-run wrappers (step-9 P11): probe
+    the three provider hosts and exit ``0`` with the recommended mode
+    on stdout. When airgapped also emit the banner on stderr so the
+    installer can surface it without parsing stdout.
+    """
+
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(
+        description="Detect airgap state and print recommended member_mode."
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT_S,
+        help=f"per-host DNS timeout in seconds (default: {DEFAULT_TIMEOUT_S})",
+    )
+    args = parser.parse_args(argv)
+
+    is_airgapped = detect_airgap(timeout=args.timeout)
+    mode = "api" if is_airgapped else "cli"
+    if is_airgapped:
+        print(AIRGAP_BANNER, file=sys.stderr)
+    print(mode)
+    return 0
+
+
+if __name__ == "__main__":
+    import sys as _sys
+
+    raise SystemExit(main(_sys.argv[1:]))