@event4u/agent-config 1.12.0 → 1.14.0

package/.agent-src/templates/scripts/memory_lookup.py

@@ -1,21 +1,28 @@
 #!/usr/bin/env python3
-"""File-based retrieval for the `absent` path.
+"""Hybrid retrieval — file-first with optional package augmentation.
 
 Implements the shared `retrieve(types, keys, limit)` abstraction used
 by skills. Reads YAML under `agents/memory/<type>/` (curated, hand-
 reviewed) and JSONL under `agents/memory/intake/*.jsonl` (agent-written,
 append-only, supersede-chain aware).
 
-The returned shape is identical to the `present`-path adapter over the
-`@event4u/agent-memory` API, so skills stay backend-agnostic.
+When the `@event4u/agent-memory` package is present (see
+`scripts/memory_status.py`), callers can pass the result of
+:func:`package_operational_provider` to route additional retrieval
+through the package's semantic CLI. Repo entries always win on
+conflict — see `_apply_conflict_rule`.
 
 Usage:
     python3 scripts/memory_lookup.py --types domain-invariants,ownership \\
         --key "app/Http/Controllers/Foo" --limit 5
     python3 scripts/memory_lookup.py --types incident-learnings --format json
+    python3 scripts/memory_lookup.py --types ownership --key billing --auto
 
