@heretek-ai/epistemic-swarm 0.4.7 → 0.4.8

package/plugins/research-cache/skills/research_cache/hasher.py

@@ -14,10 +14,14 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, Any, Optional, Tuple
 
+DEFAULT_RESEARCH_DIR = ".research"
+BASE_DIR_HELP = "Base .research directory"
+
 class SourceHasher:
     def __init__(self, base_dir: Optional[Path] = None):
-        self.base_dir = base_dir or Path(".research")
-        self.sources_dir = self.base_dir / "sources"
+        target = base_dir or Path(DEFAULT_RESEARCH_DIR)
+        self.base_dir = Path(os.path.realpath(str(target)))
+        self.sources_dir = Path(os.path.realpath(str(self.base_dir / "sources")))
         self.sources_dir.mkdir(parents=True, exist_ok=True)
 
     @staticmethod
@@ -70,15 +74,28 @@ class SourceHasher:
         return None
 
     def _resolve_hash_file(self, hash_prefix: str, extension: str) -> Optional[Path]:
-        """Resolves exact or prefix hash to disk path."""
-        exact_path = self.sources_dir / f"{hash_prefix}{extension}"
+        """Resolves exact or prefix hash to disk path.
+
+        ``hash_prefix`` is untrusted (it arrives from an LLM tool call), so the
+        result is required to stay inside ``sources_dir``. Containment is checked
+        inline rather than via ``runner.path_safety`` because this module is
+        mirrored into the standalone ``research-cache`` plugin, which has no
+        ``runner`` package on its path.
+        """
+        if not re.match(r"^[a-fA-F0-9]+$", hash_prefix):
+            return None
+        exact_path = Path(os.path.realpath(str(self.sources_dir / f"{hash_prefix}{extension}")))
+        if exact_path.parent != self.sources_dir:
+            return None
         if exact_path.exists():
             return exact_path
 
         # If prefix match
         matches = list(self.sources_dir.glob(f"{hash_prefix}*{extension}"))
         if len(matches) == 1:
-            return matches[0]
+            candidate = Path(os.path.realpath(str(matches[0])))
+            if candidate.parent == self.sources_dir:
+                return candidate
         return None
 
     @staticmethod
@@ -143,20 +160,21 @@ def main():
     cache_parser.add_argument("--title", default="Untitled", help="Document Title")
     cache_parser.add_argument("--tier", default="WEB_DOCUMENT", help="Source tier")
     cache_parser.add_argument("--content", help="Raw text content (or read from stdin)")
-    cache_parser.add_argument("--dir", default=".research", help="Base .research directory")
+    cache_parser.add_argument("--dir", default=DEFAULT_RESEARCH_DIR, help=BASE_DIR_HELP)
 
     # Verify command
     verify_parser = subparsers.add_parser("verify", help="Verify a verbatim quote")
     verify_parser.add_argument("--hash", required=True, help="Document SHA-256 hash")
     verify_parser.add_argument("--quote", required=True, help="Verbatim quote to check")
-    verify_parser.add_argument("--dir", default=".research", help="Base .research directory")
+    verify_parser.add_argument("--dir", default=DEFAULT_RESEARCH_DIR, help=BASE_DIR_HELP)
 
     # List command
     list_parser = subparsers.add_parser("list", help="List cached sources")
-    list_parser.add_argument("--dir", default=".research", help="Base .research directory")
+    list_parser.add_argument("--dir", default=DEFAULT_RESEARCH_DIR, help=BASE_DIR_HELP)
 
     args = parser.parse_args()
-    hasher = SourceHasher(base_dir=Path(args.dir if hasattr(args, "dir") else ".research"))
+    dir_val = getattr(args, "dir", DEFAULT_RESEARCH_DIR) or DEFAULT_RESEARCH_DIR
+    hasher = SourceHasher(base_dir=Path(os.path.realpath(str(dir_val))))
 
     if args.command == "cache":
         content = args.content

package/plugins/socratic-grilling/skills/grilling/socratic_tree.py

