fix(pantry): clarify version policy rejection wording (#480) (#511)

Reword pantry health messages so dev/prerelease builds read as deliberate
policy rejection instead of parse failure, while preserving the fixed
invalid-version label and never echoing raw version strings.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: solomonneas

docs/technical-guide.md

@@ -1372,6 +1372,7 @@ First-class station CLIs (always registered; not extras-gated):
 
 `pantry` (alias `larder`) is the agent session auth sync station. Agent Pantry remains a process-boundary Go binary; Brigade never imports it.
 `brigade add pantry` installs agentpantry via `go install github.com/escoffier-labs/agentpantry/cmd/agentpantry@latest` and prints the first-class operator path (setup plan, doctor, expiry-alert).
+Before invoking any installed agentpantry surface, Brigade probes `agentpantry version --json` and accepts only released ASCII semver triples (optional leading `v`, no prerelease or build suffix). Dev builds, prerelease tags, and other non-triple strings are rejected by version policy, not because parsing failed. Brigade never echoes the raw rejected version string in `work brief`, doctor output, logs, or receipts; it surfaces a fixed policy message instead.
 `brigade doctor` health-checks it with `agentpantry doctor --json --no-net` and keeps a compatibility fallback to `agentpantry status --json` for older binaries.
 Like the memory satellites, agentpantry inspects host-global state, so its checks are advisory and never FAIL a workspace run: an unwired install (exit 2, no config) is a `WARN`, and setup problems are surfaced as advisory pantry health.
 Use `brigade pantry status` and `brigade pantry doctor` for pantry-specific health with explicit `next` commands, `brigade pantry setup plan --role source|sink` to preview or write a reviewed setup plan, and `brigade pantry service plan --role source|sink` to preview or write service setup steps.

src/brigade/pantry_compat.py

@@ -13,6 +13,14 @@
 probe, malformed JSON, non-string version, prerelease-shaped, or below-floor
 version all collapse to an incompatible :class:`VersionProbe` with a precise
 detail string.
+
+**Version policy:** Brigade accepts only released ASCII semver triples (optional
+leading ``v``, no prerelease or build suffix). Dev builds, prerelease tags,
+unknown labels, and any other non-triple string are rejected deliberately, not
+because parsing failed. Those values collapse to the fixed
+:data:`_INVALID_VERSION_LABEL` in :attr:`VersionProbe.observed` so the raw
+version field never reaches ``work brief``, doctor output, logs, or receipts.
+The surfaced detail explains policy rejection instead of echoing the raw string.
 """
 
 from __future__ import annotations
@@ -97,6 +105,17 @@ def floor_label() -> str:
     return f"expected >= {major}.{minor}.{patch}"
 
 
+def released_floor_label() -> str:
+    """Return the released-build floor expectation, e.g. ``expected released >= 0.5.0``."""
+    major, minor, patch = AGENTPANTRY_MIN_VERSION
+    return f"expected released >= {major}.{minor}.{patch}"
+
+
+def _policy_rejected_detail() -> str:
+    """Detail string when a version string fails the released-semver policy."""
+    return f"agentpantry build rejected by version policy (unreleased or non-semver build); {released_floor_label()}"
+
+
 def parse_version(value: object) -> Optional[Tuple[int, int, int]]:
     """Parse a version value into an integer ``(major, minor, patch)`` triple.
 
@@ -172,10 +191,16 @@ def probe_agentpantry_version() -> VersionProbe:
     parsed = parse_version(raw_version)
     if parsed is None:
         observed = _unparsable_observed_label(raw_version)
+        if observed == _INVALID_VERSION_LABEL:
+            detail = _policy_rejected_detail()
+        elif observed == "missing":
+            detail = f"agentpantry version field missing; {expected}"
+        else:
+            detail = f"agentpantry version field is not a string; {expected}"
         return VersionProbe(
             compatible=False,
             observed=observed,
-            detail=f"agentpantry version unparsable ({observed}); {expected}",
+            detail=detail,
         )
     observed = _format_triple(parsed)
     if parsed < AGENTPANTRY_MIN_VERSION:

tests/test_managed.py

@@ -3,7 +3,7 @@
 
 import pytest
 
-from brigade import managed
+from brigade import managed, pantry_compat
 from brigade import station_manifest
 from brigade import stations_cmd
 from brigade.station import DoctorContext
@@ -296,9 +296,20 @@ def fake_run(args, **kw):
     ctx = DoctorContext(target=Path("/tmp/ws"), selection=None, harnesses=[])
     results = t.doctor(ctx)
     assert all(status != "FAIL" and status != "OK" for status, _, _ in results)
-    assert any(
-        status == "WARN" and "expected >= 0.5.0" in detail and observed in detail for status, _, detail in results
-    ), (version_value, observed, results)
+    if observed == "invalid-version":
+        assert any(
+            status == "WARN"
+            and "rejected by version policy" in detail
+            and pantry_compat.released_floor_label() in detail
+            for status, _, detail in results
+        ), (version_value, observed, results)
+    else:
+        assert any(
+            status == "WARN"
+            and "expected >= 0.5.0" in detail
+            and (observed in detail if observed != "non-string" else "is not a string" in detail)
+            for status, _, detail in results
+        ), (version_value, observed, results)
     # The raw invalid version field must not leak into any surfaced doctor detail.
     raw = "" if version_value is None else str(version_value)
     if raw:
@@ -321,7 +332,7 @@ def fake_run(args, **kw):
     results = t.doctor(ctx)
     assert all(status != "FAIL" and status != "OK" for status, _, _ in results)
     assert any(
-        status == "WARN" and "invalid-version" in detail and "expected >= 0.5.0" in detail
+        status == "WARN" and "rejected by version policy" in detail and pantry_compat.released_floor_label() in detail
         for status, _, detail in results
     ), results
     assert all(secret not in detail for _, _, detail in results), results

tests/test_pantry_cmd.py

@@ -1,6 +1,6 @@
 import json
 
-from brigade import center_cmd, pantry_cmd, work_cmd
+from brigade import center_cmd, pantry_cmd, pantry_compat, work_cmd
 
 
 def test_pantry_status_reports_uninstalled(monkeypatch, tmp_path):
@@ -193,6 +193,24 @@ def test_work_brief_includes_pantry_health(monkeypatch, tmp_path):
     assert payload["pantry"]["summary"] == "pantry test summary"
 
 
+def test_work_brief_surfaces_pantry_policy_rejection_without_leak(monkeypatch, tmp_path, capsys):
+    _pantry_installed(monkeypatch)
+
+    def fake_run(args, **kw):
+        assert args == ["agentpantry", "version", "--json"]
+        return pantry_cmd.proc.Result(code=0, stdout='{"version": "dev"}', stderr="")
+
+    monkeypatch.setattr(pantry_cmd.proc, "run", fake_run)
+
+    assert work_cmd.brief(target=tmp_path) == 0
+    out = capsys.readouterr().out
+    pantry_line = next(line for line in out.splitlines() if line.startswith("pantry: "))
+    assert "agentpantry build rejected by version policy" in pantry_line
+    assert pantry_compat.released_floor_label() in pantry_line
+    assert "unparsable" not in pantry_line
+    assert "dev" not in pantry_line
+
+
 def test_center_status_includes_pantry_health(monkeypatch, tmp_path):
     monkeypatch.setattr(
         pantry_cmd, "status_payload", lambda target: {"installed": False, "summary": "pantry center summary"}
@@ -301,8 +319,8 @@ def fake_run(args, **kw):
     # An unparsable version string collapses to the fixed sanitized label and
     # never leaks the raw value into the surfaced pantry payload.
     assert payload["version"] == "invalid-version"
-    assert "expected >= 0.5.0" in payload["summary"]
-    assert "invalid-version" in payload["summary"]
+    assert "rejected by version policy" in payload["summary"]
+    assert pantry_compat.released_floor_label() in payload["summary"]
     assert "dev" not in payload["summary"]
     assert "dev" not in payload["version"]
     assert calls == [["agentpantry", "version", "--json"]]
@@ -324,7 +342,7 @@ def fake_run(args, **kw):
     assert payload["version"] == "invalid-version"
     assert secret not in payload["version"]
     assert secret not in payload["summary"]
-    assert "invalid-version" in payload["summary"]
+    assert "rejected by version policy" in payload["summary"]
 
 
 def test_pantry_status_unhealthy_on_missing_version_field(monkeypatch, tmp_path):

tests/test_pantry_compat.py

@@ -114,27 +114,28 @@ def test_probe_incompatible_on_non_string_version(monkeypatch):
     assert probe.compatible is False
     assert probe.observed == "non-string"
     assert "expected >= 0.5.0" in probe.detail
-    assert "non-string" in probe.detail
+    assert "is not a string" in probe.detail
 
 
 @pytest.mark.parametrize("version", ["dev", "unknown", "0.5.0-dev", "0.5.0-rc.1", "0.5", ""])
 def test_probe_incompatible_on_unparsable_string_versions(monkeypatch, version):
     probe = _probe(monkeypatch, stdout=json.dumps({"version": version}))
     assert probe.compatible is False
-    assert "expected >= 0.5.0" in probe.detail
+    assert probe.observed == "invalid-version"
+    assert "rejected by version policy" in probe.detail
+    assert "unreleased or non-semver build" in probe.detail
+    assert pantry_compat.released_floor_label() in probe.detail
+    assert "unparsable" not in probe.detail
     # Any unparsable string collapses to the fixed sanitized label; the raw
     # invalid version field never reaches observed or detail.
-    assert probe.observed == "invalid-version"
-    # The raw value must not leak (skip the substring check for the empty
-    # string, which is vacuously a substring of every string).
     if version:
         assert version not in probe.observed
-        # detail always carries the fixed safe floor text, so a raw value that
-        # overlaps the floor (e.g. "0.5" is a substring of "expected >= 0.5.0")
-        # would make a bare substring assertion vacuously fail. Strip the fixed
-        # floor text first; the raw invalid field must not appear in the
-        # remainder, which still proves no raw content leaks.
-        assert version not in probe.detail.replace(pantry_compat.floor_label(), "")
+        # detail carries the fixed safe floor text, so a raw value that
+        # overlaps the floor (e.g. "0.5" is a substring of "expected released
+        # >= 0.5.0") would make a bare substring assertion vacuously fail.
+        # Strip the fixed floor text first; the raw invalid field must not
+        # appear in the remainder, which still proves no raw content leaks.
+        assert version not in probe.detail.replace(pantry_compat.released_floor_label(), "")
 
 
 def test_probe_unparsable_secret_version_field_never_leaks(monkeypatch):
@@ -146,6 +147,7 @@ def test_probe_unparsable_secret_version_field_never_leaks(monkeypatch):
     assert probe.observed == "invalid-version"
     assert secret not in probe.observed
     assert secret not in probe.detail
+    assert "rejected by version policy" in probe.detail
 
 
 def test_probe_unparsable_version_field_never_leaks_other_stdout(monkeypatch):
@@ -161,6 +163,7 @@ def test_probe_unparsable_version_field_never_leaks_other_stdout(monkeypatch):
     assert "/home/user/private" not in probe.detail
     assert "prerelease" not in probe.observed
     assert "prerelease" not in probe.detail
+    assert "rejected by version policy" in probe.detail
 
 
 def test_probe_below_floor_still_exposes_normalized_semver(monkeypatch):
@@ -240,7 +243,7 @@ def test_probe_oversized_segment_collapses_to_invalid_version_label(monkeypatch)
     assert huge not in probe.detail
     assert raw_version not in probe.observed
     assert raw_version not in probe.detail
-    assert "expected >= 0.5.0" in probe.detail
+    assert pantry_compat.released_floor_label() in probe.detail
 
 
 def test_probe_non_ascii_digit_version_collapses_to_invalid_version_label(monkeypatch):
@@ -252,7 +255,7 @@ def test_probe_non_ascii_digit_version_collapses_to_invalid_version_label(monkey
     assert probe.observed == "invalid-version"
     assert raw_version not in probe.observed
     assert raw_version not in probe.detail
-    assert "expected >= 0.5.0" in probe.detail
+    assert pantry_compat.released_floor_label() in probe.detail
 
 
 def test_probe_oversized_segment_never_leaks_other_stdout(monkeypatch):