-    from scripts.memory_lookup import retrieve
-    hits = retrieve(types=["ownership"], keys=["app/Http"], limit=3)
+    from scripts.memory_lookup import retrieve, package_operational_provider
+    hits = retrieve(
+        types=["ownership"], keys=["app/Http"], limit=3,
+        operational_provider=package_operational_provider(),
+    )
 """
 
 from __future__ import annotations
@@ -23,10 +30,12 @@ from __future__ import annotations
 import argparse
 import fnmatch
 import json
+import os
+import subprocess
 import sys
 from dataclasses import dataclass, asdict, field
 from pathlib import Path
-from typing import Any, Iterable
+from typing import Any, Callable, Iterable, Optional, Union
 
 MEMORY_ROOT = Path("agents/memory")
 INTAKE_ROOT = MEMORY_ROOT / "intake"
@@ -45,8 +54,8 @@ CURATED_TYPES = {
 class Hit:
     id: str
     type: str
-    source: str            # "curated" or "intake"
-    path: str              # file that produced the hit
+    source: str            # "curated" | "intake" | "operational"
+    path: str              # file (or logical locator) that produced the hit
     score: float           # naive, content-match based [0..1]
     entry: dict = field(default_factory=dict)
 
@@ -54,6 +63,38 @@ class Hit:
         return asdict(self)
 
 
+@dataclass
+class Shadow:
+    """An operational entry suppressed by the conflict rule."""
+    id: str
+    type: str
+    reason: str                    # "same-id" | "repo-deprecated"
+    operational_path: str          # where the suppressed entry came from
+    repo_path: str                 # repo entry that shadowed it
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class RetrievalResult:
+    """Full retrieval payload with conflict-rule observability."""
+    hits: list
+    shadows: list = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return {
+            "hits": [h.as_dict() for h in self.hits],
+            "shadows": [s.as_dict() for s in self.shadows],
+        }
+
+
+# An operational provider returns repo-shaped Hit objects with
+# source="operational". Backend adapters (e.g. @event4u/agent-memory)
+# are expected to translate their native payload into this shape.
+OperationalProvider = Callable[[list[str], list[str]], Iterable[Hit]]
+
+
 def _load_yaml(path: Path):
     try:
         import yaml
@@ -152,19 +193,195 @@ def _score(entry: dict, keys: list[str]) -> float:
     return best
 
 
-def retrieve(types: list[str], keys: list[str], limit: int = 5) -> list[Hit]:
+def _apply_conflict_rule(
+    repo_hits: list[Hit],
+    operational_hits: list[Hit],
+) -> tuple[list[Hit], list[Shadow]]:
+    """Enforce REPO WINS / OPERATIONAL AUGMENTS / NEVER CONTRADICTS SILENTLY.
+
+    Reference: `agents/roadmaps/road-to-memory-self-consumption.md` §
+    "Conflict rule: repo vs. operational". The four cases mapped below
+    are covered by `tests/test_conflict_rule.py`.
+    """
+    # Repo entries index — curated AND intake both count as "repo" for
+    # the conflict rule. The operational store is the only non-repo side.
+    repo_by_id: dict[str, Hit] = {h.id: h for h in repo_hits if h.id}
+
+    merged: list[Hit] = list(repo_hits)
+    shadows: list[Shadow] = []
+
+    for op in operational_hits:
+        if op.id and op.id in repo_by_id:
+            # Case 1+2: same id → repo wins (including when repo is
+            # status:deprecated — operational cannot revive a retired
+            # entry). Suppress the operational entry and record shadow.
+            repo = repo_by_id[op.id]
+            reason = (
+                "repo-deprecated"
+                if repo.entry.get("status") == "deprecated"
+                else "same-id"
+            )
+            shadows.append(Shadow(
+                id=op.id,
+                type=op.type,
+                reason=reason,
+                operational_path=op.path,
+                repo_path=repo.path,
+            ))
+            continue
+        # Case 3 (different ids on same logical key) and Case 4 (repo
+        # has no entry) — both simply include the operational hit.
+        # Repo entries naturally rank higher because their score is not
+        # discounted (see _score / operational scoring in retrieve()).
+        merged.append(op)
+
+    return merged, shadows
+
+
+# ---------------------------------------------------------------------------
+# Package-backed operational provider (the `present` path)
+# ---------------------------------------------------------------------------
+#
+# When `memory_status.status() == "present"` the consumer-facing contract
+# says retrieval should route through `@event4u/agent-memory`. The package
+# CLI is purely **semantic** (`memory retrieve <query> --type T …`); the
+# shared `retrieve(types, keys, …)` API is **key-based**. The hybrid
+# resolution agreed in `agents/contexts/agent-memory-contract.md` synthesises
+# `keys` into a single natural-language query for the package call, while
+# the file fallback continues to do glob/substring matching on the same
+# keys. Both legs land in the same `Hit` shape so the conflict rule can
+# merge them transparently.
+
+_CLI_TIMEOUT_SECONDS = 5.0
+_CLI_RETRIEVE_LIMIT_DEFAULT = 20
+
+
+def _synthesize_query(keys: list[str]) -> str:
+    """Turn a list of retrieval keys into one natural-language query.
+
+    Keys are typically file paths (`app/Http/Controllers/Foo`), feature
+    names (`billing`), or short identifiers — joining them with spaces
+    gives the package's semantic search enough surface to score against
+    without inventing structure. Empty or whitespace-only keys are
+    dropped; if nothing remains the caller falls back to the file path.
+    """
+    cleaned = [k.strip() for k in keys if isinstance(k, str) and k.strip()]
+    return " ".join(cleaned)
+
+
+def _cli_operational_provider(
+    types: list[str],
+    keys: list[str],
+    *,
+    cli_path: str = "memory",
+    timeout: float = _CLI_TIMEOUT_SECONDS,
+    limit: int = _CLI_RETRIEVE_LIMIT_DEFAULT,
+) -> Iterable[Hit]:
+    """Run `memory retrieve` and yield operational `Hit` objects.
+
+    Pino structured logs from the package go to stderr; stdout is a
+    clean v1 retrieval envelope. Any non-zero exit, timeout, or parse
+    failure degrades to "no operational hits" — `retrieve()` already
+    treats provider exceptions as a soft warning, so the caller still
+    gets the file-fallback result.
+    """
+    query = _synthesize_query(keys)
+    if not query:
+        return
+    cmd: list[str] = [cli_path, "retrieve", query, "--limit", str(limit)]
+    for t in types:
+        cmd.extend(["--type", t])
+    try:
+        out = subprocess.run(
+            cmd,
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return
+    if out.returncode != 0:
+        return
+    try:
+        envelope = json.loads(out.stdout)
+    except (ValueError, TypeError):
+        return
+    entries = envelope.get("entries") if isinstance(envelope, dict) else None
+    if not isinstance(entries, list):
+        return
+    for e in entries:
+        if not isinstance(e, dict):
+            continue
+        eid = e.get("id")
+        etype = e.get("type")
+        if not isinstance(eid, str) or not isinstance(etype, str):
+            continue
+        # The package returns `confidence` (0..1) per the v1 envelope;
+        # map it onto our internal `score` field so the conflict rule
+        # and ranking work uniformly across providers.
+        try:
+            score = float(e.get("confidence", 0.0))
+        except (TypeError, ValueError):
+            score = 0.0
+        body = e.get("body") if isinstance(e.get("body"), dict) else {}
+        yield Hit(
+            id=eid,
+            type=etype,
+            source="operational",
+            path=f"agent-memory:{eid}",
+            score=score,
+            entry=body,
+        )
+
+
+def package_operational_provider() -> Optional[OperationalProvider]:
+    """Return a CLI-backed provider when the package is `present`, else None.
+
+    Callers who want automatic backend routing pass the result directly
+    to :func:`retrieve` — `None` is a safe value that yields file-only
+    retrieval, so this is the recommended one-liner for skills:
+
+        retrieve(types, keys, operational_provider=package_operational_provider())
+
+    The status probe is bounded (≤ 2s, cached per process) — see
+    `scripts/memory_status.py`. We import lazily so pure file-fallback
+    callers never pay for the probe.
+    """
+    # Late import: keeps `memory_lookup` importable even when
+    # `memory_status` is missing in stripped consumer installs.
+    try:
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import memory_status  # type: ignore[import-not-found]
+    except ImportError:
+        return None
+    if memory_status.status().status != "present":
+        return None
+    return _cli_operational_provider
+
+
+def retrieve(
+    types: list[str],
+    keys: list[str],
+    limit: int = 5,
+    operational_provider: Optional[OperationalProvider] = None,
+    with_shadows: bool = False,
+) -> Union[list[Hit], RetrievalResult]:
     """Return up to `limit` hits across the requested types, highest score first.
 