@@ -5,6 +5,7 @@ Implements Matt Pocock-style design tree traversal to isolate the active decisio
 """
 
 import sys
+import os
 import json
 import argparse
 from pathlib import Path
@@ -84,7 +85,8 @@ class DesignTree:
         return len(self.compute_frontier()) == 0 and all(n.is_settled() for n in self.nodes.values())
 
     def export_frontier_json(self, output_path: Path):
-        output_path.parent.mkdir(parents=True, exist_ok=True)
+        safe_path = Path(os.path.realpath(str(output_path)))
+        safe_path.parent.mkdir(parents=True, exist_ok=True)
         data = {
             "objective": self.objective,
             "is_complete": self.is_complete(),
@@ -93,12 +95,13 @@ class DesignTree:
                 k: v.settled_answer for k, v in self.nodes.items() if v.is_settled()
             }
         }
-        with open(output_path, "w", encoding="utf-8") as f:
+        with open(safe_path, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
 
     @classmethod
     def load_from_json(cls, file_path: Path) -> 'DesignTree':
-        with open(file_path, "r", encoding="utf-8") as f:
+        safe_path = Path(os.path.realpath(str(file_path)))
+        with open(safe_path, "r", encoding="utf-8") as f:
             data = json.load(f)
         tree = cls(objective=data["objective"])
         for k, v in data.get("nodes", {}).items():
@@ -106,15 +109,31 @@ class DesignTree:
         return tree
 
 
+def _display_frontier(tree: DesignTree, frontier: list) -> None:
+    print(f"\n🎯 Objective: {tree.objective}")
+    print(f"📊 Total Nodes: {len(tree.nodes)} | Settled: {sum(1 for n in tree.nodes.values() if n.is_settled())}")
+    if not frontier:
+        if tree.nodes and tree.is_complete():
+            print("✅ Frontier is EMPTY. All prerequisite branches are fully settled!")
+        else:
+            print("ℹ️ No active frontier nodes. Define new decision nodes to begin grilling.")
+    else:
+        print(f"\n⚡ Current Active Frontier ({len(frontier)} questions ready):")
+        for idx, node in enumerate(frontier, 1):
+            print(f"\n❓ Q{idx} [{node.node_id}] - {node.title}")
+            print(f"   {node.question}")
+            print(f"   ➡️ Recommended: {node.recommended}")
+
+
 def main():
     parser = argparse.ArgumentParser(description="Epistemic Swarm Socratic Decision Tree")
     parser.add_argument("--objective", type=str, help="Research objective")
     parser.add_argument("--file", type=str, default=".research/frontier.json", help="Path to frontier.json")
     parser.add_argument("--show-frontier", action="store_true", help="Print the current decision frontier")
     parser.add_argument("--settle", nargs=2, metavar=("NODE_ID", "ANSWER"), help="Settle a decision node")
-    
+
     args = parser.parse_args()
-    frontier_path = Path(args.file)
+    frontier_path = Path(os.path.realpath(str(args.file)))
 
     if frontier_path.exists():
         tree = DesignTree.load_from_json(frontier_path)
@@ -130,19 +149,8 @@ def main():
 
     frontier = tree.compute_frontier()
     if args.show_frontier or not args.settle:
-        print(f"\n🎯 Objective: {tree.objective}")
-        print(f"📊 Total Nodes: {len(tree.nodes)} | Settled: {sum(1 for n in tree.nodes.values() if n.is_settled())}")
-        if not frontier:
-            if tree.nodes and tree.is_complete():
-                print("✅ Frontier is EMPTY. All prerequisite branches are fully settled!")
-            else:
-                print("ℹ️ No active frontier nodes. Define new decision nodes to begin grilling.")
-        else:
-            print(f"\n⚡ Current Active Frontier ({len(frontier)} questions ready):")
-            for idx, node in enumerate(frontier, 1):
-                print(f"\n❓ Q{idx} [{node.node_id}] - {node.title}")
-                print(f"   {node.question}")
-                print(f"   ➡️ Recommended: {node.recommended}")
+        _display_frontier(tree, frontier)
+
 
 if __name__ == "__main__":
     main()

package/runner/auditor_engine.py

@@ -17,6 +17,68 @@ from skills.research_cache.hasher import SourceHasher
 from runner.state_machine import ResearchStateMachine, ScopeStatus
 from runner.refinement import compute_epistemic_score
 
+def _compute_scope_epistemic_score(
+    constitution: Any,
+    alpha_dossier: Dict[str, Any],
+    beta_dossier: Dict[str, Any],
+    alpha_results: list,
+    beta_results: list,
+    counts: Dict[str, int],
+) -> float:
+    from runner.refinement import LEGACY_CONSTITUTION
+
+    if constitution is not LEGACY_CONSTITUTION:
+        from runner.claim_witness import STATUS_REJECTED, claims_from_dossier
+        from runner.refinement import compute_epistemic_score_from_claims
+
+        results_by_id = {r["claim_id"]: r for r in (alpha_results + beta_results)}
+        score_claims = claims_from_dossier(alpha_dossier) + claims_from_dossier(beta_dossier)
+        for c in score_claims:
+            r = results_by_id.get(c.claim_id)
+            if r is not None and r.get("audited_tag") == "UNVERIFIED_REJECTED":
+                c.tag = "UNVERIFIED_REJECTED"
+                c.status = STATUS_REJECTED
+        epistemic_score, _breakdown = compute_epistemic_score_from_claims(
+            score_claims, constitution=constitution
+        )
+        return epistemic_score
+
+    epistemic_score, _breakdown = compute_epistemic_score(counts)
+    return epistemic_score
+
+
+def _apply_living_dossiers_degradation(
+    base_dir: Path,
+    scope_id: str,
+    alpha_dossier: Dict[str, Any],
+    beta_dossier: Dict[str, Any],
+) -> Dict[str, Any]:
+    degradation = {"events": [], "degraded_scopes": []}
+    try:
+        from runner.living_dossiers import (
+            apply_degradation,
+            append_ledger,
+            load_retractions,
+            queue_requeue,
+        )
+        from runner.claim_witness import claims_from_dossier
+
+        retractions = load_retractions(base_dir)
+        if retractions:
+            all_claims = claims_from_dossier(alpha_dossier) + claims_from_dossier(beta_dossier)
+            _degraded, events = apply_degradation(all_claims, retractions, scope_id=scope_id)
+            if events:
+                append_ledger(base_dir, events)
+                queue_requeue(base_dir, scope_id, reason="claim degradation (retraction event)")
+            degradation = {
+                "events": [e.to_dict() for e in events],
+                "degraded_scopes": [scope_id] if events else [],
+            }
+    except Exception as exc:  # noqa: BLE001 - degradation must not break audit
+        print(f"[auditor] living-dossiers pass skipped: {exc}", file=sys.stderr)
+    return degradation
+
+
 class EpistemicAuditorEngine:
     def __init__(self, base_dir: Optional[Path] = None):
         self.base_dir = base_dir or Path(".research")
@@ -59,82 +121,24 @@ class EpistemicAuditorEngine:
             beta_dossier.get("falsification_claims", []), constitution=constitution
         )
 
-        total_verified = alpha_verified + beta_verified
-        total_rejected = alpha_rejected + beta_rejected
-
-        # Negative knowledge counts
-        neg_knowledge_alpha = len(alpha_dossier.get("negative_knowledge", []))
-        neg_knowledge_beta = len(beta_dossier.get("negative_knowledge", []))
-        total_neg_knowledge = neg_knowledge_alpha + neg_knowledge_beta
-
-        total_inferred = len(alpha_dossier.get("inferred_implications", []))
-        total_hypotheses = len(beta_dossier.get("hypotheses", []))
+        counts = {
+            "verified": alpha_verified + beta_verified,
+            "rejected": alpha_rejected + beta_rejected,
+            "inferred": len(alpha_dossier.get("inferred_implications", [])),
+            "hypotheses": len(beta_dossier.get("hypotheses", [])),
+            "neg_knowledge": len(alpha_dossier.get("negative_knowledge", [])) + len(beta_dossier.get("negative_knowledge", [])),
+        }
 
         # 3. Calculate Epistemic Score via the pure refinement function.
-        #    NOTE (docs/impl mismatch, deliberate): docs/SYSTEM_ARCHITECTURE.md
-        #    §1.2 publishes tier-weighted V(c_i); the runtime has always scored
-        #    flat 1.0 per verified claim. LEGACY_CONSTITUTION preserves that;
-        #    tier weighting is opt-in via Domain Packs (Stream G).
-        if constitution is not LEGACY_CONSTITUTION:
-            from runner.claim_witness import STATUS_REJECTED, claims_from_dossier
-            from runner.refinement import compute_epistemic_score_from_claims
-
-            results_by_id = {
-                r["claim_id"]: r for r in (alpha_results + beta_results)
-            }
-            score_claims = claims_from_dossier(alpha_dossier) + claims_from_dossier(beta_dossier)
-            for c in score_claims:
-                r = results_by_id.get(c.claim_id)
-                if r is not None and r.get("audited_tag") == "UNVERIFIED_REJECTED":
-                    # Reflect the auditor's verdict, not the dossier's claim.
-                    c.tag = "UNVERIFIED_REJECTED"
-                    c.status = STATUS_REJECTED
-            epistemic_score, _breakdown = compute_epistemic_score_from_claims(
-                score_claims, constitution=constitution
-            )
-        else:
-            epistemic_score, _breakdown = compute_epistemic_score({
-                "verified": total_verified,
-                "rejected": total_rejected,
-                "inferred": total_inferred,
-                "hypotheses": total_hypotheses,
-                "neg_knowledge": total_neg_knowledge,
-            })
+        epistemic_score = _compute_scope_epistemic_score(
+            constitution, alpha_dossier, beta_dossier, alpha_results, beta_results, counts
+        )
         accept_threshold = constitution.accept_threshold
 
-        # 3b. Living Dossiers (Stream C): a VERIFIED claim is a time-bounded
-        #     loan against its source. Join against retraction events —
-        #     RETRACTED => STALE even when the quote still matches locally.
-        degradation = {"events": [], "degraded_scopes": []}
-        try:
-            from runner.living_dossiers import (
-                apply_degradation,
-                append_ledger,
-                load_retractions,
-                queue_requeue,
-            )
-            from runner.claim_witness import claims_from_dossier
-
-            retractions = load_retractions(self.base_dir)
-            if retractions:
-                all_claims = (
-                    claims_from_dossier(alpha_dossier)
-                    + claims_from_dossier(beta_dossier)
-                )
-                _degraded, events = apply_degradation(
-                    all_claims, retractions, scope_id=scope_id
-                )
-                if events:
-                    append_ledger(self.base_dir, events)
-                    queue_requeue(
-                        self.base_dir, scope_id, reason="claim degradation (retraction event)"
-                    )
-                degradation = {
-                    "events": [e.to_dict() for e in events],
-                    "degraded_scopes": [scope_id] if events else [],
-                }
-        except Exception as exc:  # noqa: BLE001 - degradation must not break audit
-            print(f"[auditor] living-dossiers pass skipped: {exc}", file=sys.stderr)
+        # 3b. Living Dossiers (Stream C): check degradation against retraction events
+        degradation = _apply_living_dossiers_degradation(
+            self.base_dir, scope_id, alpha_dossier, beta_dossier
+        )
 
         # 4. Calculate Divergence Score
         divergence_score, divergence_matrix = self._compute_divergence(alpha_dossier, beta_dossier)
@@ -146,9 +150,9 @@ class EpistemicAuditorEngine:
             "audited_at": datetime.now(timezone.utc).isoformat(),
             "summary": {
                 "total_claims_audited": len(alpha_results) + len(beta_results),
-                "verified_passed": total_verified,
-                "unverified_rejected": total_rejected,
-                "negative_knowledge_count": total_neg_knowledge,
+                "verified_passed": counts["verified"],
+                "unverified_rejected": counts["rejected"],
+                "negative_knowledge_count": counts["neg_knowledge"],
                 "epistemic_score": epistemic_score,
                 "divergence_score": divergence_score,
                 "verdict": "CERTIFIED" if epistemic_score >= accept_threshold else "WARNING_LOW_GROUNDING"
@@ -294,44 +298,60 @@ class EpistemicAuditorEngine:
         divergence = round(min(1.0, (contradictions * 2) / total_claims), 2)
         return divergence, matrix
 
-    def _generate_synthesis_markdown(self, scope_id: str, alpha: Dict[str, Any], 
-                                     beta: Dict[str, Any], audit: Dict[str, Any]) -> str:
-        summary = audit["summary"]
-        md = []
-        md.append(f"# Epistemic Synthesis: Scope {scope_id}\n")
-        md.append(f"**Audit Verdict**: `{summary['verdict']}` | **Epistemic Score**: `{summary['epistemic_score']}/1.0` | **Divergence Index**: `{summary['divergence_score']}`\n")
-        
-        md.append("## 1. Verified Empirical Grounding")
-        for claim in audit["alpha_claims_audit"]:
+    @staticmethod
+    def _render_verified_section(alpha_audit: list, beta_audit: list) -> List[str]:
+        lines = ["## 1. Verified Empirical Grounding"]
+        for claim in alpha_audit:
             if claim["audited_tag"] == "VERIFIED":
-                md.append(f"- `[VERIFIED: {claim['source_hash'][:8]}]` {claim['statement']}")
-        for claim in audit["beta_claims_audit"]:
+                lines.append(f"- `[VERIFIED: {claim['source_hash'][:8]}]` {claim['statement']}")
+        for claim in beta_audit:
             if claim["audited_tag"] == "VERIFIED":
-                md.append(f"- `[VERIFIED: {claim['source_hash'][:8]}]` (Counter-Evidence) {claim['statement']}")
-        
-        md.append("\n## 2. Dialectic Tensions & Falsification Audit")
-        if audit["divergence_matrix"]:
-            for item in audit["divergence_matrix"]:
-                md.append(f"### Tension: {item['tension_type']}")
-                md.append(f"- **Thesis Assertion**: {item['proponent_claim']}")
-                md.append(f"- **Adversarial Critique**: {item['adversary_critique']}")
+                lines.append(f"- `[VERIFIED: {claim['source_hash'][:8]}]` (Counter-Evidence) {claim['statement']}")
+        return lines
+
+    @staticmethod
+    def _render_tensions_section(matrix: list) -> List[str]:
+        lines = ["\n## 2. Dialectic Tensions & Falsification Audit"]
+        if matrix:
+            for item in matrix:
+                lines.append(f"### Tension: {item['tension_type']}")
+                lines.append(f"- **Thesis Assertion**: {item['proponent_claim']}")
+                lines.append(f"- **Adversarial Critique**: {item['adversary_critique']}")
         else:
-            md.append("No active contradictions identified between primary literature and red-team findings.")
+            lines.append("No active contradictions identified between primary literature and red-team findings.")
+        return lines
 
-        md.append("\n## 3. Rejected & Unverified Assertions")
-        rejected = [c for c in audit["alpha_claims_audit"] + audit["beta_claims_audit"] if c["audited_tag"] == "UNVERIFIED_REJECTED"]
+    @staticmethod
+    def _render_rejected_section(claims: list) -> List[str]:
+        lines = ["\n## 3. Rejected & Unverified Assertions"]
+        rejected = [c for c in claims if c["audited_tag"] == "UNVERIFIED_REJECTED"]
         if rejected:
             for r in rejected:
-                md.append(f"- ⚠️ **PURGED**: \"{r['statement']}\" — *Reason: {r['reason']}*")
+                lines.append(f"- ⚠️ **PURGED**: \"{r['statement']}\" — *Reason: {r['reason']}*")
         else:
-            md.append("Zero claims rejected. 100% of cited assertions verified against source cache.")
+            lines.append("Zero claims rejected. 100% of cited assertions verified against source cache.")
+        return lines
 
-        md.append("\n## 4. Negative Knowledge Catalog")
+    @staticmethod
+    def _render_negative_knowledge_section(alpha: Dict[str, Any], beta: Dict[str, Any]) -> List[str]:
+        lines = ["\n## 4. Negative Knowledge Catalog"]
         all_neg = alpha.get("negative_knowledge", []) + beta.get("negative_knowledge", [])
         if all_neg:
             for n in all_neg:
-                md.append(f"- `[NEGATIVE_KNOWLEDGE: {n['query']}]` {n['finding']}")
+                lines.append(f"- `[NEGATIVE_KNOWLEDGE: {n['query']}]` {n['finding']}")
         else:
-            md.append("No negative knowledge declarations logged.")
+            lines.append("No negative knowledge declarations logged.")
+        return lines
 
+    def _generate_synthesis_markdown(self, scope_id: str, alpha: Dict[str, Any], 
+                                     beta: Dict[str, Any], audit: Dict[str, Any]) -> str:
+        summary = audit["summary"]
+        md = [
+            f"# Epistemic Synthesis: Scope {scope_id}\n",
+            f"**Audit Verdict**: `{summary['verdict']}` | **Epistemic Score**: `{summary['epistemic_score']}/1.0` | **Divergence Index**: `{summary['divergence_score']}`\n",
+        ]
+        md.extend(self._render_verified_section(audit["alpha_claims_audit"], audit["beta_claims_audit"]))
+        md.extend(self._render_tensions_section(audit.get("divergence_matrix", [])))
+        md.extend(self._render_rejected_section(audit["alpha_claims_audit"] + audit["beta_claims_audit"]))
+        md.extend(self._render_negative_knowledge_section(alpha, beta))
         return "\n".join(md)

package/runner/claim_store.py

@@ -22,6 +22,7 @@ need an API call and are out of this phase's scope).
 import argparse
 import hashlib
 import json
+import os
 import sqlite3
 import sys
 from pathlib import Path
@@ -50,8 +51,8 @@ def _has_fts5(conn: sqlite3.Connection) -> bool:
 
 class ClaimStore:
     def __init__(self, base_dir: Path, db_path: Optional[Path] = None):
-        self.base_dir = Path(base_dir)
-        self.db_path = db_path or (self.base_dir / "claims.sqlite")
+        self.base_dir = Path(os.path.realpath(str(base_dir)))
+        self.db_path = Path(os.path.realpath(str(db_path))) if db_path else (self.base_dir / "claims.sqlite")
         self.db_path.parent.mkdir(parents=True, exist_ok=True)
         self.conn = sqlite3.connect(str(self.db_path))
         self.conn.row_factory = sqlite3.Row
@@ -344,7 +345,7 @@ def main(argv: Optional[List[str]] = None) -> int:
     search_p.add_argument("text")
     args = parser.parse_args(argv)
 
-    base = Path(args.dir)
+    base = Path(os.path.realpath(str(args.dir)))
     if args.command == "reindex" or args.command is None:
         print(json.dumps(reindex(base), indent=2))
         return 0
@@ -354,7 +355,7 @@ def main(argv: Optional[List[str]] = None) -> int:
         store.close()
         print(json.dumps(rows, indent=2, default=str))
         return 0
-    return 0
+    return 1
 
 
 if __name__ == "__main__":

package/runner/living_dossiers.py

@@ -21,6 +21,7 @@ Degradation rules (applied after quote verification):
 
 import json
 import os
+import re
 import sys
 from dataclasses import dataclass, asdict
 from datetime import datetime, timezone
@@ -38,6 +39,7 @@ from runner.claim_witness import (  # noqa: E402
     STATUS_SUSPECT,
     ClaimWitness,
 )
+from runner.path_safety import safe_join  # noqa: E402
 
 EVENT_RETRACTED = "RETRACTED"
 EVENT_REVISED = "REVISED"
@@ -83,6 +85,8 @@ def write_retraction(
     """Record a RETRACTED/REVISED event for a cached source."""
     if event not in VALID_EVENTS:
         raise ValueError(f"event must be one of {VALID_EVENTS}, got {event!r}")
+    if not re.match(r"^[a-zA-Z0-9_\-\.]+$", source_hash):
+        raise ValueError(f"Invalid source hash: {source_hash!r}")
     retr_dir = Path(base_dir) / "retractions"
     retr_dir.mkdir(parents=True, exist_ok=True)
     payload = RetractionEvent(
@@ -92,7 +96,11 @@ def write_retraction(
         note=note,
         supersedes=supersedes,
     )
-    path = retr_dir / f"{source_hash}.json"
+    # `source_hash` is untrusted tool input, so the filename is joined under
+    # `retractions/` through safe_join (no separators, no bare `..`, and a
+    # containment re-check after canonicalisation). The regex above is the
+    # input gate; safe_join is the one that holds if the gate is ever loosened.
+    path = safe_join(retr_dir, f"{source_hash}.json")
     # Last write wins per hash (a REVISED may follow a RETRACTED); the ledger
     # keeps the full history of claim transitions either way.
     with open(path, "w", encoding="utf-8") as f:
@@ -258,7 +266,14 @@ def check_staleness(base_dir: Path, scope_ids: Optional[List[str]] = None) -> Di
 
     if scope_ids is None:
         if not scratch.exists():
-            return {"scopes": [], "retractions": len(retractions), "degraded": 0}
+            return {
+                "scopes": [],
+                "retractions": len(retractions),
+                "degraded": 0,
+                # Keep the early return shape identical to the normal one so
+                # callers can key off `degraded_scopes` unconditionally.
+                "degraded_scopes": [],
+            }
         scope_dirs = sorted(p for p in scratch.iterdir() if p.is_dir())
     else:
         scope_dirs = [scratch / s for s in scope_ids]
@@ -281,7 +296,7 @@ def check_staleness(base_dir: Path, scope_ids: Optional[List[str]] = None) -> Di
             claim_sets += 1
             dossier = load_dossier(dpath)
             claims = claims_from_dossier(dossier)
-            degraded, events = apply_degradation(
+            _, events = apply_degradation(
                 claims, retractions, scope_id=scope_id
             )
             all_events.extend(events)
@@ -336,19 +351,26 @@ def main(argv: Optional[List[str]] = None) -> int:
     rep.add_argument("--event", required=True, choices=list(VALID_EVENTS))
     rep.add_argument("--note", default="")
 
-    sub.add_parser("check", help="Run one staleness/degradation pass")
+    sub.add_parser(
+        "check",
+        help=(
+            "Run one staleness/degradation pass. Exits 1 when any scope "
+            "degraded (the ledger reporting a problem IS the outcome), 0 "
+            "otherwise — callers under `set -e` should expect that."
+        ),
+    )
     args = parser.parse_args(argv)
 
-    base = Path(args.dir)
+    base = Path(os.path.realpath(str(args.dir)))
     if args.command == "report":
         path = write_retraction(base, args.hash, args.event, note=args.note)
         print(json.dumps({"status": "recorded", "path": str(path)}))
         return 0
-    if args.command == "check":
-        print(json.dumps(check_staleness(base), indent=2))
-        return 0
-    print(json.dumps(check_staleness(base), indent=2))
-    return 0
+    if args.command == "check" or args.command is None:
+        res = check_staleness(base)
+        print(json.dumps(res, indent=2))
+        return 1 if res.get("degraded_scopes") else 0
+    return 1
 
 
 if __name__ == "__main__":

package/runner/mcp_protocol.py

@@ -140,7 +140,7 @@ class StdioJsonRpcServer:
             return self._error(req_id, -32601, f"Tool {tool_name} not found")
         try:
             text = spec.handler(args)
-        except Exception as exc:  # noqa: BLE001 - surface, do not kill the server
+        except Exception as exc:  # noqa: BLE001  # surface, do not kill the server
             return self._error(req_id, -32603, f"{type(exc).__name__}: {exc}")
         return self._reply(
             req_id, {"content": [{"type": "text", "text": text}]}