-    Curated entries are preferred on ties — they are hand-reviewed.
-    The shape (`Hit`) matches the `present` backend adapter so skills
-    can treat both sources identically.
+    Repo entries (curated + intake) are preferred on ties — they are
+    hand-reviewed or session-captured against the repo itself. When an
+    `operational_provider` is supplied (the `present` path of the
+    backend-detection contract), its results are merged under the
+    REPO WINS conflict rule; suppressed operational entries surface as
+    `shadows` when `with_shadows=True`.
+
+    The return type stays `list[Hit]` by default for backward
+    compatibility with existing skill call sites.
     """
-    hits: list[Hit] = []
+    repo_hits: list[Hit] = []
     for mtype in types:
         if mtype not in CURATED_TYPES:
             continue
         for path, entry in _iter_curated_entries(mtype):
-            hits.append(Hit(
+            repo_hits.append(Hit(
                 id=str(entry.get("id", "")),
                 type=mtype,
                 source="curated",
@@ -173,7 +390,7 @@ def retrieve(types: list[str], keys: list[str], limit: int = 5) -> list[Hit]:
                 entry=entry,
             ))
         for path, entry in _iter_intake_entries(mtype):
-            hits.append(Hit(
+            repo_hits.append(Hit(
                 id=str(entry.get("id", "")),
                 type=mtype,
                 source="intake",
@@ -181,10 +398,122 @@ def retrieve(types: list[str], keys: list[str], limit: int = 5) -> list[Hit]:
                 score=_score(entry, keys) * 0.9,  # slight discount vs curated
                 entry=entry,
             ))
-    hits.sort(key=lambda h: (h.score, h.source == "curated"), reverse=True)
-    # Drop zero-score hits unless no better option exists.
-    positives = [h for h in hits if h.score > 0]
-    return (positives or hits)[:limit]
+
+    operational_hits: list[Hit] = []
+    if operational_provider is not None:
+        try:
+            for oh in operational_provider(list(types), list(keys)) or []:
+                # Discount operational vs curated/intake so repo ranks
+                # higher on equal relevance. Providers may already return
+                # trust-adjusted scores; we only apply a floor discount.
+                oh.score = min(oh.score, 0.85)
+                operational_hits.append(oh)
+        except Exception as exc:  # noqa: BLE001 — providers are external
+            print(f"warning: operational_provider raised "
+                  f"{exc.__class__.__name__}: {exc}", file=sys.stderr)
+
+    merged, shadows = _apply_conflict_rule(repo_hits, operational_hits)
+    merged.sort(key=lambda h: (h.score, h.source == "curated"), reverse=True)
+    positives = [h for h in merged if h.score > 0]
+    final_hits = (positives or merged)[:limit]
+
+    if with_shadows:
+        return RetrievalResult(hits=final_hits, shadows=shadows)
+    return final_hits
+
+
+CONTRACT_VERSION = 1
+
+# Memory types this file-backed backend can answer. Types outside this
+# set map to `unknown_type` per the retrieval contract.
+_KNOWN_TYPES = CURATED_TYPES
+
+
+def retrieve_v1(
+    types: list[str],
+    keys: list[str],
+    limit: int = 20,
+    operational_provider: Optional[OperationalProvider] = None,
+) -> dict:
+    """Return a v1 retrieval-contract envelope.
+
+    Wraps :func:`retrieve` and projects the internal ``Hit`` shape into
+    the shape defined by
+    ``schemas/retrieval-v1.schema.json``. Unknown types are reported as
+    ``status: unknown_type`` for that slice only, rather than failing
+    the whole call.
+    """
+    known = [t for t in types if t in _KNOWN_TYPES]
+    unknown = [t for t in types if t not in _KNOWN_TYPES]
+
+    result = retrieve(known, keys, limit=limit,
+                      operational_provider=operational_provider,
+                      with_shadows=True)
+    assert isinstance(result, RetrievalResult)
+    hits, shadows = result.hits, result.shadows
+    shadow_by_id = {s.id: s for s in shadows if s.id}
+
+    slice_counts: dict[str, int] = {t: 0 for t in known}
+    entries: list[dict] = []
+    for h in hits:
+        source = "operational" if h.source == "operational" else "repo"
+        envelope_entry: dict = {
+            "id": h.id,
+            "type": h.type,
+            "source": source,
+            "confidence": round(float(h.score), 4),
+            "body": dict(h.entry) if isinstance(h.entry, dict) else {},
+            "shadowed_by": None,
+        }
+        if h.type in slice_counts:
+            slice_counts[h.type] += 1
+        entries.append(envelope_entry)
+
+    # Surface shadowed operational entries as additional entries carrying
+    # `shadowed_by`. The conformance harness checks that only
+    # source="operational" entries ever set this field.
+    for sid, s in shadow_by_id.items():
+        entries.append({
+            "id": sid,
+            "type": s.type,
+            "source": "operational",
+            "confidence": 0.0,
+            "body": {},
+            "shadowed_by": f"repo:{sid}",
+        })
+        if s.type in slice_counts:
+            slice_counts[s.type] += 1
+
+    slices: dict[str, dict] = {
+        t: {"status": "ok", "count": slice_counts.get(t, 0)}
+        for t in known
+    }
+    errors: list[dict] = []
+    for t in unknown:
+        slices[t] = {"status": "unknown_type", "count": 0}
+        errors.append({
+            "type": t,
+            "code": "unknown_type",
+            "message": f"file-backed backend does not know type {t!r}",
+        })
+
+    oks = [s for s in slices.values() if s["status"] == "ok"]
+    fails = [s for s in slices.values() if s["status"] != "ok"]
+    envelope_status = (
+        "ok" if not fails
+        else "error" if not oks
+        else "partial"
+    )
+
+    envelope: dict = {
+        "contract_version": CONTRACT_VERSION,
+        "status": envelope_status,
+        "entries": entries,
+        "slices": slices,
+    }
+    if errors:
+        envelope["errors"] = errors
+    return envelope
 
 
 def main() -> int:
@@ -195,20 +524,52 @@ def main() -> int:
                     help="Retrieval key (repeatable)")
     ap.add_argument("--limit", type=int, default=5)
     ap.add_argument("--format", choices=["text", "json"], default="text")
+    ap.add_argument("--envelope", choices=["legacy", "v1"], default="legacy",
+                    help="Output shape: `legacy` (Hit list) or `v1` "
+                         "(retrieval contract v1 envelope). `v1` implies JSON output.")
+    ap.add_argument("--with-shadows", action="store_true",
+                    help="Include shadowed-operational entries in the output "
+                         "(no-op until an operational backend is wired)")
+    ap.add_argument("--auto", action="store_true",
+                    help="Auto-route to the @event4u/agent-memory package "
+                         "when memory_status.status() == 'present'; "
+                         "falls through to file-only retrieval otherwise")
     args = ap.parse_args()
     types = [t.strip() for t in args.types.split(",") if t.strip()]
     if not types:
         print("error: --types is required", file=sys.stderr)
         return 2
-    hits = retrieve(types, args.key, args.limit)
+    op_provider = package_operational_provider() if args.auto else None
+    if args.envelope == "v1":
+        envelope = retrieve_v1(types, args.key, args.limit,
+                               operational_provider=op_provider)
+        print(json.dumps(envelope, indent=2, default=str))
+        return 0
+    result = retrieve(types, args.key, args.limit,
+                      operational_provider=op_provider,
+                      with_shadows=args.with_shadows)
+    if args.with_shadows:
+        assert isinstance(result, RetrievalResult)
+        hits, shadows = result.hits, result.shadows
+    else:
+        hits, shadows = result, []  # type: ignore[assignment]
     if args.format == "json":
-        print(json.dumps([h.as_dict() for h in hits], indent=2, default=str))
+        payload = {"hits": [h.as_dict() for h in hits],
+                   "shadows": [s.as_dict() for s in shadows]}
+        print(json.dumps(payload, indent=2, default=str))
     else:
         if not hits:
             print("  (no hits)")
         for h in hits:
             print(f"  [{h.source}] {h.type}  score={h.score:.2f}  "
                   f"id={h.id or '-'}  path={h.path}")
+        if shadows:
+            print(f"\n  shadows: {len(shadows)} operational entr"
+                  f"{'y' if len(shadows) == 1 else 'ies'} suppressed by "
+                  f"the conflict rule")
+            for s in shadows:
+                print(f"    [{s.reason}] {s.type}  id={s.id}  "
+                      f"op={s.operational_path}  repo={s.repo_path}")
     return 0
 
 

package/.agent-src/templates/scripts/memory_status.py

@@ -35,11 +35,17 @@ from typing import Literal
 
 Status = Literal["absent", "misconfigured", "present"]
 
-_CLI_CANDIDATES = ("agent-memory", "agentmem")
+_CLI_CANDIDATES = ("memory", "agent-memory", "agentmem")
 _HEALTH_TIMEOUT_SECONDS = 2.0
 _CACHE_ENV = "AGENT_MEMORY_STATUS"
 _CACHE_FILE = Path(".agent-memory") / "status.cache"
 
+# Retrieval contract version served by the file-backed fallback.
+# Source of truth: schemas/retrieval-v1.schema.json.
+CONTRACT_VERSION = 1
+_FILE_BACKEND_VERSION = "0.0.0-file"
+_FILE_BACKEND_FEATURES = ("file-fallback",)
+
 
 @dataclass
 class Result:
@@ -48,6 +54,11 @@ class Result:
     reason: str             # short explanation
     elapsed_ms: int         # time spent probing (0 if cached)
     cli_path: str = ""      # resolved CLI path, if any
+    # Populated only when status == "present" — sourced from the
+    # `health` CLI envelope so the v1 health() reports real package
+    # capabilities instead of file-fallback placeholders.
+    backend_version: str = ""
+    features: tuple = ()
 
 
 def _find_cli() -> str:
@@ -58,8 +69,45 @@ def _find_cli() -> str:
     return ""
 
 
-def _probe_health(cli_path: str) -> tuple[bool, str]:
-    """Returns (healthy, reason)."""
+def _parse_health_envelope(stdout: str) -> dict | None:
+    """Extract the v1 health envelope from `memory health` stdout.
+
+    The package emits a single JSON object on stdout (pino structured
+    logs go to stderr). We tolerate older builds that may have leaked
+    log lines into stdout by scanning for the first top-level object
+    that carries ``contract_version``.
+    """
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    try:
+        obj = json.loads(text)
+    except ValueError:
+        obj = None
+    if isinstance(obj, dict) and obj.get("contract_version"):
+        return obj
+    # Fallback: line-by-line scan for an envelope-shaped object — covers
+    # the case where structured logs accidentally share stdout.
+    for line in text.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            cand = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(cand, dict) and cand.get("contract_version"):
+            return cand
+    return None
+
+
+def _probe_health(cli_path: str) -> tuple[bool, str, dict | None]:
+    """Returns (healthy, reason, envelope).
+
+    On success ``envelope`` is the parsed v1 health envelope (may still
+    be ``None`` for very old CLIs that don't emit one). On failure it
+    is always ``None``.
+    """
     try:
         out = subprocess.run(
             [cli_path, "health"],
@@ -67,15 +115,16 @@ def _probe_health(cli_path: str) -> tuple[bool, str]:
             timeout=_HEALTH_TIMEOUT_SECONDS,
         )
     except subprocess.TimeoutExpired:
-        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s"
+        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s", None
     except FileNotFoundError:
-        return False, "CLI vanished between which() and invoke"
+        return False, "CLI vanished between which() and invoke", None
     if out.returncode != 0:
         # First line of combined output, capped, for the reason field.
         msg = (out.stderr or out.stdout or "exit != 0").strip().splitlines()
         head = msg[0][:120] if msg else "exit != 0"
-        return False, f"health() returned {out.returncode}: {head}"
-    return True, "ok"
+        return False, f"health() returned {out.returncode}: {head}", None
+    envelope = _parse_health_envelope(out.stdout)
+    return True, "ok", envelope
 
 
 def _read_cache() -> Result | None:
@@ -125,22 +174,74 @@ def status(refresh: bool = False) -> Result:
         result = Result("absent", "file",
                         "agent-memory CLI not on PATH", 0)
     else:
-        healthy, reason = _probe_health(cli)
+        healthy, reason, envelope = _probe_health(cli)
         elapsed = int((time.monotonic() - t0) * 1000)
         if healthy:
-            result = Result("present", "package", reason, elapsed, cli)
+            backend_version = ""
+            features: tuple = ()
+            if isinstance(envelope, dict):
+                bv = envelope.get("backend_version")
+                if isinstance(bv, str):
+                    backend_version = bv
+                feats = envelope.get("features")
+                if isinstance(feats, list) and all(
+                    isinstance(f, str) for f in feats
+                ):
+                    features = tuple(feats)
+            result = Result("present", "package", reason, elapsed, cli,
+                            backend_version=backend_version,
+                            features=features)
         else:
             result = Result("misconfigured", "file", reason, elapsed, cli)
     _write_cache(result)
     return result
 
 
+def health(refresh: bool = False) -> dict:
+    """Return a v1 retrieval-contract health envelope.
+
+    Schema: ``schemas/retrieval-v1.schema.json`` (HealthResponse).
+    Maps the three-state :func:`status` result onto the contract's
+    ``ok | degraded | error`` so consumers can read
+    ``contract_version`` without caring about the file-vs-package split.
+
+    When the package backs the call (``status == "present"``), the
+    envelope reports the package's own ``backend_version`` and
+    ``features`` so consumers can feature-detect against real
+    capabilities. Otherwise the file-fallback markers are returned.
+    """
+    r = status(refresh=refresh)
+    envelope_status = {
+        "present": "ok",
+        "misconfigured": "degraded",
+        "absent": "ok",
+    }[r.status]
+    if r.status == "present" and (r.backend_version or r.features):
+        backend_version = r.backend_version or _FILE_BACKEND_VERSION
+        features = list(r.features) if r.features else list(_FILE_BACKEND_FEATURES)
+    else:
+        backend_version = _FILE_BACKEND_VERSION
+        features = list(_FILE_BACKEND_FEATURES)
+    return {
+        "contract_version": CONTRACT_VERSION,
+        "status": envelope_status,
+        "backend_version": backend_version,
+        "features": features,
+    }
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__)
     ap.add_argument("--format", choices=["text", "json"], default="text")
     ap.add_argument("--refresh", action="store_true",
                     help="Bypass the session cache and probe fresh")
+    ap.add_argument("--health", action="store_true",
+                    help="Emit a v1 retrieval-contract health envelope "
+                         "instead of the legacy status line")
     args = ap.parse_args()
+    if args.health:
+        print(json.dumps(health(refresh=args.refresh)))
+        return 0
     r = status(refresh=args.refresh)
     if args.format == "json":
         print(json.dumps(asdict(r)))