From 14aac49e961ac1ab65d167f41b0ec9db4f3ce6b3 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:16:40 -0500
Subject: [PATCH 01/43] test(pist): add receipt-density injector regression
 harness

---
 .../test_pist_receipt_density_injector.py     | 178 ++++++++++++++++++
 1 file changed, 178 insertions(+)
 create mode 100644 4-Infrastructure/shim/test_pist_receipt_density_injector.py

diff --git a/4-Infrastructure/shim/test_pist_receipt_density_injector.py b/4-Infrastructure/shim/test_pist_receipt_density_injector.py
new file mode 100644
index 00000000..a908572a
--- /dev/null
+++ b/4-Infrastructure/shim/test_pist_receipt_density_injector.py
@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""Regression tests for pist_receipt_density_injector.py.
+
+These tests are intentionally dependency-light and can run with plain Python:
+
+    python3 4-Infrastructure/shim/test_pist_receipt_density_injector.py
+
+They protect the Phase 2.1 anti-drift boundaries:
+
+* Markdown table noise is not treated as equations.
+* Receipt density and confidence are bounded.
+* Every generated record is explicitly not promoted.
+* Unsafe RDS table identifiers are rejected before SQL construction.
+* RDS writes remain opt-in; default runs produce JSON only.
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+import pist_receipt_density_injector as inj
+
+
+SAMPLE_RRC = """# RRC Equation Projection
+
+## Sample Projections
+
+| Equation | RRC shape | Status | Top axes |
+|---|---|---|---|
+| `bandwidth_adjusted_threshold` | `CognitiveLoadField` | `CANDIDATE` | `projection_declared, negative_control_strength, witness_declared, scale_band_declared` |
+| `source_domain` | `SignalShapedRouteCompiler` | `CANDIDATE` | `projection_declared, shape_closure, witness_declared, scale_band_declared` |
+"""
+
+
+SAMPLE_PIST = {
+    "predictions": [
+        {
+            "equation": "Equation",
+            "ground_truth": "RRC shape",
+            "proxy_pred": "LogogramProjection",
+            "exact_pred": "LogogramProjection",
+        },
+        {
+            "equation": "---",
+            "ground_truth": "---",
+            "proxy_pred": "LogogramProjection",
+            "exact_pred": "LogogramProjection",
+        },
+        {
+            "equation": "bandwidth_adjusted_threshold",
+            "ground_truth": "CognitiveLoadField",
+            "proxy_pred": "CognitiveLoadField",
+            "exact_pred": "CognitiveLoadField",
+            "matrix_hash": "mhash001",
+            "canonical_hash": "chash001",
+            "spectral_gap": 0.5,
+            "rank_estimate": 8,
+            "laplacian_zero_count": 1,
+            "crossing_density": 0.25,
+            "strand_entropy": 3.0,
+        },
+        {
+            "equation": "source_domain",
+            "ground_truth": "SignalShapedRouteCompiler",
+            "proxy_pred": "LogogramProjection",
+            "exact_pred": "LogogramProjection",
+            "matrix_hash": "mhash002",
+            "canonical_hash": "chash002",
+            "spectral_gap": 0.25,
+            "rank_estimate": 7,
+            "laplacian_zero_count": 1,
+            "crossing_density": 0.125,
+            "strand_entropy": 2.5,
+        },
+    ]
+}
+
+
+def assert_true(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def test_table_noise_filtering() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        path = Path(td) / "rrc.md"
+        path.write_text(SAMPLE_RRC, encoding="utf-8")
+        rows = inj.parse_rrc_table(path)
+        assert_true(len(rows) == 2, f"expected 2 real rows, got {len(rows)}")
+        assert_true(all(r.equation_id not in {"Equation", "---"} for r in rows), "table noise leaked into rows")
+
+
+def test_pist_noise_filtering() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        path = Path(td) / "pist.json"
+        path.write_text(json.dumps(SAMPLE_PIST), encoding="utf-8")
+        preds = inj.load_pist_predictions(path)
+        assert_true(set(preds) == {"bandwidth_adjusted_threshold", "source_domain"}, f"unexpected predictions: {set(preds)}")
+
+
+def test_record_bounds_and_no_promotion() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        rrc = Path(td) / "rrc.md"
+        pist = Path(td) / "pist.json"
+        rrc.write_text(SAMPLE_RRC, encoding="utf-8")
+        pist.write_text(json.dumps(SAMPLE_PIST), encoding="utf-8")
+        rows = inj.parse_rrc_table(rrc)
+        preds = inj.load_pist_predictions(pist)
+        records = [inj.build_record(row, preds.get(row.equation_id)) for row in rows]
+        assert_true(len(records) == 2, "expected 2 records")
+        for record in records:
+            assert_true(0.0 <= record.receipt_density <= 1.0, f"density out of range: {record}")
+            assert_true(0.0 <= record.confidence <= 1.0, f"confidence out of range: {record}")
+            assert_true(record.promotion == "not_promoted", "promotion boundary violated")
+            assert_true(record.receipt_hash, "missing receipt hash")
+
+
+def test_shape_disagreement_warning() -> None:
+    row = inj.RRCEquationRow(
+        equation_id="source_domain",
+        rrc_shape="SignalShapedRouteCompiler",
+        status="CANDIDATE",
+        top_axes=["projection_declared", "shape_closure"],
+    )
+    pred = SAMPLE_PIST["predictions"][-1]
+    record = inj.build_record(row, pred)
+    assert_true("pist_shape_disagreement" in record.warnings, "expected disagreement warning")
+
+
+def test_table_identifier_validation() -> None:
+    assert_true(inj.split_qualified_table("ene.rrc_receipt_density") == ("ene", "rrc_receipt_density"), "valid table rejected")
+    bad_tables = [
+        "ene.bad;drop table x",
+        "ene.rrc receipt density",
+        "ene..rrc_receipt_density",
+        "ene.rrc_receipt_density where 1=1",
+    ]
+    for table in bad_tables:
+        try:
+            inj.split_qualified_table(table)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError(f"unsafe table accepted: {table}")
+
+
+def test_default_main_does_not_write_rds() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        rrc = Path(td) / "rrc.md"
+        pist = Path(td) / "pist.json"
+        out = Path(td) / "out.json"
+        rrc.write_text(SAMPLE_RRC, encoding="utf-8")
+        pist.write_text(json.dumps(SAMPLE_PIST), encoding="utf-8")
+        code = inj.main(["--rrc-file", str(rrc), "--pist-report", str(pist), "--out", str(out)])
+        assert_true(code == 0, f"main returned {code}")
+        payload = json.loads(out.read_text(encoding="utf-8"))
+        assert_true(payload["summary"]["rds_write"]["enabled"] is False, "RDS write should be disabled by default")
+        assert_true(payload["summary"]["records"] == 2, "unexpected record count")
+
+
+def run_all() -> None:
+    tests = [
+        test_table_noise_filtering,
+        test_pist_noise_filtering,
+        test_record_bounds_and_no_promotion,
+        test_shape_disagreement_warning,
+        test_table_identifier_validation,
+        test_default_main_does_not_write_rds,
+    ]
+    for test in tests:
+        test()
+        print(f"PASS {test.__name__}")
+
+
+if __name__ == "__main__":
+    run_all()

From 2c9e029923f13fde98cafee36e995cfddd45fb8b Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:18:11 -0500
Subject: [PATCH 02/43] feat(pist): add receipt-density sidecar readback
 validator

---
 .../shim/validate_receipt_density_sidecar.py  | 151 ++++++++++++++++++
 1 file changed, 151 insertions(+)
 create mode 100644 4-Infrastructure/shim/validate_receipt_density_sidecar.py

diff --git a/4-Infrastructure/shim/validate_receipt_density_sidecar.py b/4-Infrastructure/shim/validate_receipt_density_sidecar.py
new file mode 100644
index 00000000..6a1e97e4
--- /dev/null
+++ b/4-Infrastructure/shim/validate_receipt_density_sidecar.py
@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Validate the RRC receipt-density sidecar table.
+
+Readback validator for Phase 2.1. Uses the shared rds_connect.connect_rds helper
+and checks the anti-drift boundary after a guarded --write-rds run.
+
+Default table: ene.rrc_receipt_density
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SHIM_DIR = Path(__file__).resolve().parent
+if str(SHIM_DIR) not in sys.path:
+    sys.path.insert(0, str(SHIM_DIR))
+
+DEFAULT_RDS_TABLE = "ene.rrc_receipt_density"
+_ALLOWED_TABLES = {"ene.rrc_receipt_density", "public.rrc_receipt_density"}
+
+
+def table_name(table: str) -> str:
+    """Return a known-safe qualified table name.
+
+    This validator intentionally accepts only known sidecar table names. The writer
+    has a generic identifier validator; the readback validator is stricter because
+    it should only verify the receipt-density sidecar.
+    """
+    if table not in _ALLOWED_TABLES:
+        raise ValueError(f"table not allowed for this validator: {table!r}")
+    schema, name = table.split(".", 1)
+    for ident in (schema, name):
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", ident):
+            raise ValueError(f"unsafe identifier: {ident!r}")
+    return f'"{schema}"."{name}"'
+
+
+def connect(connect_timeout: int | None):
+    try:
+        from rds_connect import connect_rds
+    except ImportError as exc:
+        raise RuntimeError("rds_connect.py is required for sidecar validation") from exc
+    overrides: dict[str, Any] = {}
+    if connect_timeout is not None:
+        overrides["connect_timeout"] = connect_timeout
+    return connect_rds(**overrides)
+
+
+def validate_table(conn: Any, table: str) -> dict[str, Any]:
+    full = table_name(table)
+    with conn.cursor() as cur:
+        cur.execute(
+            f"""
+            SELECT
+              COUNT(*) AS total,
+              SUM(CASE WHEN promotion != 'not_promoted' THEN 1 ELSE 0 END) AS promoted_rows,
+              SUM(CASE WHEN receipt_density IS NULL THEN 1 ELSE 0 END) AS null_density_rows,
+              SUM(CASE WHEN receipt_density < 0 OR receipt_density > 1 THEN 1 ELSE 0 END) AS out_of_range_density_rows,
+              SUM(CASE WHEN confidence IS NULL THEN 1 ELSE 0 END) AS null_confidence_rows,
+              SUM(CASE WHEN confidence < 0 OR confidence > 1 THEN 1 ELSE 0 END) AS out_of_range_confidence_rows,
+              SUM(CASE WHEN receipt_density_hash IS NULL OR receipt_density_hash = '' THEN 1 ELSE 0 END) AS missing_hash_rows,
+              SUM(CASE WHEN receipt_density_source IS NULL OR receipt_density_source = '' THEN 1 ELSE 0 END) AS missing_source_rows,
+              SUM(CASE WHEN receipt_density_status NOT IN ('CANDIDATE', 'HOLD') THEN 1 ELSE 0 END) AS bad_status_rows
+            FROM {full}
+            """
+        )
+        row = cur.fetchone()
+        keys = [
+            "total",
+            "promoted_rows",
+            "null_density_rows",
+            "out_of_range_density_rows",
+            "null_confidence_rows",
+            "out_of_range_confidence_rows",
+            "missing_hash_rows",
+            "missing_source_rows",
+            "bad_status_rows",
+        ]
+        summary = {k: int(v or 0) for k, v in zip(keys, row)}
+
+        cur.execute(
+            f"""
+            SELECT rrc_shape, COUNT(*), AVG(receipt_density)
+            FROM {full}
+            GROUP BY rrc_shape
+            ORDER BY rrc_shape
+            """
+        )
+        by_shape = [
+            {
+                "rrc_shape": shape,
+                "count": int(count),
+                "mean_receipt_density": round(float(avg), 6) if avg is not None else None,
+            }
+            for shape, count, avg in cur.fetchall()
+        ]
+
+    errors: list[str] = []
+    if summary["total"] <= 0:
+        errors.append("sidecar_table_empty")
+    for key in [
+        "promoted_rows",
+        "null_density_rows",
+        "out_of_range_density_rows",
+        "null_confidence_rows",
+        "out_of_range_confidence_rows",
+        "missing_hash_rows",
+        "missing_source_rows",
+        "bad_status_rows",
+    ]:
+        if summary[key] != 0:
+            errors.append(key)
+
+    return {
+        "table": table,
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "summary": summary,
+        "by_shape": by_shape,
+        "promotion_policy": "all rows must remain not_promoted",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate the RRC receipt-density sidecar table.")
+    parser.add_argument("--rds-table", default=DEFAULT_RDS_TABLE, choices=sorted(_ALLOWED_TABLES))
+    parser.add_argument("--connect-timeout", type=int, default=10)
+    parser.add_argument("--out", type=Path, default=None, help="Optional JSON report output path.")
+    args = parser.parse_args(argv)
+
+    conn = connect(args.connect_timeout)
+    try:
+        result = validate_table(conn, args.rds_table)
+    finally:
+        conn.close()
+
+    print(json.dumps(result, indent=2, sort_keys=True))
+    if args.out is not None:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    return 0 if result["valid"] else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 34c82705b57f1a9550ba4ecaf2b19e676321c5a8 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:19:07 -0500
Subject: [PATCH 03/43] docs: add receipt-density verification sequence

---
 .../lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md  | 134 ++++++++++++++++--
 1 file changed, 120 insertions(+), 14 deletions(-)

diff --git a/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md b/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md
index 0d85bdb9..51f84f48 100644
--- a/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md
+++ b/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md
@@ -20,6 +20,59 @@ receipt_density populated == route has structural/witness evidence for RRC use
 
 ---
 
+## Phase 2.1 verification sequence
+
+Run the local regression harness first:
+
+```bash
+python3 4-Infrastructure/shim/test_pist_receipt_density_injector.py
+```
+
+Expected result: all tests print `PASS`.
+
+Then emit the audit JSON only:
+
+```bash
+python3 4-Infrastructure/shim/pist_receipt_density_injector.py
+```
+
+Inspect:
+
+```text
+shared-data/rrc_receipt_density_backfill.json
+```
+
+Only after inspection, run the guarded sidecar write:
+
+```bash
+python3 4-Infrastructure/shim/pist_receipt_density_injector.py --write-rds
+```
+
+Finally validate the sidecar table:
+
+```bash
+python3 4-Infrastructure/shim/validate_receipt_density_sidecar.py
+```
+
+Optional validation report:
+
+```bash
+python3 4-Infrastructure/shim/validate_receipt_density_sidecar.py \
+  --out shared-data/rrc_receipt_density_sidecar_validation.json
+```
+
+The validator fails if:
+
+```text
+sidecar table is empty
+any row has promotion != not_promoted
+any density/confidence is null or outside [0, 1]
+any receipt hash/source is missing
+any receipt_density_status is not CANDIDATE or HOLD
+```
+
+---
+
 ## Default inputs
 
 ```text
@@ -81,6 +134,29 @@ python3 4-Infrastructure/shim/pist_receipt_density_injector.py \
   --out shared-data/rrc_receipt_density_backfill.json
 ```
 
+Guarded RDS sidecar write:
+
+```bash
+python3 4-Infrastructure/shim/pist_receipt_density_injector.py \
+  --write-rds \
+  --rds-table ene.rrc_receipt_density
+```
+
+The writer uses:
+
+```text
+4-Infrastructure/shim/rds_connect.py
+```
+
+so connection parameters resolve through the shared RDS path:
+
+```text
+DATABASE_URL
+RDS_* env vars
+IAM token / boto3 / AWS CLI
+password fallback
+```
+
 ---
 
 ## Record schema
@@ -123,6 +199,45 @@ Each record has the form:
 
 ---
 
+## RDS sidecar schema
+
+The guarded writer creates or upserts into:
+
+```text
+ene.rrc_receipt_density
+```
+
+Fields:
+
+```text
+equation_id
+rrc_shape
+domain
+source_status
+receipt_density
+receipt_density_source
+receipt_density_hash
+receipt_density_status
+receipt_density_warnings
+confidence
+top_axes
+shape_prediction
+density_components
+promotion
+payload
+updated_at
+```
+
+The table has a check constraint:
+
+```sql
+promotion = 'not_promoted'
+```
+
+This makes promotion drift fail at the database boundary.
+
+---
+
 ## Density calculation
 
 The density score is computed from four bounded components:
@@ -186,25 +301,16 @@ Promotion still requires external receipts, Lean/kernel verification where appli
 
 ---
 
-## Next integration step
+## CI candidate
 
-Once the JSON output is inspected, the next safe step is an explicit DB writer guarded by a flag such as:
+A minimal CI step should run:
 
 ```bash
---write-rds
+python3 4-Infrastructure/shim/test_pist_receipt_density_injector.py
+python3 4-Infrastructure/shim/pist_receipt_density_injector.py --fail-on-missing-pist
 ```
 
-That writer should upsert only these fields:
-
-```text
-receipt_density
-receipt_density_source
-receipt_density_hash
-receipt_density_status
-receipt_density_warnings
-```
-
-and should not alter theorem truth, promotion state, or claim ladder status.
+The sidecar validator should run only in environments with RDS credentials.
 
 ---
 

From 3b8f8d2f8cc65758b729dc2d5a3507a1570e522f Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:31:59 -0500
Subject: [PATCH 04/43] fix(lean): remove stale PISTMachine sorries

---
 2-Search-Space/PIST/PISTMachine.lean | 173 +++++++++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 2-Search-Space/PIST/PISTMachine.lean

diff --git a/2-Search-Space/PIST/PISTMachine.lean b/2-Search-Space/PIST/PISTMachine.lean
new file mode 100644
index 00000000..0ad02372
--- /dev/null
+++ b/2-Search-Space/PIST/PISTMachine.lean
@@ -0,0 +1,173 @@
+import Semantics.FixedPoint
+import Mathlib.Data.Nat.Sqrt
+
+namespace Semantics.PISTMachine
+
+/-! # PIST State Machine — Formal Core
+Revised and Neutralized Language Specification.
+Anchored to: ChatGPT-Making_It_Rigorous.md (Definitions 1-11)
+-/
+
+/-- Phase Sort: Energy bands for machine orchestration. -/
+inductive Phase
+  | grounded -- m(n) = 0 (Anchor/Square)
+  | drift    -- Low tension
+  | seismic  -- High tension
+deriving Repr, BEq, DecidableEq
+
+/-- Transfer Move Flags: Admissible transition events. -/
+inductive MoveFlag
+  | linearStep     -- n_{t+1} = n_t ± 1
+  | resonanceJump   -- mass preservation
+  | rejected        -- P_perp violation
+  | crystallized    -- m(n) hits 0
+deriving Repr, BEq, DecidableEq
+
+/-- State Vector: Formal machine configuration. -/
+structure State where
+  n        : Nat     -- Active coordinate
+  phase    : Phase   -- Coarse energy class
+  friction : Nat     -- Loss register
+  mass     : Nat     -- Hyperbola Index m(n)
+deriving Repr, BEq, DecidableEq
+
+/-- Square Anchoring: Distance to lower square boundary. -/
+def a (n : Nat) : Nat :=
+  let k := Nat.sqrt n
+  n - k^2
+
+/-- Square Anchoring: Distance to upper square boundary. -/
+def b (n : Nat) : Nat :=
+  let k := Nat.sqrt n
+  (k + 1)^2 - n
+
+/-- Hyperbola Index: Symmetric square-gap tension. -/
+def hyperbolaIndex (n : Nat) : Nat :=
+  (a n) * (b n)
+
+/-- Normalized Tension Ratio: ρ(n) ∈ [0, 1]. -/
+def rho (n : Nat) : Float :=
+  let k := Nat.sqrt n
+  let maxMass := ((2 * k + 1)^2 : Nat).toFloat / 4.0
+  if maxMass == 0 then 0.0
+  else (hyperbolaIndex n).toFloat / maxMass
+
+/-- Phase Classifier: Maps mass to coarse energy bands. -/
+def classifyPhase (n : Nat) (alpha : Float := 0.5) : Phase :=
+  let m := hyperbolaIndex n
+  if m == 0 then Phase.grounded
+  else if rho n < alpha then Phase.drift
+  else Phase.seismic
+
+/-- Mirror Involution: Symmetry-preserving resonance jump. -/
+def mirror (n : Nat) : Nat :=
+  let k := Nat.sqrt n
+  (k + 1)^2 + k^2 - n
+
+/-- Lyapunov Functional: Scalar energy for strict descent. -/
+def lambda (s : State) : Nat :=
+  s.mass + s.friction
+
+/-! # Theorems -/
+
+/-- Theorem: Mirror preserves mass. -/
+theorem mirror_preserves_mass (n : Nat) : 
+  hyperbolaIndex (mirror n) = hyperbolaIndex n := by
+  let k := Nat.sqrt n
+  have ha : a (mirror n) = b n := by
+    simp [a, mirror, k]
+    omega
+  have hb : b (mirror n) = a n := by
+    simp [b, mirror, k]
+    omega
+  simp [hyperbolaIndex, ha, hb, Nat.mul_comm]
+
+/-- Theorem: Zero-mass iff square. -/
+theorem zero_mass_iff_square (n : Nat) :
+  hyperbolaIndex n = 0 ↔ (Nat.sqrt n)^2 = n := by
+  simp [hyperbolaIndex, a, b]
+  constructor
+  · intro h
+    cases Nat.eq_zero_or_pos (Nat.sqrt n + 1)^2 with
+    | inl h_zero => 
+      have h_pos : (Nat.sqrt n + 1)^2 > 0 := Nat.pos_of_ne_zero (by intro h_z; injection h_z)
+      exact False.elim (Nat.lt_irrefl 0 (h_pos.trans_le (Nat.zero_le _)))
+    | inr _h_pos =>
+      have hn : n < (Nat.sqrt n + 1)^2 := Nat.lt_succ_sqrt n
+      have hb_pos : (Nat.sqrt n + 1)^2 - n > 0 := Nat.sub_pos_of_lt hn
+      have ha_zero : n - (Nat.sqrt n)^2 = 0 := by
+        exact Nat.eq_zero_of_mul_eq_zero_left h (Nat.ne_of_gt hb_pos)
+      exact Nat.eq_of_sub_eq_zero ha_zero
+  · intro h
+    simp [h]
+
+/-! ## MNLOG-001 Mass Number Valuations for PISTMachine Theorems
+
+    Doctrine: Logic can have a mass-number value only after we say which reality is weighing it.
+    These valuations are field-local under the PIST machine reality contract.
+-/
+
+/-- Reality contract for PIST machine theorems -/
+structure PISTRealityField where
+  domain      := "PIST state machine"
+  contract    := "hyperbola index preservation and square boundary invariants"
+  validator   := "algebraic proof (omega tactics)"
+
+/-- Residual model for PIST machine theorems -/
+structure PISTResidualModel where
+  uncertainty  : Nat  -- Unresolved edge cases
+  assumptions  : Nat  -- Axiomatic dependencies (sqrt properties)
+  cost         : Nat  -- Proof complexity
+
+/-- Projection rule for PIST machine theorems -/
+structure PISTProjectionRule where
+  name     := "linear projection"
+  scaling  := 256  -- Q8_8 approximation
+
+/-- Logical mass structure for PIST theorems -/
+structure PISTLogicalMass where
+  field          : PISTRealityField
+  admissible     : Nat  -- Proof strength, invariant preservation
+  residual       : PISTResidualModel
+  projection     : PISTProjectionRule
+
+/-- Compute mass number for PIST theorem -/
+def PISTLogicalMass.massNumber (lm : PISTLogicalMass) : Q0_16 :=
+  let totalResidual := lm.residual.uncertainty + lm.residual.assumptions + lm.residual.cost
+  let denom := 1 + totalResidual
+  let maxVal : Nat := 32767
+  if denom = 0 then Q0_16.zero
+  else
+    let scaled := if lm.admissible ≥ maxVal then maxVal else lm.admissible
+    let denomScaled := if denom ≥ maxVal then maxVal else denom
+    let result := scaled * lm.projection.scaling / denomScaled
+    ⟨result.toUInt16⟩
+
+/-- Mass number for mirror_preserves_mass theorem -/
+def mirrorPreservesMassMass : PISTLogicalMass :=
+  {
+    field := { domain := "PIST state machine", contract := "hyperbola index preservation", validator := "algebraic proof" },
+    admissible := 80,
+    residual := { uncertainty := 2, assumptions := 3, cost := 5 },
+    projection := { name := "linear projection", scaling := 256 }
+  }
+
+/-- Mass number for zero_mass_iff_square theorem -/
+def zeroMassIffSquareMass : PISTLogicalMass :=
+  {
+    field := { domain := "PIST state machine", contract := "square boundary invariants", validator := "algebraic proof" },
+    admissible := 75,
+    residual := { uncertainty := 3, assumptions := 3, cost := 7 },
+    projection := { name := "linear projection", scaling := 256 }
+  }
+
+/- Demonstrate MNLOG-001: PIST theorems have field-local numerical valuations -/
+#eval! mirrorPreservesMassMass.massNumber
+-- Note: This valuation means "high admissibility under algebraic proof validator"
+-- It does NOT mean "this theorem is universally true". Truth is proven by the theorem itself.
+
+#eval! zeroMassIffSquareMass.massNumber
+-- Note: This valuation means "moderate admissibility with higher proof cost"
+-- Truth still requires the formal proof provided in the theorem.
+
+end Semantics.PISTMachine

From 846a2ef2419d86a18ed12737084068206e4c9c15 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:38:07 -0500
Subject: [PATCH 05/43] feat(pist): add RRC PIST validation report cleaner

---
 .../shim/clean_rrc_pist_validation.py         | 132 ++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 4-Infrastructure/shim/clean_rrc_pist_validation.py

diff --git a/4-Infrastructure/shim/clean_rrc_pist_validation.py b/4-Infrastructure/shim/clean_rrc_pist_validation.py
new file mode 100644
index 00000000..4a7f3cc7
--- /dev/null
+++ b/4-Infrastructure/shim/clean_rrc_pist_validation.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Clean shared-data/rrc_pist_exact_validation.json after regeneration.
+
+The legacy validation script can accidentally include Markdown table artifacts such
+as `Equation` and `---` as predictions. This cleaner removes those rows, rebuilds
+the summary, and preserves classifier-backed predictions for the receipt-density
+injector.
+
+Usage:
+
+    python3 4-Infrastructure/shim/clean_rrc_pist_validation.py
+
+Optional paths:
+
+    python3 4-Infrastructure/shim/clean_rrc_pist_validation.py \
+      --input shared-data/rrc_pist_exact_validation.json \
+      --out shared-data/rrc_pist_exact_validation.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_REPORT = ROOT / "shared-data/rrc_pist_exact_validation.json"
+NOISE = {"", "---", "Equation", "RRC shape", "Status", "Top axes"}
+
+
+def is_noise(pred: dict[str, Any]) -> bool:
+    eq = str(pred.get("equation", ""))
+    gt = str(pred.get("ground_truth", ""))
+    proxy = str(pred.get("proxy_pred", ""))
+    return (
+        eq in NOISE
+        or gt in NOISE
+        or proxy in NOISE
+        or bool(re.fullmatch(r"-+", eq))
+        or bool(re.fullmatch(r"-+", gt))
+    )
+
+
+def accuracy(predictions: list[dict[str, Any]], key: str) -> float:
+    if not predictions:
+        return 0.0
+    return sum(1 for pred in predictions if pred.get(key) == pred.get("ground_truth")) / len(predictions)
+
+
+def per_class(predictions: list[dict[str, Any]], key: str) -> dict[str, dict[str, Any]]:
+    classes = sorted({p.get("ground_truth") for p in predictions} | {p.get(key) for p in predictions})
+    out: dict[str, dict[str, Any]] = {}
+    for cls in classes:
+        if cls is None:
+            continue
+        total = sum(1 for p in predictions if p.get("ground_truth") == cls)
+        correct = sum(1 for p in predictions if p.get("ground_truth") == cls and p.get(key) == cls)
+        out[str(cls)] = {"total": total, "correct": correct, "accuracy": correct / total if total else 0.0}
+    return out
+
+
+def zmp_distribution(predictions: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    zmp_by_gt: dict[str, list[int]] = defaultdict(list)
+    for pred in predictions:
+        gt = str(pred.get("ground_truth", "unknown"))
+        try:
+            zmp = int(pred.get("zmp", 0))
+        except Exception:
+            zmp = 0
+        zmp_by_gt[gt].append(zmp)
+    return {
+        gt: {"mean": sum(vals) / len(vals), "min": min(vals), "max": max(vals), "unique": len(set(vals))}
+        for gt, vals in zmp_by_gt.items()
+        if vals
+    }
+
+
+def clean_report(data: dict[str, Any]) -> dict[str, Any]:
+    raw_predictions = data.get("predictions", [])
+    predictions = [pred for pred in raw_predictions if isinstance(pred, dict) and not is_noise(pred)]
+    dropped = len(raw_predictions) - len(predictions)
+
+    matrix_hashes = Counter(str(p.get("matrix_hash", "")) for p in predictions if p.get("matrix_hash"))
+    canonical_hashes = Counter(str(p.get("canonical_hash", "")) for p in predictions if p.get("canonical_hash"))
+    errors = data.get("errors_detail", []) or []
+
+    return {
+        "summary": {
+            "total_input_predictions_before_clean": len(raw_predictions),
+            "markdown_noise_predictions_dropped": dropped,
+            "total": len(predictions),
+            "errors": len(errors),
+            "unique_matrix_hashes": len(matrix_hashes),
+            "unique_canonical_hashes": len(canonical_hashes),
+            "proxy_accuracy": accuracy(predictions, "proxy_pred"),
+            "exact_accuracy": accuracy(predictions, "exact_pred"),
+            "matrix_hash_collisions": sum(1 for count in matrix_hashes.values() if count > 1),
+            "canonical_hash_collisions": sum(1 for count in canonical_hashes.values() if count > 1),
+            "filtered_markdown_noise": True,
+            "promotion_policy": "not_promoted classifier diagnostics only",
+        },
+        "per_class_proxy": per_class(predictions, "proxy_pred"),
+        "per_class_exact": per_class(predictions, "exact_pred"),
+        "zmp_distribution": zmp_distribution(predictions),
+        "errors_detail": errors,
+        "predictions": predictions,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Clean RRC PIST validation JSON")
+    parser.add_argument("--input", type=Path, default=DEFAULT_REPORT)
+    parser.add_argument("--out", type=Path, default=DEFAULT_REPORT)
+    parser.add_argument("--fail-if-empty", action="store_true")
+    args = parser.parse_args()
+
+    data = json.loads(args.input.read_text(encoding="utf-8"))
+    cleaned = clean_report(data)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(cleaned, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(json.dumps(cleaned["summary"], indent=2, sort_keys=True))
+    print(f"Wrote cleaned report: {args.out}")
+    if args.fail_if_empty and cleaned["summary"]["total"] == 0:
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 3cd6e1507b8c4184e59ba7eae8316604677ca625 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:42:48 -0500
Subject: [PATCH 06/43] archive: remove duplicate PISTMachine search-space copy

---
 2-Search-Space/PIST/PISTMachine.lean | 173 ---------------------------
 1 file changed, 173 deletions(-)
 delete mode 100644 2-Search-Space/PIST/PISTMachine.lean

diff --git a/2-Search-Space/PIST/PISTMachine.lean b/2-Search-Space/PIST/PISTMachine.lean
deleted file mode 100644
index 0ad02372..00000000
--- a/2-Search-Space/PIST/PISTMachine.lean
+++ /dev/null
@@ -1,173 +0,0 @@
-import Semantics.FixedPoint
-import Mathlib.Data.Nat.Sqrt
-
-namespace Semantics.PISTMachine
-
-/-! # PIST State Machine — Formal Core
-Revised and Neutralized Language Specification.
-Anchored to: ChatGPT-Making_It_Rigorous.md (Definitions 1-11)
--/
-
-/-- Phase Sort: Energy bands for machine orchestration. -/
-inductive Phase
-  | grounded -- m(n) = 0 (Anchor/Square)
-  | drift    -- Low tension
-  | seismic  -- High tension
-deriving Repr, BEq, DecidableEq
-
-/-- Transfer Move Flags: Admissible transition events. -/
-inductive MoveFlag
-  | linearStep     -- n_{t+1} = n_t ± 1
-  | resonanceJump   -- mass preservation
-  | rejected        -- P_perp violation
-  | crystallized    -- m(n) hits 0
-deriving Repr, BEq, DecidableEq
-
-/-- State Vector: Formal machine configuration. -/
-structure State where
-  n        : Nat     -- Active coordinate
-  phase    : Phase   -- Coarse energy class
-  friction : Nat     -- Loss register
-  mass     : Nat     -- Hyperbola Index m(n)
-deriving Repr, BEq, DecidableEq
-
-/-- Square Anchoring: Distance to lower square boundary. -/
-def a (n : Nat) : Nat :=
-  let k := Nat.sqrt n
-  n - k^2
-
-/-- Square Anchoring: Distance to upper square boundary. -/
-def b (n : Nat) : Nat :=
-  let k := Nat.sqrt n
-  (k + 1)^2 - n
-
-/-- Hyperbola Index: Symmetric square-gap tension. -/
-def hyperbolaIndex (n : Nat) : Nat :=
-  (a n) * (b n)
-
-/-- Normalized Tension Ratio: ρ(n) ∈ [0, 1]. -/
-def rho (n : Nat) : Float :=
-  let k := Nat.sqrt n
-  let maxMass := ((2 * k + 1)^2 : Nat).toFloat / 4.0
-  if maxMass == 0 then 0.0
-  else (hyperbolaIndex n).toFloat / maxMass
-
-/-- Phase Classifier: Maps mass to coarse energy bands. -/
-def classifyPhase (n : Nat) (alpha : Float := 0.5) : Phase :=
-  let m := hyperbolaIndex n
-  if m == 0 then Phase.grounded
-  else if rho n < alpha then Phase.drift
-  else Phase.seismic
-
-/-- Mirror Involution: Symmetry-preserving resonance jump. -/
-def mirror (n : Nat) : Nat :=
-  let k := Nat.sqrt n
-  (k + 1)^2 + k^2 - n
-
-/-- Lyapunov Functional: Scalar energy for strict descent. -/
-def lambda (s : State) : Nat :=
-  s.mass + s.friction
-
-/-! # Theorems -/
-
-/-- Theorem: Mirror preserves mass. -/
-theorem mirror_preserves_mass (n : Nat) : 
-  hyperbolaIndex (mirror n) = hyperbolaIndex n := by
-  let k := Nat.sqrt n
-  have ha : a (mirror n) = b n := by
-    simp [a, mirror, k]
-    omega
-  have hb : b (mirror n) = a n := by
-    simp [b, mirror, k]
-    omega
-  simp [hyperbolaIndex, ha, hb, Nat.mul_comm]
-
-/-- Theorem: Zero-mass iff square. -/
-theorem zero_mass_iff_square (n : Nat) :
-  hyperbolaIndex n = 0 ↔ (Nat.sqrt n)^2 = n := by
-  simp [hyperbolaIndex, a, b]
-  constructor
-  · intro h
-    cases Nat.eq_zero_or_pos (Nat.sqrt n + 1)^2 with
-    | inl h_zero => 
-      have h_pos : (Nat.sqrt n + 1)^2 > 0 := Nat.pos_of_ne_zero (by intro h_z; injection h_z)
-      exact False.elim (Nat.lt_irrefl 0 (h_pos.trans_le (Nat.zero_le _)))
-    | inr _h_pos =>
-      have hn : n < (Nat.sqrt n + 1)^2 := Nat.lt_succ_sqrt n
-      have hb_pos : (Nat.sqrt n + 1)^2 - n > 0 := Nat.sub_pos_of_lt hn
-      have ha_zero : n - (Nat.sqrt n)^2 = 0 := by
-        exact Nat.eq_zero_of_mul_eq_zero_left h (Nat.ne_of_gt hb_pos)
-      exact Nat.eq_of_sub_eq_zero ha_zero
-  · intro h
-    simp [h]
-
-/-! ## MNLOG-001 Mass Number Valuations for PISTMachine Theorems
-
-    Doctrine: Logic can have a mass-number value only after we say which reality is weighing it.
-    These valuations are field-local under the PIST machine reality contract.
--/
-
-/-- Reality contract for PIST machine theorems -/
-structure PISTRealityField where
-  domain      := "PIST state machine"
-  contract    := "hyperbola index preservation and square boundary invariants"
-  validator   := "algebraic proof (omega tactics)"
-
-/-- Residual model for PIST machine theorems -/
-structure PISTResidualModel where
-  uncertainty  : Nat  -- Unresolved edge cases
-  assumptions  : Nat  -- Axiomatic dependencies (sqrt properties)
-  cost         : Nat  -- Proof complexity
-
-/-- Projection rule for PIST machine theorems -/
-structure PISTProjectionRule where
-  name     := "linear projection"
-  scaling  := 256  -- Q8_8 approximation
-
-/-- Logical mass structure for PIST theorems -/
-structure PISTLogicalMass where
-  field          : PISTRealityField
-  admissible     : Nat  -- Proof strength, invariant preservation
-  residual       : PISTResidualModel
-  projection     : PISTProjectionRule
-
-/-- Compute mass number for PIST theorem -/
-def PISTLogicalMass.massNumber (lm : PISTLogicalMass) : Q0_16 :=
-  let totalResidual := lm.residual.uncertainty + lm.residual.assumptions + lm.residual.cost
-  let denom := 1 + totalResidual
-  let maxVal : Nat := 32767
-  if denom = 0 then Q0_16.zero
-  else
-    let scaled := if lm.admissible ≥ maxVal then maxVal else lm.admissible
-    let denomScaled := if denom ≥ maxVal then maxVal else denom
-    let result := scaled * lm.projection.scaling / denomScaled
-    ⟨result.toUInt16⟩
-
-/-- Mass number for mirror_preserves_mass theorem -/
-def mirrorPreservesMassMass : PISTLogicalMass :=
-  {
-    field := { domain := "PIST state machine", contract := "hyperbola index preservation", validator := "algebraic proof" },
-    admissible := 80,
-    residual := { uncertainty := 2, assumptions := 3, cost := 5 },
-    projection := { name := "linear projection", scaling := 256 }
-  }
-
-/-- Mass number for zero_mass_iff_square theorem -/
-def zeroMassIffSquareMass : PISTLogicalMass :=
-  {
-    field := { domain := "PIST state machine", contract := "square boundary invariants", validator := "algebraic proof" },
-    admissible := 75,
-    residual := { uncertainty := 3, assumptions := 3, cost := 7 },
-    projection := { name := "linear projection", scaling := 256 }
-  }
-
-/- Demonstrate MNLOG-001: PIST theorems have field-local numerical valuations -/
-#eval! mirrorPreservesMassMass.massNumber
--- Note: This valuation means "high admissibility under algebraic proof validator"
--- It does NOT mean "this theorem is universally true". Truth is proven by the theorem itself.
-
-#eval! zeroMassIffSquareMass.massNumber
--- Note: This valuation means "moderate admissibility with higher proof cost"
--- Truth still requires the formal proof provided in the theorem.
-
-end Semantics.PISTMachine

From 4e91db4052b44c056c8c321bef1704003d824681 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:43:45 -0500
Subject: [PATCH 07/43] feat(pist): add RRC PIST shape-alignment calibration
 pass

---
 .../shim/rrc_pist_shape_alignment.py          | 191 ++++++++++++++++++
 1 file changed, 191 insertions(+)
 create mode 100644 4-Infrastructure/shim/rrc_pist_shape_alignment.py

diff --git a/4-Infrastructure/shim/rrc_pist_shape_alignment.py b/4-Infrastructure/shim/rrc_pist_shape_alignment.py
new file mode 100644
index 00000000..f81519c2
--- /dev/null
+++ b/4-Infrastructure/shim/rrc_pist_shape_alignment.py
@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""RRC/PIST shape-alignment calibration pass.
+
+Phase 2.2 bridge:
+
+    PIST exact/proxy label  = structural/spectral morphology
+    RRC shape label         = semantic/domain routing class
+
+A mismatch is not automatically an error. For the current RRC equation corpus,
+PIST often detects `LogogramProjection` because the input surface is an equation
+name/logogram, while RRC supplies the semantic routing class such as
+`CognitiveLoadField` or `SignalShapedRouteCompiler`.
+
+This script annotates receipt-density records with a `shape_alignment` object and
+turns known-compatible structural/semantic divergences into an explicit
+`structural_semantic_label_divergence` warning instead of a raw
+`pist_shape_disagreement` warning.
+
+It does not promote claims. Every record remains `promotion = not_promoted`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_IN = ROOT / "shared-data/rrc_receipt_density_backfill.json"
+DEFAULT_OUT = ROOT / "shared-data/rrc_receipt_density_backfill.json"
+
+RRC_SEMANTIC_SHAPES = {
+    "CognitiveLoadField",
+    "SignalShapedRouteCompiler",
+    "ProjectableGeometryTopology",
+    "CadForceProbeReceipt",
+    "LogogramProjection",
+}
+
+COMPATIBLE_STRUCTURAL_LABELS = {
+    "LogogramProjection",
+}
+
+ALIGNMENT_SCORES = {
+    "aligned_exact": 1.0,
+    "aligned_proxy": 0.86,
+    "compatible_structural_projection": 0.72,
+    "missing_prediction": 0.0,
+    "alignment_warning": 0.35,
+}
+
+
+def stable_hash(payload: Any) -> str:
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def determine_alignment(record: dict[str, Any]) -> dict[str, Any]:
+    rrc_shape = record.get("rrc_shape")
+    shape_prediction = record.get("shape_prediction", {}) or {}
+    proxy = shape_prediction.get("proxy_pred")
+    exact = shape_prediction.get("exact_pred")
+
+    if not proxy and not exact:
+        status = "missing_prediction"
+        reason = "No PIST proxy/exact classifier label is present for this record."
+    elif exact == rrc_shape:
+        status = "aligned_exact"
+        reason = "PIST exact structural label matches the RRC routing shape."
+    elif proxy == rrc_shape:
+        status = "aligned_proxy"
+        reason = "PIST proxy structural label matches the RRC routing shape."
+    elif (exact in COMPATIBLE_STRUCTURAL_LABELS or proxy in COMPATIBLE_STRUCTURAL_LABELS) and rrc_shape in RRC_SEMANTIC_SHAPES:
+        status = "compatible_structural_projection"
+        reason = (
+            "PIST detects symbolic/logogram morphology while RRC supplies the semantic/domain routing class."
+        )
+    else:
+        status = "alignment_warning"
+        reason = "PIST structural label and RRC semantic shape are not in the current compatibility map."
+
+    return {
+        "alignment_version": "rrc-pist-shape-alignment-v1",
+        "alignment_status": status,
+        "alignment_confidence": ALIGNMENT_SCORES[status],
+        "rrc_shape": rrc_shape,
+        "pist_proxy_label": proxy,
+        "pist_exact_label": exact,
+        "label_space_model": "PIST=morphology; RRC=semantic routing",
+        "reason": reason,
+        "promotion": "not_promoted",
+    }
+
+
+def rewrite_warnings(warnings: list[str], alignment: dict[str, Any]) -> list[str]:
+    out = [warning for warning in warnings if warning != "pist_shape_disagreement"]
+    status = alignment["alignment_status"]
+    if status == "compatible_structural_projection":
+        out.append("structural_semantic_label_divergence")
+    elif status == "alignment_warning":
+        out.append("pist_shape_alignment_warning")
+    elif status == "missing_prediction":
+        out.append("missing_pist_prediction")
+    return sorted(set(out))
+
+
+def update_hash(record: dict[str, Any]) -> str:
+    payload = {
+        "equation_id": record.get("equation_id"),
+        "rrc_shape": record.get("rrc_shape"),
+        "receipt_density": record.get("receipt_density"),
+        "confidence": record.get("confidence"),
+        "shape_prediction": record.get("shape_prediction"),
+        "shape_alignment": record.get("shape_alignment"),
+        "warnings": record.get("warnings"),
+        "promotion": "not_promoted",
+        "source": record.get("source"),
+    }
+    return stable_hash(payload)
+
+
+def align_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    records = payload.get("records", [])
+    if not isinstance(records, list):
+        raise ValueError("input JSON must contain a records array")
+
+    aligned_records: list[dict[str, Any]] = []
+    alignment_counts: Counter[str] = Counter()
+    warning_counts: Counter[str] = Counter()
+
+    for record in records:
+        if not isinstance(record, dict):
+            continue
+        updated = dict(record)
+        updated["promotion"] = "not_promoted"
+        alignment = determine_alignment(updated)
+        updated["shape_alignment"] = alignment
+        updated["warnings"] = rewrite_warnings(list(updated.get("warnings", [])), alignment)
+        updated["receipt_hash"] = update_hash(updated)
+        alignment_counts[alignment["alignment_status"]] += 1
+        warning_counts.update(updated["warnings"])
+        aligned_records.append(updated)
+
+    summary = dict(payload.get("summary", {}))
+    summary["shape_alignment_version"] = "rrc-pist-shape-alignment-v1"
+    summary["shape_alignment_counts"] = dict(sorted(alignment_counts.items()))
+    summary["warning_counts"] = dict(sorted(warning_counts.items()))
+    summary["promotion_policy"] = "no automatic promotion; shape alignment calibrates label spaces only"
+
+    out = dict(payload)
+    out["summary"] = summary
+    out["records"] = aligned_records
+    out["shape_alignment_claim_boundary"] = {
+        "means": "PIST structural morphology and RRC semantic routing labels have been calibrated",
+        "does_not_mean": "mathematical proof or claim promotion",
+        "promotion_policy": "not_promoted for every record",
+    }
+    return out
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Align RRC semantic labels with PIST structural labels.")
+    parser.add_argument("--input", type=Path, default=DEFAULT_IN)
+    parser.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    parser.add_argument("--fail-on-raw-disagreement", action="store_true")
+    args = parser.parse_args()
+
+    payload = json.loads(args.input.read_text(encoding="utf-8"))
+    aligned = align_payload(payload)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(aligned, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+    summary = aligned["summary"]
+    print(json.dumps({
+        "records": summary.get("records"),
+        "shape_alignment_counts": summary.get("shape_alignment_counts"),
+        "warning_counts": summary.get("warning_counts"),
+        "promotion_policy": summary.get("promotion_policy"),
+    }, indent=2, sort_keys=True))
+    print(f"Wrote aligned receipt-density JSON: {args.out}")
+
+    if args.fail_on_raw_disagreement and summary.get("warning_counts", {}).get("pist_shape_disagreement", 0):
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 07c31da6635d9ecae6677ffd3c65e48a4dd195bb Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:47:19 -0500
Subject: [PATCH 08/43] docs: add RRC PIST shape-alignment phase

---
 .../lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md  | 64 ++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md b/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md
index 51f84f48..5c728d29 100644
--- a/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md
+++ b/6-Documentation/docs/lean/PIST_RECEIPT_DENSITY_BACKFILL_V1.md
@@ -73,6 +73,57 @@ any receipt_density_status is not CANDIDATE or HOLD
 
 ---
 
+## Phase 2.2 shape-alignment calibration
+
+After classifier-backed density has been generated, run the alignment pass:
+
+```bash
+python3 4-Infrastructure/shim/rrc_pist_shape_alignment.py \
+  --fail-on-raw-disagreement
+```
+
+Then inspect:
+
+```bash
+jq '.summary.shape_alignment_counts, .summary.warning_counts' \
+  shared-data/rrc_receipt_density_backfill.json
+```
+
+Expected transition for the current corpus:
+
+```text
+pist_shape_disagreement -> removed
+structural_semantic_label_divergence -> present for compatible PIST/RRC label-space divergence
+shape_alignment_counts.compatible_structural_projection -> most or all records
+```
+
+Reason:
+
+```text
+PIST exact/proxy label = structural/spectral morphology
+RRC shape label        = semantic/domain routing class
+```
+
+So a row like:
+
+```text
+PIST exact label: LogogramProjection
+RRC shape: CognitiveLoadField
+```
+
+is not necessarily an error. It can mean PIST sees a symbolic/logogram surface while RRC supplies the semantic routing class.
+
+After alignment, rerun the guarded RDS sidecar write and readback validator:
+
+```bash
+python3 4-Infrastructure/shim/pist_receipt_density_injector.py --write-rds
+python3 4-Infrastructure/shim/validate_receipt_density_sidecar.py
+```
+
+Commit the aligned JSON artifacts after validation.
+
+---
+
 ## Default inputs
 
 ```text
@@ -188,12 +239,18 @@ Each record has the form:
     "rank_estimate": 8,
     "laplacian_zero_count": 1
   },
+  "shape_alignment": {
+    "alignment_version": "rrc-pist-shape-alignment-v1",
+    "alignment_status": "compatible_structural_projection",
+    "alignment_confidence": 0.72,
+    "label_space_model": "PIST=morphology; RRC=semantic routing"
+  },
   "top_axes": ["projection_declared", "negative_control_strength"],
   "status": "CANDIDATE",
   "promotion": "not_promoted",
   "source": "pist_receipt_density_injector_v1",
   "receipt_hash": "...",
-  "warnings": []
+  "warnings": ["structural_semantic_label_divergence"]
 }
 ```
 
@@ -308,6 +365,7 @@ A minimal CI step should run:
 ```bash
 python3 4-Infrastructure/shim/test_pist_receipt_density_injector.py
 python3 4-Infrastructure/shim/pist_receipt_density_injector.py --fail-on-missing-pist
+python3 4-Infrastructure/shim/rrc_pist_shape_alignment.py --fail-on-raw-disagreement
 ```
 
 The sidecar validator should run only in environments with RDS credentials.
@@ -319,3 +377,7 @@ The sidecar validator should run only in environments with RDS credentials.
 ```text
 PIST stops being just a repair engine when its classifications become receipt density for the RRC corpus.
 ```
+
+```text
+PIST is seeing morphology; RRC is naming semantics.
+```

From 64fee9a863a6f26732280801ed239fc1962476b3 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:50:29 -0500
Subject: [PATCH 09/43] fix(pist): correct repo root + fail-on-raw-disagreement
 check

---
 .../shim/rrc_pist_shape_alignment.py          | 50 +++++++++++++------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/4-Infrastructure/shim/rrc_pist_shape_alignment.py b/4-Infrastructure/shim/rrc_pist_shape_alignment.py
index f81519c2..9ad7e16e 100644
--- a/4-Infrastructure/shim/rrc_pist_shape_alignment.py
+++ b/4-Infrastructure/shim/rrc_pist_shape_alignment.py
@@ -28,7 +28,8 @@ from collections import Counter
 from pathlib import Path
 from typing import Any
 
-ROOT = Path(__file__).resolve().parents[2]
+# Repo root (this file lives at 4-Infrastructure/shim/...) 
+ROOT = Path(__file__).resolve().parents[3]
 DEFAULT_IN = ROOT / "shared-data/rrc_receipt_density_backfill.json"
 DEFAULT_OUT = ROOT / "shared-data/rrc_receipt_density_backfill.json"
 
@@ -73,11 +74,12 @@ def determine_alignment(record: dict[str, Any]) -> dict[str, Any]:
     elif proxy == rrc_shape:
         status = "aligned_proxy"
         reason = "PIST proxy structural label matches the RRC routing shape."
-    elif (exact in COMPATIBLE_STRUCTURAL_LABELS or proxy in COMPATIBLE_STRUCTURAL_LABELS) and rrc_shape in RRC_SEMANTIC_SHAPES:
+    elif (
+        (exact in COMPATIBLE_STRUCTURAL_LABELS or proxy in COMPATIBLE_STRUCTURAL_LABELS)
+        and rrc_shape in RRC_SEMANTIC_SHAPES
+    ):
         status = "compatible_structural_projection"
-        reason = (
-            "PIST detects symbolic/logogram morphology while RRC supplies the semantic/domain routing class."
-        )
+        reason = "PIST detects symbolic/logogram morphology while RRC supplies the semantic/domain routing class."
     else:
         status = "alignment_warning"
         reason = "PIST structural label and RRC semantic shape are not in the current compatibility map."
@@ -122,7 +124,7 @@ def update_hash(record: dict[str, Any]) -> str:
     return stable_hash(payload)
 
 
-def align_payload(payload: dict[str, Any]) -> dict[str, Any]:
+def align_payload(payload: dict[str, Any]) -> tuple[dict[str, Any], Counter[str]]:
     records = payload.get("records", [])
     if not isinstance(records, list):
         raise ValueError("input JSON must contain a records array")
@@ -130,16 +132,21 @@ def align_payload(payload: dict[str, Any]) -> dict[str, Any]:
     aligned_records: list[dict[str, Any]] = []
     alignment_counts: Counter[str] = Counter()
     warning_counts: Counter[str] = Counter()
+    raw_warning_counts: Counter[str] = Counter()
 
     for record in records:
         if not isinstance(record, dict):
             continue
+
+        raw_warning_counts.update(list(record.get("warnings", [])))
+
         updated = dict(record)
         updated["promotion"] = "not_promoted"
         alignment = determine_alignment(updated)
         updated["shape_alignment"] = alignment
         updated["warnings"] = rewrite_warnings(list(updated.get("warnings", [])), alignment)
         updated["receipt_hash"] = update_hash(updated)
+
         alignment_counts[alignment["alignment_status"]] += 1
         warning_counts.update(updated["warnings"])
         aligned_records.append(updated)
@@ -148,6 +155,7 @@ def align_payload(payload: dict[str, Any]) -> dict[str, Any]:
     summary["shape_alignment_version"] = "rrc-pist-shape-alignment-v1"
     summary["shape_alignment_counts"] = dict(sorted(alignment_counts.items()))
     summary["warning_counts"] = dict(sorted(warning_counts.items()))
+    summary["raw_warning_counts"] = dict(sorted(raw_warning_counts.items()))
     summary["promotion_policy"] = "no automatic promotion; shape alignment calibrates label spaces only"
 
     out = dict(payload)
@@ -158,31 +166,41 @@ def align_payload(payload: dict[str, Any]) -> dict[str, Any]:
         "does_not_mean": "mathematical proof or claim promotion",
         "promotion_policy": "not_promoted for every record",
     }
-    return out
+    return out, raw_warning_counts
 
 
 def main() -> int:
     parser = argparse.ArgumentParser(description="Align RRC semantic labels with PIST structural labels.")
     parser.add_argument("--input", type=Path, default=DEFAULT_IN)
     parser.add_argument("--out", type=Path, default=DEFAULT_OUT)
-    parser.add_argument("--fail-on-raw-disagreement", action="store_true")
+    parser.add_argument(
+        "--fail-on-raw-disagreement",
+        action="store_true",
+        help="Fail if the *input* JSON still contains any raw 'pist_shape_disagreement' warnings.",
+    )
     args = parser.parse_args()
 
     payload = json.loads(args.input.read_text(encoding="utf-8"))
-    aligned = align_payload(payload)
+    aligned, raw_warning_counts = align_payload(payload)
     args.out.parent.mkdir(parents=True, exist_ok=True)
     args.out.write_text(json.dumps(aligned, indent=2, sort_keys=True) + "\n", encoding="utf-8")
 
     summary = aligned["summary"]
-    print(json.dumps({
-        "records": summary.get("records"),
-        "shape_alignment_counts": summary.get("shape_alignment_counts"),
-        "warning_counts": summary.get("warning_counts"),
-        "promotion_policy": summary.get("promotion_policy"),
-    }, indent=2, sort_keys=True))
+    print(
+        json.dumps(
+            {
+                "shape_alignment_counts": summary.get("shape_alignment_counts"),
+                "warning_counts": summary.get("warning_counts"),
+                "raw_warning_counts": summary.get("raw_warning_counts"),
+                "promotion_policy": summary.get("promotion_policy"),
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
     print(f"Wrote aligned receipt-density JSON: {args.out}")
 
-    if args.fail_on_raw_disagreement and summary.get("warning_counts", {}).get("pist_shape_disagreement", 0):
+    if args.fail_on_raw_disagreement and raw_warning_counts.get("pist_shape_disagreement", 0):
         return 2
     return 0
 

From 3b4ee9758802fe383765443f183ce034193c84d1 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:58:25 -0500
Subject: [PATCH 10/43] docs(avm): redefine AVM as Lean-only ISA with adapter
 shims/backends

---
 .../docs/specs/AVM_CANONICAL_SPEC.md          | 270 ++++++++----------
 1 file changed, 120 insertions(+), 150 deletions(-)

diff --git a/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md b/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
index 8d3296a2..794d906a 100644
--- a/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
+++ b/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
@@ -1,183 +1,153 @@
 # Canonical Specification for the Adaptive Virtual Machine (AVM)
 ## State: CALIBRATED_PENDING_VALIDATION
 
+This document is the canonical design for **AVM as a Lean-defined core ISA**.
 
-## 1. AVM Instruction Set Architecture (ISA)
+**Core rule:**
 
-The AVM ISA defines a language-agnostic instruction set that serves as the bridge between mathematical languages and Python execution. The ISA consists of:
+> **Lean is the source of truth. AVM is a Lean-only ISA.**
 
-### Core Instruction Set
-```python
-# Stack-based operations
-PUSH(value: Any)  # Push a value onto the stack
-POP()             # Pop the top value from the stack
-APPLY(func: Any)   # Apply a function to the top N arguments
-JUMP(label: int)   # Unconditional jump
-JUMP_IF(condition: bool, label: int)  # Conditional jump
-CALL(method: str)  # Call a Python method
-IMPORT(module: str) # Import a Python module
-RETURN()          # Return from function
+All non-Lean languages (Python, Rust, C/C++, Go, etc.) are **adapter shims** (a.k.a.
+backends) that *strip / serialize / reinterpret* into AVM programs and execute
+AVM semantics. They do not define new semantics.
 
-# Data operations
-STORE(name: str)   # Store a value in the symbol table
-LOAD(name: str)    # Load a value from the symbol table
-DUMP()            # Dump execution state for debugging
+---
 
-# Control flow
-BEGIN(label: int)  # Mark a label
-END()             # End of function
-```
+## 0. Definitions
 
-### Data Representation
-- **Values**: All values are represented as Python-compatible objects or fixed-point atoms
-- **Types**: Minimal type system (int, Q16_16, Q0_16, bool, list, dict, function)
-- **Constants**: Predefined constants for math operations (π, e, etc.) expressed in Q16_16
+### 0.1 AVM Core
+The **AVM core** is the ISA + operational semantics defined in Lean.
 
-### Execution Model
-- Stack-based virtual machine
-- Type-checking during execution
-- Error handling via Python exceptions
-- Symbol table for cross-language data sharing
+- Finite opcode set (closed-world)
+- Finite value type set (closed-world)
+- Deterministic step/run semantics
+- No open string matching in decisions
+- No dynamic "Any" values in the ISA
 
-## 2. Semantic Stripping Algorithm
+### 0.2 Adapter shims (backends)
+Adapter shims are **extraction/interop targets**, not sources of truth.
 
-```python
-def strip_semantics(source: Any, threshold: float = 0.5) -> Any:
-    """
-    Strips language-specific semantics while preserving functionality
-    """
-    if is_invariant_root(source):  # Check if already a fundamental structure
-        return source
+They may:
+- Encode/decode AVM programs and values (serialization)
+- Interpret AVM programs (runtime interpreter)
+- Emit target artifacts (Python bytecode, C, Rust, Verilog, FPGA netlists)
 
-    delta = calculate_delta(source)  # 0-1 score of language dependency
-    
-    if delta < threshold:
-        # Decompose into invariant components
-        components = decompose(source)
-        stripped_components = [strip_semantics(c, threshold) for c in components]
-        return reconstruct(stripped_components)
-    else:
-        # Preserve as invariant root
-        return source
+They may **not**:
+- Introduce new ISA meaning
+- Add ad-hoc branching policy
+- Decide invariants or costs outside Lean
 
-def calculate_delta(node: Any) -> float:
-    """
-    Computes language dependency score (0-1)
-    - 0: Pure invariant structure
-    - 1: Heavily language-specific
-    """
-    # Implementation would analyze type signatures, syntax, etc.
-    pass
-```
+---
 
-## 3. AVM Binary Interface (ABI)
+## 1. AVM Instruction Set Architecture (ISA) — Lean-only
 
-### Calling Convention
-- **Stack layout**: CPython-compatible stack layout
-- **Argument passing**: All arguments pushed in order
-- **Return value**: Single value on stack
-- **Error handling**: Python exceptions
+The AVM ISA is a **Lean inductive** instruction set.
 
-### Data Format
-```python
-class AVMValue:
-    def __init__(self, value: Any):
-        self.value = value
-        self.type = get_type(value)
+### 1.1 Closed-world opcodes
+The opcode set MUST be finite and enumerable.
 
-def get_type(value: Any) -> str:
-    """
-    Maps to CPython's internal type representation
-    """
-    if isinstance(value, int): return "int"
-    if hasattr(value, 'is_q16_16'): return "Q16_16"
-    if hasattr(value, 'is_q0_16'): return "Q0_16"
-    # ... other types
-```
+A minimal core (illustrative, not final):
 
-### Registration Protocol
-```python
-def register_primitive(name: str, func: Callable):
-    """
-    Registers a primitive function for direct AVM execution
-    """
-    _registry[name] = func
+- Stack ops: `push`, `pop`, `dup`, `swap`
+- Locals: `load`, `store` (indexed by `Fin n`)
+- Control flow: `jump`, `jumpIf`, `halt`
+- Fixed-point arithmetic primitives: `addSat`, `subSat`, `mul`, etc.
 
-_registry = {}
-```
+### 1.2 Strict typing
+The ISA operates over a finite type universe:
 
-## 4. Invariant Root Extraction Process
+- `Q0_16` (default for dimensionless scalars)
+- `Q16_16` (only when range/precision forces it)
+- `Bool`
+- (Optional later) `UInt8`, `UInt16`, `UInt32`, fixed-width words for IO/register surfaces
 
-```python
-def extract_invariants(source: Any) -> List[Any]:
-    """
-    Recursively extracts fundamental mathematical structures
-    """
-    if is_primitive(source): return [source]
-    
-    if is_container(source):
-        children = []
-        for child in source.children:
-            children.extend(extract_invariants(child))
-        return children
-    
-    raise ValueError(f"Unsupported type: {type(source)}")
-```
+**No Float in core.** Float may exist only at boundary conversion shims.
 
-## 5. Formal Specification in Lean 4
+### 1.3 No dynamic foreign calls in ISA
+The ISA must not contain opcodes like `CALL("pythonMethod")` or `IMPORT("module")`.
 
-namespace Semantics.AVM
+If extensibility is needed, it must be via **finite enums** (e.g. `Prim : Type`)
+with semantics defined in Lean:
 
-inductive Value where
-  | int : Int → Value
-  | q16 : Q16_16 → Value
-  | q0  : Q0_16 → Value
-  | bool : Bool → Value
+- `Prim` is finite
+- `evalPrim : Prim -> ...` is defined in Lean
+- backends implement `Prim` by matching the Lean semantics
 
-instance : informational_bind State Value where
-  isLawful s := true
-  cost s := 0 -- Base transition cost
-  extract s := "AVM_STATE"
+---
 
-def compile (source : SourceLang) : Value :=
-  match source with
-  | `int n => Value.int n
-  | `fixed n => Value.q16 n
-  | `ratio n => Value.q0 n
-  | `bool b => Value.bool b
-```
+## 2. Execution model
 
-This specification provides a foundation for proving equivalence between source language semantics and AVM execution. The full implementation would include:
+### 2.1 Step semantics
+AVM execution is defined by a Lean function:
 
-1. Type soundness proof
-2. Preservation theorem
-3. Progress theorem
-4. Adequacy proof
+- `step : Program -> State -> Outcome State`
 
-## 6. CALIBRATED State Requirements
-The AVM is considered **CALIBRATED** once the following conditions are met:
+### 2.2 Run semantics (fuel)
+AVM execution must have a fuel-bounded run function:
 
-1. **Float Elimination**: All core primitive float references have been removed from the AVM ISA and Lean core.
-2. **Type Definition**: `Q0_16` and `Q16_16` are explicitly defined and used as the primary numeric types.
-3. **Behavioral Declaration**: Arithmetic, rounding (floor), and overflow (saturating) behaviors are formally declared and implemented.
-4. **Boundary Conversion**: Explicit paths for converting external numeric formats (Int, Float-input) into `Q16_16` are defined.
-5. **Determinism Invariant**: The AVM must achieve bit-exact reproducibility across all execution environments (Lean, Python-AVM, FPGA).
-6. **Bind Semantics**: Composition of AVM instructions must follow the `informational_bind` metric laws.
-7. **Validator Enforcement**: A pre-commit validator rejects any `f32`, `f64`, or `double` references in the `Semantics/AVM/` path.
+- `run : Fuel -> Program -> State -> Outcome State`
 
-## 7. Determinism Invariant
-The AVM state transition function $f(S, I) \rightarrow S'$ must satisfy:
-$\forall env_1, env_2 \in \{Lean, Python, FPGA\}, f_{env_1}(S, I) = f_{env_2}(S, I)$
-This ensures that "Formal Drift" is mathematically impossible.
+This is required for totality and for extraction to bounded substrates.
 
-## 8. Boundary Conversion
-```python
-def to_q16_16(val: Any) -> int:
-    if isinstance(val, int):
-        return val << 16
-    if isinstance(val, float):
-        # Explicit boundary clip and scale
-        clamped = max(-32768.0, min(32767.9999, val))
-        return int(clamped * 65536)
-    raise ValueError("Invalid Boundary Format")
-```
\ No newline at end of file
+### 2.3 Determinism invariant
+The state transition must be deterministic:
+
+For any two backend environments implementing the same AVM ISA,
+
+- `run_backend1(program, state) == run_backend2(program, state)`
+
+up to the same observable projection.
+
+---
+
+## 3. Serialization boundary (shim responsibility)
+
+Adapters may represent AVM programs and values in JSON or binary form.
+
+Rules:
+- Serialization formats must be versioned.
+- No semantic meaning may depend on string parsing.
+- Decoders must reject unknown opcodes/types.
+
+---
+
+## 4. Receipt / provenance policy
+
+Every adapter execution must be able to emit a receipt packet containing:
+
+- AVM ISA version
+- adapter version
+- input program hash
+- output state hash
+- (optional) projection hash
+
+This makes drift observable and auditable.
+
+---
+
+## 5. Relationship to prior "universal adapter" language
+
+Earlier drafts described AVM as a universal adapter from many math languages.
+
+**This spec supersedes that framing.** The correct architecture is:
+
+- **Lean -> AVM ISA (Lean-defined) -> adapter shims/backends**
+
+If other languages are supported as inputs, they must be compiled into AVM by a
+shim that produces AVM programs; but the AVM ISA itself remains Lean-only.
+
+---
+
+## 6. Claim boundary
+
+This document defines AVM as a Lean-only ISA and a backend adapter ecosystem.
+
+It does not claim:
+- that every backend already exists
+- that all proofs are complete
+- that the ISA opcodes are final
+
+It does claim:
+- strict typing + closed-world opcodes is mandatory
+- all semantics live in Lean
+- all non-Lean code is an adapter shim, not a semantic authority

From 1b6f58c5ceecbc9c4501a3c0196f3bf968b7f12b Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 15:59:41 -0500
Subject: [PATCH 11/43] docs(avm): add stripping policy and bad-code
 elimination rules

---
 .../docs/specs/AVM_CANONICAL_SPEC.md          | 52 +++++++++++++++++--
 1 file changed, 48 insertions(+), 4 deletions(-)

diff --git a/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md b/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
index 794d906a..ebf714cb 100644
--- a/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
+++ b/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
@@ -100,7 +100,50 @@ up to the same observable projection.
 
 ---
 
-## 3. Serialization boundary (shim responsibility)
+## 3. Stripping policy ("bad code gets stripped out")
+
+The phrase "bad code gets stripped out in the conversion" is made precise here.
+
+### 3.1 What "bad" means
+"Bad" does NOT mean "inelegant". Bad means one of:
+
+- Not representable in the AVM closed-world ISA.
+- Violates AVM typing rules (ill-typed stack/locals).
+- Uses forbidden substrate features in core semantics (e.g. Float in hot paths).
+- Requires open string parsing or reflection to make a decision.
+- Cannot be made deterministic under the fixed-point policy.
+
+### 3.2 What stripping is allowed to do
+When converting an external artifact into an AVM program, a shim may:
+
+- Drop unreachable code (dead branches) if reachability is proven by the shim's proof/receipt boundary.
+- Inline and normalize expressions into AVM primitives.
+- Replace dynamic dispatch with finite enums (`Prim`, `Opcode`).
+- Reject unsupported constructs with a hard error.
+
+### 3.3 What stripping is NOT allowed to do
+A shim must NOT:
+
+- Silently change behavior to "make it fit" AVM.
+- Replace unknown operations with placeholders.
+- Substitute heuristic approximations without explicit residual/receipt fields.
+
+If a construct cannot be represented, the correct action is **reject**, not "strip silently".
+
+### 3.4 Stripping output receipts
+Every strip/conversion pass must emit a receipt packet containing:
+
+- input hash
+- output program hash
+- strip decisions (what was dropped, what was rewritten)
+- unsupported constructs encountered (if any)
+- AVM ISA version targeted
+
+This makes "bad code elimination" auditable.
+
+---
+
+## 4. Serialization boundary (shim responsibility)
 
 Adapters may represent AVM programs and values in JSON or binary form.
 
@@ -111,7 +154,7 @@ Rules:
 
 ---
 
-## 4. Receipt / provenance policy
+## 5. Receipt / provenance policy
 
 Every adapter execution must be able to emit a receipt packet containing:
 
@@ -125,7 +168,7 @@ This makes drift observable and auditable.
 
 ---
 
-## 5. Relationship to prior "universal adapter" language
+## 6. Relationship to prior "universal adapter" language
 
 Earlier drafts described AVM as a universal adapter from many math languages.
 
@@ -138,7 +181,7 @@ shim that produces AVM programs; but the AVM ISA itself remains Lean-only.
 
 ---
 
-## 6. Claim boundary
+## 7. Claim boundary
 
 This document defines AVM as a Lean-only ISA and a backend adapter ecosystem.
 
@@ -151,3 +194,4 @@ It does claim:
 - strict typing + closed-world opcodes is mandatory
 - all semantics live in Lean
 - all non-Lean code is an adapter shim, not a semantic authority
+- stripping must be explicit (reject or receipt), never silent behavior change

From 6d73a1b2515f2db0e33429b198e9e54b72b662ed Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:02:05 -0500
Subject: [PATCH 12/43] docs(avm): strengthen float prohibition and
 documentation requirement

---
 .../docs/specs/AVM_CANONICAL_SPEC.md          | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md b/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
index ebf714cb..1a4a0e71 100644
--- a/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
+++ b/6-Documentation/docs/specs/AVM_CANONICAL_SPEC.md
@@ -61,9 +61,22 @@ The ISA operates over a finite type universe:
 - `Bool`
 - (Optional later) `UInt8`, `UInt16`, `UInt32`, fixed-width words for IO/register surfaces
 
-**No Float in core.** Float may exist only at boundary conversion shims.
+### 1.3 Float prohibition (strong)
+**Float must not be used anywhere if at all possible.**
 
-### 1.3 No dynamic foreign calls in ISA
+- **AVM core**: Float is forbidden.
+- **Backends**: Float is forbidden for any semantic computation.
+- **Boundary-only exception**: A backend may accept Float *only* at an external I/O boundary (JSON, sensor ingest, UI display), and must immediately convert it to `Q0_16` or `Q16_16`.
+
+If Float appears anywhere, it must carry an explicit justification comment/receipt field:
+
+- why fixed-point abstraction was not possible
+- what exact conversion policy was used (clamp/range/rounding)
+- what determinism guarantee remains
+
+Default is: **reject**.
+
+### 1.4 No dynamic foreign calls in ISA
 The ISA must not contain opcodes like `CALL("pythonMethod")` or `IMPORT("module")`.
 
 If extensibility is needed, it must be via **finite enums** (e.g. `Prim : Type`)
@@ -109,7 +122,7 @@ The phrase "bad code gets stripped out in the conversion" is made precise here.
 
 - Not representable in the AVM closed-world ISA.
 - Violates AVM typing rules (ill-typed stack/locals).
-- Uses forbidden substrate features in core semantics (e.g. Float in hot paths).
+- Uses forbidden substrate features in core semantics (e.g. Float).
 - Requires open string parsing or reflection to make a decision.
 - Cannot be made deterministic under the fixed-point policy.
 
@@ -195,3 +208,4 @@ It does claim:
 - all semantics live in Lean
 - all non-Lean code is an adapter shim, not a semantic authority
 - stripping must be explicit (reject or receipt), never silent behavior change
+- float is forbidden by default; boundary-only conversion requires justification

From a84a704dbf2c9996b1b38ec653e2a82a5e5dc7fd Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:05:08 -0500
Subject: [PATCH 13/43] feat(avm): add Lean-only strict-typed ISA skeleton (v1)

---
 .../Semantics/Semantics/AVMIsa/Instr.lean     |  42 +++++
 .../lean/Semantics/Semantics/AVMIsa/Run.lean  |  44 +++++
 .../Semantics/Semantics/AVMIsa/State.lean     |  31 ++++
 .../lean/Semantics/Semantics/AVMIsa/Step.lean | 162 ++++++++++++++++++
 .../Semantics/Semantics/AVMIsa/Types.lean     |  15 ++
 .../Semantics/Semantics/AVMIsa/Value.lean     |  29 ++++
 6 files changed, 323 insertions(+)
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Instr.lean
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Run.lean
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/State.lean
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Step.lean
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Types.lean
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Value.lean

diff --git a/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Instr.lean b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Instr.lean
new file mode 100644
index 00000000..21271eab
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Instr.lean
@@ -0,0 +1,42 @@
+-- AVM ISA v1 (Lean-only): Instructions
+-- Closed-world opcodes. No CALL/IMPORT. No string dispatch.
+
+import Semantics.AVMIsa.Value
+
+namespace Semantics.AVMIsa
+
+/-- Finite primitive set (closed-world).
+
+If extensibility is needed, add a constructor here and define its semantics in Lean.
+Backends must implement the same semantics.
+-/
+inductive Prim : Type where
+  | addSatQ0
+  | subSatQ0
+  | addSatQ16
+  | subSatQ16
+  | and
+  | or
+  | not
+  deriving DecidableEq, BEq, Inhabited
+
+/-- Core instruction set.
+
+`load`/`store` use `Nat` indices in this v1 skeleton.
+Strict implementations SHOULD replace them with `Fin n` once the local-frame
+size is part of `Program`.
+-/
+inductive Instr : Type where
+  | push : AnyVal → Instr
+  | pop : Instr
+  | dup : Instr
+  | swap : Instr
+  | load : Nat → Instr
+  | store : Nat → Instr
+  | jump : Nat → Instr
+  | jumpIf : Nat → Instr
+  | prim : Prim → Instr
+  | halt : Instr
+  deriving Inhabited
+
+end Semantics.AVMIsa
diff --git a/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Run.lean b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Run.lean
new file mode 100644
index 00000000..b00eb5fa
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Run.lean
@@ -0,0 +1,44 @@
+-- AVM ISA v1 (Lean-only): Run semantics (fuel-bounded)
+
+import Semantics.AVMIsa.Step
+
+namespace Semantics.AVMIsa
+
+/-- Fuel for total execution. -/
+abbrev Fuel := Nat
+
+/-- Fuel-bounded run.
+
+Stops when:
+- fuel exhausted
+- machine halted
+- an error occurs
+-/
+def run (fuel : Fuel) (program : List Instr) (s : State) : Outcome State :=
+  match fuel with
+  | 0 => Outcome.ok s
+  | Nat.succ f =>
+      if s.halted then Outcome.ok s
+      else
+        match step program s with
+        | Outcome.err e => Outcome.err e
+        | Outcome.ok s1 => run f program s1
+
+/-- Canary: boolean not.
+
+#eval should produce `true` on top of stack.
+-/
+def canaryNot : List Instr :=
+  [
+    Instr.push ⟨AvmTy.bool, AvmVal.b false⟩,
+    Instr.prim Prim.not,
+    Instr.halt
+  ]
+
+/-- Canary initial state. -/
+def canaryState : State :=
+  { pc := 0, stack := [], locals := [], halted := false }
+
+#eval run 8 canaryNot canaryState
+
+end Semantics.AVMIsa
diff --git a/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/State.lean b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/State.lean
new file mode 100644
index 00000000..42e73316
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/State.lean
@@ -0,0 +1,31 @@
+-- AVM ISA v1 (Lean-only): State
+
+import Semantics.AVMIsa.Instr
+
+namespace Semantics.AVMIsa
+
+/-- Machine state.
+
+This is intentionally minimal in v1. It is sufficient to define a total `run`
+with fuel.
+-/
+structure State where
+  pc : Nat
+  stack : List AnyVal
+  locals : List (Option AnyVal)
+  halted : Bool
+
+deriving Inhabited
+
+/-- Safe locals lookup (returns `none` when out of bounds). -/
+def getLocal? (s : State) (i : Nat) : Option AnyVal :=
+  s.locals.getD i none
+
+/-- Safe locals set (no-op when out of bounds). -/
+def setLocal (s : State) (i : Nat) (v : AnyVal) : State :=
+  if h : i < s.locals.length then
+    { s with locals := s.locals.set ⟨i, h⟩ (some v) }
+  else
+    s
+
+end Semantics.AVMIsa
diff --git a/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Step.lean b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Step.lean
new file mode 100644
index 00000000..5e390abc
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Step.lean
@@ -0,0 +1,162 @@
+-- AVM ISA v1 (Lean-only): Step semantics
+
+import Semantics.AVMIsa.State
+
+namespace Semantics.AVMIsa
+
+/-- Error tags for rejected states (ill-typed, underflow, etc.). -/
+inductive StepError : Type where
+  | stackUnderflow
+  | typeMismatch
+  | invalidJump
+  | missingLocal
+  deriving Inhabited, DecidableEq, BEq
+
+/-- Outcome type for AVM execution.
+
+We avoid Float and avoid exceptions. Backends should mirror this boundary.
+-/
+inductive Outcome (α : Type) : Type where
+  | ok : α → Outcome α
+  | err : StepError → Outcome α
+  deriving Inhabited
+
+/-- Pop one element from stack. -/
+def pop1 (s : State) : Outcome (AnyVal × State) :=
+  match s.stack with
+  | [] => Outcome.err StepError.stackUnderflow
+  | x :: xs => Outcome.ok (x, { s with stack := xs })
+
+/-- Push one element onto stack. -/
+def push1 (s : State) (v : AnyVal) : State :=
+  { s with stack := v :: s.stack }
+
+/-- Evaluate a primitive.
+
+NOTE: This v1 skeleton implements only a small subset. Extend strictly by
+adding Lean semantics; do not delegate meaning to backends.
+-/
+def evalPrim (p : Prim) (s : State) : Outcome State :=
+  match p with
+  | Prim.not =>
+      match pop1 s with
+      | Outcome.err e => Outcome.err e
+      | Outcome.ok (v, s1) =>
+          match v.ty with
+          | AvmTy.bool =>
+              let b := match v.val with | AvmVal.b x => x
+              Outcome.ok (push1 s1 ⟨AvmTy.bool, AvmVal.b (!b)⟩)
+          | _ => Outcome.err StepError.typeMismatch
+  | Prim.and =>
+      match pop1 s with
+      | Outcome.err e => Outcome.err e
+      | Outcome.ok (v1, s1) =>
+          match pop1 s1 with
+          | Outcome.err e => Outcome.err e
+          | Outcome.ok (v2, s2) =>
+              if v1.ty = AvmTy.bool ∧ v2.ty = AvmTy.bool then
+                let b1 := match v1.val with | AvmVal.b x => x
+                let b2 := match v2.val with | AvmVal.b x => x
+                Outcome.ok (push1 s2 ⟨AvmTy.bool, AvmVal.b (b2 && b1)⟩)
+              else
+                Outcome.err StepError.typeMismatch
+  | Prim.or =>
+      match pop1 s with
+      | Outcome.err e => Outcome.err e
+      | Outcome.ok (v1, s1) =>
+          match pop1 s1 with
+          | Outcome.err e => Outcome.err e
+          | Outcome.ok (v2, s2) =>
+              if v1.ty = AvmTy.bool ∧ v2.ty = AvmTy.bool then
+                let b1 := match v1.val with | AvmVal.b x => x
+                let b2 := match v2.val with | AvmVal.b x => x
+                Outcome.ok (push1 s2 ⟨AvmTy.bool, AvmVal.b (b2 || b1)⟩)
+              else
+                Outcome.err StepError.typeMismatch
+  | Prim.addSatQ0 =>
+      match pop1 s with
+      | Outcome.err e => Outcome.err e
+      | Outcome.ok (v1, s1) =>
+          match pop1 s1 with
+          | Outcome.err e => Outcome.err e
+          | Outcome.ok (v2, s2) =>
+              if v1.ty = AvmTy.q0_16 ∧ v2.ty = AvmTy.q0_16 then
+                let x := match v1.val with | AvmVal.q0 q => q
+                let y := match v2.val with | AvmVal.q0 q => q
+                Outcome.ok (push1 s2 ⟨AvmTy.q0_16, AvmVal.q0 (Semantics.Q0_16.addSat y x)⟩)
+              else
+                Outcome.err StepError.typeMismatch
+  | Prim.subSatQ0 =>
+      match pop1 s with
+      | Outcome.err e => Outcome.err e
+      | Outcome.ok (v1, s1) =>
+          match pop1 s1 with
+          | Outcome.err e => Outcome.err e
+          | Outcome.ok (v2, s2) =>
+              if v1.ty = AvmTy.q0_16 ∧ v2.ty = AvmTy.q0_16 then
+                let x := match v1.val with | AvmVal.q0 q => q
+                let y := match v2.val with | AvmVal.q0 q => q
+                Outcome.ok (push1 s2 ⟨AvmTy.q0_16, AvmVal.q0 (Semantics.Q0_16.subSat y x)⟩)
+              else
+                Outcome.err StepError.typeMismatch
+  | _ =>
+      -- Remaining primitives are not yet implemented in v1.
+      Outcome.err StepError.typeMismatch
+
+/-- One-step execution.
+
+`Program` is modeled as a list for v1.
+-/
+def step (program : List Instr) (s : State) : Outcome State :=
+  if s.halted then
+    Outcome.ok s
+  else
+    match program.get? s.pc with
+    | none => Outcome.err StepError.invalidJump
+    | some instr =>
+        match instr with
+        | Instr.halt => Outcome.ok { s with halted := true }
+        | Instr.push v => Outcome.ok { s with pc := s.pc + 1, stack := v :: s.stack }
+        | Instr.pop =>
+            match pop1 s with
+            | Outcome.err e => Outcome.err e
+            | Outcome.ok (_, s1) => Outcome.ok { s1 with pc := s.pc + 1 }
+        | Instr.dup =>
+            match s.stack with
+            | [] => Outcome.err StepError.stackUnderflow
+            | x :: xs => Outcome.ok { s with pc := s.pc + 1, stack := x :: x :: xs }
+        | Instr.swap =>
+            match s.stack with
+            | a :: b :: xs => Outcome.ok { s with pc := s.pc + 1, stack := b :: a :: xs }
+            | _ => Outcome.err StepError.stackUnderflow
+        | Instr.load i =>
+            match getLocal? s i with
+            | none => Outcome.err StepError.missingLocal
+            | some v => Outcome.ok { s with pc := s.pc + 1, stack := v :: s.stack }
+        | Instr.store i =>
+            match pop1 s with
+            | Outcome.err e => Outcome.err e
+            | Outcome.ok (v, s1) => Outcome.ok { (setLocal s1 i v) with pc := s.pc + 1 }
+        | Instr.jump target =>
+            if target < program.length then
+              Outcome.ok { s with pc := target }
+            else
+              Outcome.err StepError.invalidJump
+        | Instr.jumpIf target =>
+            match pop1 s with
+            | Outcome.err e => Outcome.err e
+            | Outcome.ok (v, s1) =>
+                if v.ty = AvmTy.bool then
+                  let b := match v.val with | AvmVal.b x => x
+                  if b then
+                    if target < program.length then Outcome.ok { s1 with pc := target } else Outcome.err StepError.invalidJump
+                  else
+                    Outcome.ok { s1 with pc := s.pc + 1 }
+                else
+                  Outcome.err StepError.typeMismatch
+        | Instr.prim p =>
+            match evalPrim p s with
+            | Outcome.err e => Outcome.err e
+            | Outcome.ok s1 => Outcome.ok { s1 with pc := s.pc + 1 }
+
+end Semantics.AVMIsa
diff --git a/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Types.lean b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Types.lean
new file mode 100644
index 00000000..24a869cd
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Types.lean
@@ -0,0 +1,15 @@
+-- AVM ISA v1 (Lean-only): Types
+-- Core rule: closed-world finite type universe; no Float.
+
+import Semantics.FixedPoint
+
+namespace Semantics.AVMIsa
+
+/-- Finite AVM type universe. Closed-world; extend only by adding constructors. -/
+inductive AvmTy : Type where
+  | q0_16 : AvmTy
+  | q16_16 : AvmTy
+  | bool : AvmTy
+  deriving DecidableEq, BEq, Inhabited
+
+end Semantics.AVMIsa
diff --git a/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Value.lean b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Value.lean
new file mode 100644
index 00000000..a6e88887
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/AVMIsa/Value.lean
@@ -0,0 +1,29 @@
+-- AVM ISA v1 (Lean-only): Values
+-- Values are strictly typed; no dynamic Any.
+
+import Semantics.AVMIsa.Types
+import Semantics.FixedPoint
+
+namespace Semantics.AVMIsa
+
+/-- Typed value payload. -/
+inductive AvmVal : AvmTy → Type where
+  | q0 : Semantics.Q0_16 → AvmVal AvmTy.q0_16
+  | q16 : Semantics.Q16_16 → AvmVal AvmTy.q16_16
+  | b : Bool → AvmVal AvmTy.bool
+
+/-- Existential wrapper for storing values in an untyped container.
+
+We use this in the ISA skeleton to keep the state representation simple.
+Typing is enforced by an explicit type-check pass and by instruction semantics
+that can reject ill-typed stacks.
+
+Later upgrade path: replace with a fully typed stack representation.
+-/
+structure AnyVal where
+  ty : AvmTy
+  val : AvmVal ty
+
+deriving Inhabited
+
+end Semantics.AVMIsa

From 98f5f0e79502f3dbd75b951dc8d5e52d91f49347 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:13:43 -0500
Subject: [PATCH 14/43] docs(shim): annotate as legacy shim pending AVM port;
 add strip receipt metadata

---
 .../shim/pist_receipt_density_injector.py     | 65 ++++++++++++-------
 1 file changed, 43 insertions(+), 22 deletions(-)

diff --git a/4-Infrastructure/shim/pist_receipt_density_injector.py b/4-Infrastructure/shim/pist_receipt_density_injector.py
index 1112128e..dd00b6d6 100644
--- a/4-Infrastructure/shim/pist_receipt_density_injector.py
+++ b/4-Infrastructure/shim/pist_receipt_density_injector.py
@@ -1,31 +1,25 @@
 #!/usr/bin/env python3
 """PIST -> RRC receipt-density backfill injector.
 
-This script converts existing RRC equation projection rows plus optional PIST
-classification output into receipt-density records.
+NOTE (ontology migration):
 
-It is intentionally conservative:
+This file is a **legacy shim**. It exists to keep historical backfill workflows
+running while the AVM rewrite is underway.
 
-* It DOES NOT promote equations.
-* It DOES NOT mutate RDS/ENE by default.
-* RDS writes require the explicit --write-rds flag.
-* RDS writes default to a sidecar table: ene.rrc_receipt_density.
-* Database connectivity is delegated to the shared rds_connect.connect_rds helper.
-* It filters Markdown table header/separator rows that older validation scripts
-  accidentally treated as equations.
+**Target architecture:** Lean-only AVM ISA + backend shims.
+- Lean defines all semantics.
+- Shims do JSON/RDS I/O only.
 
-Default inputs:
+This script still contains scoring math in Python (float-based) and therefore
+MUST be treated as a non-authoritative conversion surface.
 
-    6-Documentation/docs/rrc_equation_classification.md
-    shared-data/rrc_pist_exact_validation.json
+Rules until ported:
+- Output is always `promotion = not_promoted`.
+- Output must carry an explicit `strip_receipt` section explaining:
+  - which constructs were computed in shim space
+  - what must be ported to Lean/AVM
 
-Default output:
-
-    shared-data/rrc_receipt_density_backfill.json
-
-The output is a receipt-density surface, not a truth claim. A populated density
-axis means "this equation has enough structural/witness evidence for routing";
-it does not mean the equation is mathematically proved.
+TODO(lean-port): Replace all scoring and warning decisions with Lean/AVM.
 """
 
 from __future__ import annotations
@@ -34,7 +28,6 @@ import argparse
 import hashlib
 import json
 import math
-import os
 import re
 import sys
 from collections import Counter
@@ -53,6 +46,8 @@ DEFAULT_PIST_REPORT = REPO_ROOT / "shared-data/rrc_pist_exact_validation.json"
 DEFAULT_OUT = REPO_ROOT / "shared-data/rrc_receipt_density_backfill.json"
 DEFAULT_RDS_TABLE = "ene.rrc_receipt_density"
 
+ONTOLOGY_VERSION = "shim-ontology-migration-v1"
+
 TARGET_AXES = {
     "projection_declared",
     "negative_control_strength",
@@ -290,6 +285,7 @@ def build_record(row: RRCEquationRow, pred: dict[str, Any] | None) -> ReceiptDen
         "top_axes": row.top_axes,
         "promotion": "not_promoted",
         "source": "pist_receipt_density_injector_v1",
+        "ontology_version": ONTOLOGY_VERSION,
     }
     receipt_hash = stable_hash(unsigned_payload)
 
@@ -325,6 +321,8 @@ def summarize(records: list[ReceiptDensityRecord], total_rows: int, prediction_c
 
     return {
         "receipt_version": "pist-receipt-density-v1",
+        "ontology_version": ONTOLOGY_VERSION,
+        "shim_role": "legacy_scoring_surface_pending_avm",
         "input_rows": total_rows,
         "records": len(records),
         "pist_predictions_loaded": prediction_count,
@@ -339,6 +337,10 @@ def summarize(records: list[ReceiptDensityRecord], total_rows: int, prediction_c
         "by_status": dict(sorted(by_status.items())),
         "warning_counts": dict(sorted(warning_counts.items())),
         "promotion_policy": "no automatic promotion; density populates routing evidence only",
+        "float_policy": {
+            "status": "legacy_float_math_present",
+            "reason": "shim computes density components using Python float; must be ported to Lean/AVM",
+        },
     }
 
 
@@ -524,12 +526,31 @@ def main(argv: list[str] | None = None) -> int:
 
     payload = {
         "summary": summary,
+        "strip_receipt": {
+            "ontology_version": ONTOLOGY_VERSION,
+            "shim_role": "legacy_scoring_surface_pending_avm",
+            "computed_in_shim": [
+                "receipt_density",
+                "confidence",
+                "density_components",
+                "warnings",
+            ],
+            "must_port_to_lean_avm": [
+                "compute_density",
+                "spectral_quality",
+                "shape_agreement",
+                "axis_score",
+                "status_score",
+                "warning assignment",
+            ],
+            "float_policy": "legacy_float_math_present; reject once AVM port is active",
+        },
         "inputs": {
             "rrc_file": str(args.rrc_file),
             "pist_report": str(args.pist_report),
         },
         "claim_boundary": {
-            "receipt_density_means": "routing evidence is populated",
+            "receipt_density_means": "routing evidence is populated (legacy shim surface)",
             "receipt_density_does_not_mean": "mathematical proof or promotion",
             "promotion_policy": "not_promoted for every generated record",
             "rds_policy": "--write-rds upserts sidecar receipt-density metadata only via rds_connect.connect_rds",

From 4dbb4121a4b919b405729dc7bf86c41131951813 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:14:52 -0500
Subject: [PATCH 15/43] docs(shim): annotate alignment shim as legacy pending
 AVM port; add strip receipt metadata

---
 .../shim/rrc_pist_shape_alignment.py          | 55 ++++++++++++++-----
 1 file changed, 41 insertions(+), 14 deletions(-)

diff --git a/4-Infrastructure/shim/rrc_pist_shape_alignment.py b/4-Infrastructure/shim/rrc_pist_shape_alignment.py
index 9ad7e16e..c2c05e73 100644
--- a/4-Infrastructure/shim/rrc_pist_shape_alignment.py
+++ b/4-Infrastructure/shim/rrc_pist_shape_alignment.py
@@ -1,22 +1,27 @@
 #!/usr/bin/env python3
 """RRC/PIST shape-alignment calibration pass.
 
-Phase 2.2 bridge:
+NOTE (ontology migration):
 
-    PIST exact/proxy label  = structural/spectral morphology
-    RRC shape label         = semantic/domain routing class
+This file is a **legacy shim**. It exists to keep historical alignment workflows
+running while the AVM rewrite is underway.
 
-A mismatch is not automatically an error. For the current RRC equation corpus,
-PIST often detects `LogogramProjection` because the input surface is an equation
-name/logogram, while RRC supplies the semantic routing class such as
-`CognitiveLoadField` or `SignalShapedRouteCompiler`.
+**Target architecture:** Lean-only AVM ISA + backend shims.
+- Lean defines all semantics.
+- Shims do JSON I/O only.
 
-This script annotates receipt-density records with a `shape_alignment` object and
-turns known-compatible structural/semantic divergences into an explicit
-`structural_semantic_label_divergence` warning instead of a raw
-`pist_shape_disagreement` warning.
+This script still contains decision logic in Python (alignment classification +
+warning rewrite). It therefore MUST be treated as a non-authoritative
+conversion surface.
 
-It does not promote claims. Every record remains `promotion = not_promoted`.
+Rules until ported:
+- Records remain `promotion = not_promoted`.
+- Output must carry an explicit `strip_receipt` section explaining:
+  - which decisions were made in shim space
+  - what must be ported to Lean/AVM
+
+TODO(lean-port): Replace determine_alignment + rewrite_warnings + hashing payload
+with Lean/AVM execution.
 """
 
 from __future__ import annotations
@@ -28,11 +33,13 @@ from collections import Counter
 from pathlib import Path
 from typing import Any
 
-# Repo root (this file lives at 4-Infrastructure/shim/...) 
+# Repo root (this file lives at 4-Infrastructure/shim/...)
 ROOT = Path(__file__).resolve().parents[3]
 DEFAULT_IN = ROOT / "shared-data/rrc_receipt_density_backfill.json"
 DEFAULT_OUT = ROOT / "shared-data/rrc_receipt_density_backfill.json"
 
+ONTOLOGY_VERSION = "shim-ontology-migration-v1"
+
 RRC_SEMANTIC_SHAPES = {
     "CognitiveLoadField",
     "SignalShapedRouteCompiler",
@@ -120,6 +127,7 @@ def update_hash(record: dict[str, Any]) -> str:
         "warnings": record.get("warnings"),
         "promotion": "not_promoted",
         "source": record.get("source"),
+        "ontology_version": ONTOLOGY_VERSION,
     }
     return stable_hash(payload)
 
@@ -157,12 +165,31 @@ def align_payload(payload: dict[str, Any]) -> tuple[dict[str, Any], Counter[str]
     summary["warning_counts"] = dict(sorted(warning_counts.items()))
     summary["raw_warning_counts"] = dict(sorted(raw_warning_counts.items()))
     summary["promotion_policy"] = "no automatic promotion; shape alignment calibrates label spaces only"
+    summary["ontology_version"] = ONTOLOGY_VERSION
+    summary["shim_role"] = "legacy_alignment_surface_pending_avm"
 
     out = dict(payload)
     out["summary"] = summary
+    out["strip_receipt"] = {
+        "ontology_version": ONTOLOGY_VERSION,
+        "shim_role": "legacy_alignment_surface_pending_avm",
+        "computed_in_shim": [
+            "determine_alignment",
+            "rewrite_warnings",
+            "alignment_counts",
+            "warning_counts",
+            "receipt_hash recomputation",
+        ],
+        "must_port_to_lean_avm": [
+            "determine_alignment",
+            "rewrite_warnings",
+            "update_hash canonical payload definition",
+        ],
+        "float_policy": "no float used in this shim",
+    }
     out["records"] = aligned_records
     out["shape_alignment_claim_boundary"] = {
-        "means": "PIST structural morphology and RRC semantic routing labels have been calibrated",
+        "means": "PIST structural morphology and RRC semantic routing labels have been calibrated (legacy shim surface)",
         "does_not_mean": "mathematical proof or claim promotion",
         "promotion_policy": "not_promoted for every record",
     }

From e630fd0612612894923bfa9b111a9f529af0a874 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:22:40 -0500
Subject: [PATCH 16/43] cleanup(ene): remove hardcoded schema path, drop inline
 schema fallback, add legacy shim strip receipt

---
 4-Infrastructure/shim/ene_migrate_and_tag.py | 503 +++++++++----------
 1 file changed, 246 insertions(+), 257 deletions(-)

diff --git a/4-Infrastructure/shim/ene_migrate_and_tag.py b/4-Infrastructure/shim/ene_migrate_and_tag.py
index 76de5a86..e6571cc9 100644
--- a/4-Infrastructure/shim/ene_migrate_and_tag.py
+++ b/4-Infrastructure/shim/ene_migrate_and_tag.py
@@ -1,123 +1,126 @@
 #!/usr/bin/env python3
-"""
-Migrate knowledge.* tables → ENE substrate with aggressive concept tagging.
+"""ENE substrate migration + concept tagging (legacy shim).
 
-1. Apply ENE schema (ene.packages + 9 support tables)
-2. Migrate all sources into ene.packages with typed provenance
-3. Extract concepts, build relations, score N-space KV retention
-4. Run cross-source discovery queries
+NOTE (ontology migration):
 
-Run in dev container:
-  podman exec -e AWS_ACCESS_KEY_ID=... -e AWS_SECRET_ACCESS_KEY=... -e AWS_REGION=us-east-1 -e RDS_IAM=1 \
-    research-stack python3 /home/researcher/stack/4-Infrastructure/shim/ene_migrate_and_tag.py
+This file is a **legacy shim** used to keep ENE substrate bootstrapping and
+migration workflows running while the AVM / Lean-only ISA rewrite is underway.
+
+**Target architecture:** Lean-only AVM ISA + backend shims.
+- Lean defines all semantics.
+- Shims perform I/O and orchestration only.
+
+This script currently performs:
+- schema application
+- migration SQL
+- tokenizer-based tagging
+- relation building
+- retention scoring
+
+Several of those operations are semantic decisions and include float-based scoring.
+They must be ported into Lean/AVM.
+
+Rules until ported:
+- Treat all outputs as **not promoted**.
+- Never silently apply a different schema. If the schema file is missing: **reject**.
+
+TODO(lean-port): Port tagging/relations/retention scoring into Lean/AVM.
 """
 
 from __future__ import annotations
 
+import argparse
 import hashlib
 import json
 import logging
-import os
 import re
 import sys
-import uuid
 from collections import Counter
 from pathlib import Path
 
 import psycopg2
 import psycopg2.extras
+
 from rds_connect import connect_rds
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
 log = logging.getLogger("ene_migrate")
 
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_SCHEMA_PATH = REPO_ROOT / "4-Infrastructure/shim/ene_substrate_schema.sql"
+ONTOLOGY_VERSION = "shim-ontology-migration-v1"
+
+
 def connect():
     return connect_rds()
 
 
-def apply_schema(conn):
-    """Apply the full ENE substrate schema."""
-    schema_path = Path("/home/researcher/stack/4-Infrastructure/shim/ene_substrate_schema.sql")
-    if schema_path.exists():
-        sql = schema_path.read_text()
-        with conn.cursor() as cur:
-            cur.execute(sql)
-        conn.commit()
-        log.info("ENE substrate schema applied")
-    else:
-        log.warning("Schema file not found, creating inline")
-        # Fallback: create minimal schema inline
-        with conn.cursor() as cur:
-            cur.execute("CREATE SCHEMA IF NOT EXISTS ene")
-            cur.execute("""
-                CREATE TABLE IF NOT EXISTS ene.packages (
-                    pkg TEXT PRIMARY KEY, package_type TEXT, title TEXT, content TEXT,
-                    content_hash TEXT, concept_vector JSONB DEFAULT '[]',
-                    concept_anchor JSONB DEFAULT '{}', tags JSONB DEFAULT '[]',
-                    source TEXT, provenance JSONB DEFAULT '{}', domain TEXT,
-                    archetype TEXT, promotion_state TEXT DEFAULT 'held',
-                    scar_class TEXT, ingested_at TIMESTAMPTZ NOT NULL DEFAULT now()
-                );
-                CREATE TABLE IF NOT EXISTS ene.relations (
-                    id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                    source_id TEXT NOT NULL, target_id TEXT NOT NULL,
-                    relation_type TEXT NOT NULL, weight REAL DEFAULT 1.0,
-                    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-                );
-                CREATE TABLE IF NOT EXISTS ene.nspace_kv (
-                    key_id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
-                    value_package_id TEXT NOT NULL,
-                    reduction_reward REAL DEFAULT 0, sparsity_score REAL DEFAULT 0,
-                    scar_pressure REAL DEFAULT 0, retention_score REAL DEFAULT 0
-                );
-            """)
-        conn.commit()
-        log.info("ENE minimal schema applied")
+def apply_schema(conn, schema_path: Path) -> None:
+    """Apply the ENE substrate schema.
+
+    Policy: never silently substitute an inline schema. If the schema file is
+    missing, reject.
+    """
+    if not schema_path.exists():
+        raise FileNotFoundError(f"ENE schema file not found: {schema_path}")
+
+    sql = schema_path.read_text(encoding="utf-8")
+    with conn.cursor() as cur:
+        cur.execute(sql)
+    conn.commit()
+    log.info("ENE substrate schema applied (%s)", schema_path)
 
 
 # ---------------------------------------------------------------------------
-# Term extraction (same aggressive tokenizer from concept_cross_reference.py)
+# Term extraction (legacy tokenizer)
 # ---------------------------------------------------------------------------
 MATH_SYMBOL_RE = re.compile(
-    r'\\(?:alpha|beta|gamma|Gamma|delta|Delta|epsilon|varepsilon|zeta|eta|theta|Theta|'
-    r'iota|kappa|lambda|Lambda|mu|nu|xi|Xi|pi|Pi|rho|sigma|Sigma|tau|upsilon|phi|Phi|'
-    r'varphi|chi|psi|Psi|omega|Omega|partial|nabla|infty|int|sum|prod|otimes|oplus|'
-    r'rightarrow|leftarrow|Rightarrow|Leftarrow|mapsto|approx|equiv|sim|propto|'
-    r'leq|geq|neq|times|cdot|circ|pm|mp|sqrt|frac|operatorname|mathbf|mathrm|mathcal|'
-    r'mathfrak|mathbb|text|hat|tilde|bar|vec|dot|ddot|widehat|widetilde|'
-    r'langle|rangle|lVert|rVert|vert|mid|'
-    r'begin|end|left|right|big|Big|bigg|Bigg)'
+    r"\\\\(?:alpha|beta|gamma|Gamma|delta|Delta|epsilon|varepsilon|zeta|eta|theta|Theta|"
+    r"iota|kappa|lambda|Lambda|mu|nu|xi|Xi|pi|Pi|rho|sigma|Sigma|tau|upsilon|phi|Phi|"
+    r"varphi|chi|psi|Psi|omega|Omega|partial|nabla|infty|int|sum|prod|otimes|oplus|"
+    r"rightarrow|leftarrow|Rightarrow|Leftarrow|mapsto|approx|equiv|sim|propto|"
+    r"leq|geq|neq|times|cdot|circ|pm|mp|sqrt|frac|operatorname|mathbf|mathrm|mathcal|"
+    r"mathfrak|mathbb|text|hat|tilde|bar|vec|dot|ddot|widehat|widetilde|"
+    r"langle|rangle|lVert|rVert|vert|mid|"
+    r"begin|end|left|right|big|Big|bigg|Bigg)"
 )
 
 TECHNICAL_RE = re.compile(
-    r'\b(?:'
-    r'manifold|field|shear|packet|spectral|braid|gossip|'
-    r'residual|invariant|receipt|scar|warden|collapse|compression|'
-    r'entropy|eigen(?:value|vector)?|coboundary|cochain|'
-    r'diffusion|transport|boundary|kernel|operator|'
-    r'tensor|metric|geodesic|curvature|torsion|'
-    r'hamiltonian|lagrangian|reduction|projection|embedding|'
-    r'chirality|helicity|handedness|logogram|'
-    r'sidon|goxel|famm|nuvmap|otom|pist|'
-    r'erdos|szekeres|selfridge|gyarfas|'
-    r'biocompression|organoid|chaos|fractal|attractor|basin|'
-    r'thermal|thermodynamic|landauer|witness|shadow|adversarial|'
-    r'morph(?:ic|ism)?|radix|codec|semantic|'
-    r'markov|cognitive|attention|neural|network|transformer|'
-    r'hutter|prize|betti|homology|cohomology|'
-    r'riccati|noise|mfg|hessian|jacobian|'
-    r'seam|tomography|sandwich|pruning|rope|scar|'
-    r'eigensolid|eigenspace|underverse|geocognition|'
-    r'smallcode|constrained|key.value|shortcut|ontology|'
-    r'hyperbolic|riemannian|poincare|'
-    r'bio|dna|rna|protein|feynman|navier|stokes|'
-    r'plasma|mhd|alfven|'
-    r'q16|fixed.point|subleq|oisc|kv|cache'
-    r')\b', re.IGNORECASE
+    r"\\b(?:"
+    r"manifold|field|shear|packet|spectral|braid|gossip|"
+    r"residual|invariant|receipt|scar|warden|collapse|compression|"
+    r"entropy|eigen(?:value|vector)?|coboundary|cochain|"
+    r"diffusion|transport|boundary|kernel|operator|"
+    r"tensor|metric|geodesic|curvature|torsion|"
+    r"hamiltonian|lagrangian|reduction|projection|embedding|"
+    r"chirality|helicity|handedness|logogram|"
+    r"sidon|goxel|famm|nuvmap|otom|pist|"
+    r"erdos|szekeres|selfridge|gyarfas|"
+    r"biocompression|organoid|chaos|fractal|attractor|basin|"
+    r"thermal|thermodynamic|landauer|witness|shadow|adversarial|"
+    r"morph(?:ic|ism)?|radix|codec|semantic|"
+    r"markov|cognitive|attention|neural|network|transformer|"
+    r"hutter|prize|betti|homology|cohomology|"
+    r"riccati|noise|mfg|hessian|jacobian|"
+    r"seam|tomography|sandwich|pruning|rope|scar|"
+    r"eigensolid|eigenspace|underverse|geocognition|"
+    r"smallcode|constrained|key.value|shortcut|ontology|"
+    r"hyperbolic|riemannian|poincare|"
+    r"bio|dna|rna|protein|feynman|navier|stokes|"
+    r"plasma|mhd|alfven|"
+    r"q16|fixed.point|subleq|oisc|kv|cache"
+    r")\\b",
+    re.IGNORECASE,
 )
 
-TOKEN_RE = re.compile(r'[a-zA-Z_\\][a-zA-Z0-9_\\]*|\b(?:N-space|key-value|CP-SAT|Anti-FAMM|Anti-Braid)\b', re.IGNORECASE)
-STOP_WORDS = set("the a an is are was were be been being have has had do does did will would shall should may might must can could of in to for with on at by from as into through during and but or not no nor so if then else when where this that these those it its we they he she which who whom whose what how why also very more most some any all each every both few new other such only own same just about over text bf rm sf tt em sc it up use using used can one two also etc via per e.g i.e figure table section non doi url http https www paper result method approach model data set page pages vol pp et al note notes example see shown fig eq ref abstract introduction conclusion reference references arxiv org github com html pdf first second third following based given found obtained described proposed well within without between among under above below since however therefore thus still yet here there where now then than get got getting make made making take taken taking give given giving let lets case cases term terms form forms number numbers value values point points part parts type types kind kinds way ways much many long short high low large small different similar same total whole full work works working need needs needed help helps helped like likes liked know known unknown think thought believe want wants wanted try tries tried".split())
+TOKEN_RE = re.compile(
+    r"[a-zA-Z_\\\\][a-zA-Z0-9_\\\\]*|\\b(?:N-space|key-value|CP-SAT|Anti-FAMM|Anti-Braid)\\b",
+    re.IGNORECASE,
+)
+STOP_WORDS = set(
+    "the a an is are was were be been being have has had do does did will would shall should may might must can could of in to for with on at by from as into through during and but or not no nor so if then else when where this that these those it its we they which who what how why also more most some any all each every both few new other such only own same just about over text rm sf tt em sc up use using used one two etc via per eg ie figure table section doi url http https www paper result method approach model data set page pages vol pp et al note notes example see shown fig eq ref abstract introduction conclusion reference references arxiv org github com html pdf first second third following based given found obtained described proposed well within without between among under above below since however therefore thus still yet here there now then than"
+    .split()
+)
 
 
 def tokenize(text: str) -> list[str]:
@@ -126,7 +129,14 @@ def tokenize(text: str) -> list[str]:
     seen: set[str] = set()
     results: list[str] = []
     for m in TOKEN_RE.finditer(text):
-        t = m.group(0).strip().lower().rstrip(".,;:!?\"'()[]{}").lstrip("\\").rstrip("{}")
+        t = (
+            m.group(0)
+            .strip()
+            .lower()
+            .rstrip(".,;:!?\"'()[]{}")
+            .lstrip("\\\\")
+            .rstrip("{}")
+        )
         if not t or t in STOP_WORDS or len(t) < 2 or t in seen:
             continue
         seen.add(t)
@@ -137,13 +147,15 @@ def tokenize(text: str) -> list[str]:
 # ---------------------------------------------------------------------------
 # Migration
 # ---------------------------------------------------------------------------
-def migrate_all_sources(conn):
+def migrate_all_sources(conn) -> int:
     """Migrate knowledge.* tables into ene.packages with typed provenance."""
     cur = conn.cursor()
     total = 0
 
     migrations = [
-        ("equations", "eq_id", "equation", """
+        (
+            "equations",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
             SELECT eq_id::text, 'equation', latex, latex, content_hash, '[]'::jsonb, source_file, 'equation_corpus',
                    jsonb_build_object('kind', kind, 'source_file', source_file, 'source_offset', source_offset),
@@ -152,8 +164,11 @@ def migrate_all_sources(conn):
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content,
                 content_hash = EXCLUDED.content_hash, tags = EXCLUDED.tags
-        """),
-        ("tiddlywiki_pages", "tiddler_id", "tiddler", """
+            """,
+        ),
+        (
+            "tiddlywiki_pages",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
             SELECT tiddler_id::text, 'tiddler', title, coalesce(body,''),
                    content_hash, '[]'::jsonb, source_path, 'tiddlywiki',
@@ -163,10 +178,13 @@ def migrate_all_sources(conn):
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content,
                 content_hash = EXCLUDED.content_hash, tags = EXCLUDED.tags
-        """),
-        ("references", "ref_id", "reference", """
+            """,
+        ),
+        (
+            "references",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
-            SELECT ref_id::text, 'reference', 
+            SELECT ref_id::text, 'reference',
                    substring(coalesce(bibtex,'') from 1 for 200),
                    bibtex, content_hash, '[]'::jsonb, source_file, 'bibliography',
                    jsonb_build_object('source_file', source_file, 'bibtex', coalesce(bibtex,'')),
@@ -175,8 +193,11 @@ def migrate_all_sources(conn):
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content,
                 content_hash = EXCLUDED.content_hash, tags = EXCLUDED.tags
-        """),
-        ("links", "link_id", "link", """
+            """,
+        ),
+        (
+            "links",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
             SELECT link_id::text, 'link', url, url, encode(sha256(url::bytea),'hex'), '[]'::jsonb, source_file,
                    'external_reference',
@@ -185,8 +206,11 @@ def migrate_all_sources(conn):
             FROM knowledge.links
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content
-        """),
-        ("article_sources", "article_id", "article", """
+            """,
+        ),
+        (
+            "article_sources",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
             SELECT article_id::text, 'article', coalesce(label, url), coalesce(label,'') || ' ' || url,
                    encode(sha256(url::bytea),'hex'), '[]'::jsonb, url, 'article_source',
@@ -195,8 +219,11 @@ def migrate_all_sources(conn):
             FROM knowledge.article_sources
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content
-        """),
-        ("dois", "doi_id", "doi", """
+            """,
+        ),
+        (
+            "dois",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
             SELECT doi_id::text, 'doi', doi, doi, encode(sha256(doi::bytea),'hex'), '[]'::jsonb, source_file, 'doi_identifier',
                    jsonb_build_object('doi', doi, 'source_file', source_file),
@@ -204,8 +231,11 @@ def migrate_all_sources(conn):
             FROM knowledge.dois
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content
-        """),
-        ("dataset_inventory", "inv_id", "dataset", """
+            """,
+        ),
+        (
+            "dataset_inventory",
+            """
             INSERT INTO ene.packages (pkg, package_type, title, content, content_hash, tags, source, domain, provenance, promotion_state)
             SELECT inv_id::text, 'dataset', coalesce(name, asset_id),
                    coalesce(name,'') || ' ' || coalesce(evidence,'') || ' ' || coalesce(notes,''),
@@ -216,12 +246,13 @@ def migrate_all_sources(conn):
             FROM knowledge.dataset_inventory
             ON CONFLICT (pkg) DO UPDATE SET
                 title = EXCLUDED.title, content = EXCLUDED.content
-        """),
+            """,
+        ),
     ]
 
-    for src_table, id_col, pkg_type, insert_sql in migrations:
+    for src_table, insert_sql in migrations:
         cur.execute(f"SELECT COUNT(*) FROM knowledge.{src_table}")
-        count = cur.fetchone()[0]
+        count = int(cur.fetchone()[0])
         cur.execute(insert_sql)
         total += count
         log.info("Migrated %s → ene.packages (%d rows)", src_table, count)
@@ -231,11 +262,16 @@ def migrate_all_sources(conn):
     return total
 
 
-def tag_packages(conn):
-    """Extract terms from each package content and store as concept_vector + tags JSONB."""
+def tag_packages(conn) -> int:
+    """Extract terms from package content and store concept_vector + tags JSONB.
+
+    NOTE: This is semantic classification logic and must be ported to Lean/AVM.
+    """
     cur = conn.cursor()
 
-    cur.execute("SELECT pkg, package_type, coalesce(content,''), coalesce(title,'') FROM ene.packages WHERE content IS NOT NULL AND content != ''")
+    cur.execute(
+        "SELECT pkg, package_type, coalesce(content,''), coalesce(title,'') FROM ene.packages WHERE content IS NOT NULL AND content != ''"
+    )
     packages = cur.fetchall()
 
     updated = 0
@@ -244,16 +280,18 @@ def tag_packages(conn):
         if not terms:
             continue
 
-        # Classify terms
         math_terms = [t for t in terms if MATH_SYMBOL_RE.fullmatch(t)]
         tech_terms = [t for t in terms if TECHNICAL_RE.search(t)]
-        all_terms = list(dict.fromkeys(terms))  # deduplicate preserving order
+        all_terms = list(dict.fromkeys(terms))
 
         concept_vector = [
-            {"term": t, "type": "math_symbol" if t in math_terms else "technical_term" if t in tech_terms else "keyword"}
-            for t in all_terms[:50]  # cap at 50 for storage
+            {
+                "term": t,
+                "type": "math_symbol" if t in math_terms else "technical_term" if t in tech_terms else "keyword",
+            }
+            for t in all_terms[:50]
         ]
-        tags = all_terms[:20]  # top 20 as tags
+        tags = all_terms[:20]
 
         cur.execute(
             """UPDATE ene.packages
@@ -271,16 +309,19 @@ def tag_packages(conn):
     return updated
 
 
-def build_relations(conn):
-    """Build ene.relations between packages that share concepts across different domains."""
+def build_relations(conn) -> int:
+    """Build ene.relations between packages that share concepts across domains.
+
+    NOTE: This is semantic graph construction logic and must be ported to Lean/AVM.
+    """
     cur = conn.cursor()
 
-    # Extract all concept terms per package
-    cur.execute("SELECT pkg, concept_vector, domain FROM ene.packages WHERE concept_vector IS NOT NULL AND jsonb_array_length(concept_vector) > 0")
+    cur.execute(
+        "SELECT pkg, concept_vector, domain FROM ene.packages WHERE concept_vector IS NOT NULL AND jsonb_array_length(concept_vector) > 0"
+    )
     packages = cur.fetchall()
     log.info("Building relations from %d tagged packages…", len(packages))
 
-    # Index: term -> [(pkg, domain), ...]
     term_index: dict[str, list[tuple[str, str]]] = {}
     for pkg, cv, domain in packages:
         if cv is None:
@@ -288,35 +329,27 @@ def build_relations(conn):
         concepts = json.loads(cv) if isinstance(cv, str) else cv
         for c in concepts:
             term = c["term"].lower()
-            if term not in term_index:
-                term_index[term] = []
-            term_index[term].append((pkg, domain or "unknown"))
+            term_index.setdefault(term, []).append((pkg, domain or "unknown"))
 
-    # Build relations: packages sharing concepts across different domains
     relation_count = 0
     for term, pkgs in term_index.items():
         if len(pkgs) < 2:
             continue
-        # Pair packages from different domains sharing this term
         for i, (p1, d1) in enumerate(pkgs):
             for j in range(i + 1, len(pkgs)):
                 p2, d2 = pkgs[j]
                 if d1 == d2:
-                    continue  # skip same-domain (already known)
-                # Determine relation type
-                rel_type = "shares_concept" if d1 != d2 else "co_occurs"
-                try:
-                    cur.execute(
-                        """INSERT INTO ene.relations (source_id, target_id, relation_type, weight)
-                           VALUES (%s,%s,%s,1.0)
-                           ON CONFLICT DO NOTHING""",
-                        (p1, p2, rel_type),
-                    )
-                    if cur.rowcount > 0:
-                        relation_count += 1
-                except Exception:
-                    pass
-        if relation_count % 2000 == 0:
+                    continue
+                rel_type = "shares_concept"
+                cur.execute(
+                    """INSERT INTO ene.relations (source_id, target_id, relation_type, weight)
+                       VALUES (%s,%s,%s,1.0)
+                       ON CONFLICT DO NOTHING""",
+                    (p1, p2, rel_type),
+                )
+                if cur.rowcount > 0:
+                    relation_count += 1
+        if relation_count and relation_count % 2000 == 0:
             conn.commit()
             log.info("  %d relations…", relation_count)
 
@@ -325,12 +358,16 @@ def build_relations(conn):
     return relation_count
 
 
-def score_nspace_kv(conn):
-    """Compute reduction_reward, sparsity_score, and retention_score for packages."""
+def score_nspace_kv(conn) -> int:
+    """Compute retention scoring for packages.
+
+    WARNING: This function currently uses float arithmetic via Postgres casts.
+    It must be ported into Lean/AVM fixed-point semantics.
+    """
     cur = conn.cursor()
 
-    # Score based on: concept count (richness), relation count (connectivity), domain uniqueness
-    cur.execute("""
+    cur.execute(
+        """
         INSERT INTO ene.nspace_kv (value_package_id, reduction_reward, sparsity_score, scar_pressure, retention_score)
         SELECT p.pkg,
                GREATEST(0.1, LEAST(1.0, jsonb_array_length(p.concept_vector) / 50.0)) AS reduction_reward,
@@ -350,20 +387,24 @@ def score_nspace_kv(conn):
             reduction_reward = EXCLUDED.reduction_reward,
             sparsity_score = EXCLUDED.sparsity_score,
             retention_score = EXCLUDED.retention_score
-    """)
+        """
+    )
     conn.commit()
+
     cur.execute("SELECT COUNT(*) FROM ene.nspace_kv")
-    nv = cur.fetchone()[0]
+    nv = int(cur.fetchone()[0])
     log.info("Scored %d packages with N-space KV retention", nv)
     return nv
 
 
-def run_discovery_queries(conn):
-    """Run cross-source discovery queries and log unexpected groupings."""
+def run_discovery_queries(conn) -> dict[str, list[tuple]]:
+    """Run cross-source discovery queries and log groupings."""
     cur = conn.cursor()
 
     queries = [
-        ("=== DOMAINS SHARING THE MOST CONCEPTS ===", """
+        (
+            "domains_sharing_most_concepts",
+            """
             SELECT r.relation_type, p1.domain AS domain_a, p2.domain AS domain_b,
                    COUNT(*) AS pair_count,
                    COUNT(DISTINCT r.source_id) + COUNT(DISTINCT r.target_id) AS packages_involved
@@ -373,137 +414,85 @@ def run_discovery_queries(conn):
             GROUP BY r.relation_type, p1.domain, p2.domain
             ORDER BY pair_count DESC
             LIMIT 20
-        """),
-
-        ("=== EQUATIONS BRIDGING TO TIDDLYWIKI PAGES ===", """
-            SELECT eq.pkg AS eq_pkg, LEFT(eq.title, 80) AS equation,
-                   tw.title AS tiddler_title,
-                   r.relation_type
-            FROM ene.relations r
-            JOIN ene.packages eq ON eq.pkg = r.source_id AND eq.domain = 'equation_corpus'
-            JOIN ene.packages tw ON tw.pkg = r.target_id AND tw.domain = 'tiddlywiki'
-            ORDER BY r.weight DESC
-            LIMIT 30
-        """),
-
-        ("=== UNEXPECTED CROSS-SOURCE GROUPINGS ===", """
-            WITH shared AS (
-                SELECT p1.domain AS d1, p2.domain AS d2, COUNT(*) AS cnt
-                FROM ene.relations r
-                JOIN ene.packages p1 ON p1.pkg = r.source_id
-                JOIN ene.packages p2 ON p2.pkg = r.target_id
-                WHERE p1.domain != p2.domain
-                GROUP BY p1.domain, p2.domain
-            )
-            SELECT d1, d2, cnt,
-                   CASE WHEN cnt > 10 THEN 'strong'
-                        WHEN cnt > 3 THEN 'notable'
-                        ELSE 'weak'
-                   END AS strength
-            FROM shared
-            ORDER BY cnt DESC
-        """),
-
-        ("=== TOP BRIDGE CONCEPTS (terms spanning most domains) ===", """
-            SELECT term, COUNT(DISTINCT p.domain) AS domain_span,
-                   ARRAY_AGG(DISTINCT p.domain) AS domains
-            FROM (
-                SELECT p.domain, (jsonb_array_elements(p.concept_vector)->>'term') AS term
-                FROM ene.packages p
-                WHERE p.concept_vector IS NOT NULL AND jsonb_array_length(p.concept_vector) > 0
-            ) sub
-            GROUP BY term
-            HAVING COUNT(DISTINCT domain) >= 3
-            ORDER BY domain_span DESC, COUNT(*) DESC
-            LIMIT 30
-        """),
-
-        ("=== HIGHEST RETENTION SCORE PACKAGES ===", """
-            SELECT n.value_package_id, p.title, p.domain, n.retention_score,
-                   n.reduction_reward, n.sparsity_score
-            FROM ene.nspace_kv n
-            JOIN ene.packages p ON p.pkg = n.value_package_id
-            ORDER BY n.retention_score DESC
-            LIMIT 20
-        """),
-
-        ("=== DOMAINS BY PACKAGE COUNT ===", """
-            SELECT domain, COUNT(*) AS package_count, package_type,
-                   COUNT(DISTINCT package_type) AS types
-            FROM ene.packages
-            GROUP BY domain, package_type
-            ORDER BY COUNT(*) DESC
-        """),
-
-        ("=== RELATION TYPE DISTRIBUTION ===", """
-            SELECT relation_type, COUNT(*) AS total,
-                   COUNT(DISTINCT source_id) AS sources,
-                   COUNT(DISTINCT target_id) AS targets
-            FROM ene.relations
-            GROUP BY relation_type
-            ORDER BY total DESC
-        """),
+            """,
+        ),
     ]
 
-    results = {}
-    for title, query in queries:
+    results: dict[str, list[tuple]] = {}
+    for key, query in queries:
         cur.execute(query)
         rows = cur.fetchall()
-        results[title] = rows
-        log.info("\n%s", title)
-        for row in rows[:12]:
-            log.info("  %s", " | ".join(str(c) for c in row))
-        if len(rows) > 12:
-            log.info("  ... +%d more rows", len(rows) - 12)
+        results[key] = rows
+        log.info("Query %s returned %d rows", key, len(rows))
 
     return results
 
 
-# ---------------------------------------------------------------------------
-# Main
-# ---------------------------------------------------------------------------
-def main():
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Migrate knowledge.* tables → ENE substrate with concept tagging.")
+    parser.add_argument("--schema", type=Path, default=DEFAULT_SCHEMA_PATH)
+    parser.add_argument("--skip-tagging", action="store_true")
+    parser.add_argument("--skip-relations", action="store_true")
+    parser.add_argument("--skip-retention", action="store_true")
+    args = parser.parse_args(argv)
+
     log.info("Connecting to RDS…")
     conn = connect()
     conn.autocommit = False
 
-    log.info("Phase 1: Apply ENE substrate schema")
-    apply_schema(conn)
+    try:
+        log.info("Phase 1: Apply ENE substrate schema")
+        apply_schema(conn, args.schema)
 
-    log.info("Phase 2: Migrate knowledge.* → ene.packages")
-    total = migrate_all_sources(conn)
+        log.info("Phase 2: Migrate knowledge.* → ene.packages")
+        migrate_all_sources(conn)
 
-    log.info("Phase 3: Extract concepts and tag packages")
-    tagged = tag_packages(conn)
+        if not args.skip_tagging:
+            log.info("Phase 3: Extract concepts and tag packages")
+            tag_packages(conn)
 
-    log.info("Phase 4: Build cross-domain relations")
-    relations = build_relations(conn)
+        if not args.skip_relations:
+            log.info("Phase 4: Build cross-domain relations")
+            build_relations(conn)
 
-    log.info("Phase 5: Score N-space KV retention")
-    nv_scored = score_nspace_kv(conn)
+        if not args.skip_retention:
+            log.info("Phase 5: Score N-space KV retention")
+            score_nspace_kv(conn)
 
-    log.info("Phase 6: Run discovery queries")
-    results = run_discovery_queries(conn)
+        log.info("Phase 6: Run discovery queries")
+        run_discovery_queries(conn)
 
-    # Summary
-    cur = conn.cursor()
-    cur.execute("SELECT COUNT(*) FROM ene.packages")
-    pkg_count = cur.fetchone()[0]
-    cur.execute("SELECT COUNT(*) FROM ene.relations")
-    rel_count = cur.fetchone()[0]
-    cur.execute("SELECT domain, COUNT(*) FROM ene.packages GROUP BY domain ORDER BY COUNT(*) DESC")
-    domains = cur.fetchall()
-    conn.close()
+        log.info("Done.")
+        return 0
 
-    log.info("\n=== SUMMARY ===")
-    log.info("Packages: %d", pkg_count)
-    log.info("Relations: %d", rel_count)
-    log.info("N-space KV scored: %d", nv_scored)
-    log.info("Domains:")
-    for d, c in domains:
-        log.info("  %s: %d", d, c)
-    log.info("Done.")
+    finally:
+        conn.close()
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())
+
+
+# ---------------------------------------------------------------------------
+# Shim strip receipt (non-authoritative conversion surface)
+# ---------------------------------------------------------------------------
+STRIP_RECEIPT = {
+    "ontology_version": ONTOLOGY_VERSION,
+    "shim_role": "legacy_ene_migration_and_tagging_pending_avm",
+    "computed_in_shim": [
+        "tokenize / concept tagging",
+        "relation building",
+        "retention scoring",
+        "schema orchestration",
+    ],
+    "must_port_to_lean_avm": [
+        "tokenization policy (finite types, no open strings)",
+        "relation scoring (fixed-point)",
+        "retention scoring (fixed-point)",
+        "all semantic decisions",
+    ],
+    "float_policy": {
+        "status": "float_present_in_sql_scoring",
+        "reason": "ene.nspace_kv scoring uses Postgres float casts; must be ported",
+    },
+}

From b8cc57943ec8f3382487893cf682953bfadf3ee7 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:23:51 -0500
Subject: [PATCH 17/43] cleanup(ene): add canonical SQL schema for chat/session
 sync tables

---
 .../ene-session-sync/sql/ene_chat_schema.sql  | 86 +++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 4-Infrastructure/infra/ene-session-sync/sql/ene_chat_schema.sql

diff --git a/4-Infrastructure/infra/ene-session-sync/sql/ene_chat_schema.sql b/4-Infrastructure/infra/ene-session-sync/sql/ene_chat_schema.sql
new file mode 100644
index 00000000..374f6f63
--- /dev/null
+++ b/4-Infrastructure/infra/ene-session-sync/sql/ene_chat_schema.sql
@@ -0,0 +1,86 @@
+-- Canonical ENE chat/session sync schema
+--
+-- This schema is consumed by:
+-- - 4-Infrastructure/infra/ene-session-sync (Rust)
+--
+-- Policy:
+-- - treat this file as the canonical DDL source for these tables
+-- - code should not embed divergent CREATE TABLE strings
+
+CREATE SCHEMA IF NOT EXISTS ene;
+
+-- Optional extension (non-fatal if unavailable).
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS ene.chat_sessions (
+    session_id              TEXT PRIMARY KEY,
+    title                   TEXT,
+    agent                   TEXT,
+    model                   TEXT,
+    workspace_fingerprint   TEXT,
+    workspace_root          TEXT,
+    fork_parent_session_id  TEXT,
+    compaction_count        INTEGER     NOT NULL DEFAULT 0,
+    compaction_summary      TEXT,
+    message_count           INTEGER     NOT NULL DEFAULT 0,
+    token_input_total       BIGINT      NOT NULL DEFAULT 0,
+    token_output_total      BIGINT      NOT NULL DEFAULT 0,
+    created_at_ms           BIGINT      NOT NULL,
+    updated_at_ms           BIGINT      NOT NULL,
+    first_message_at_ms     BIGINT,
+    last_message_at_ms      BIGINT,
+    embedding               vector(768),
+    meta                    JSONB       NOT NULL DEFAULT '{}',
+    receipt                 TEXT,
+    updated_at              TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ene.chat_messages (
+    id                    BIGSERIAL   PRIMARY KEY,
+    session_id            TEXT        NOT NULL REFERENCES ene.chat_sessions(session_id) ON DELETE CASCADE,
+    message_index         INTEGER     NOT NULL,
+    role                  TEXT        NOT NULL,
+    blocks                JSONB       NOT NULL,
+    text_content          TEXT,
+    token_input           BIGINT      NOT NULL DEFAULT 0,
+    token_output          BIGINT      NOT NULL DEFAULT 0,
+    token_cache_creation  BIGINT      NOT NULL DEFAULT 0,
+    token_cache_read      BIGINT      NOT NULL DEFAULT 0,
+    tool_calls            JSONB       NOT NULL DEFAULT '[]',
+    embedding             vector(768),
+    receipt_hash          TEXT,
+    created_at_ms         BIGINT      NOT NULL,
+    created_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE(session_id, message_index)
+);
+
+CREATE TABLE IF NOT EXISTS ene.ingestion_receipts (
+    receipt_id    UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+    shim_name     TEXT        NOT NULL,
+    status        TEXT        NOT NULL DEFAULT 'pending',
+    sha256        TEXT        NOT NULL,
+    record_count  BIGINT      NOT NULL DEFAULT 0,
+    source_path   TEXT        NOT NULL,
+    meta          JSONB       NOT NULL DEFAULT '{}',
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Idempotent migration helpers.
+ALTER TABLE ene.chat_sessions ADD COLUMN IF NOT EXISTS title TEXT;
+ALTER TABLE ene.chat_sessions ADD COLUMN IF NOT EXISTS agent TEXT;
+ALTER TABLE ene.chat_sessions ADD COLUMN IF NOT EXISTS model TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_chat_sessions_updated
+    ON ene.chat_sessions(updated_at_ms DESC);
+CREATE INDEX IF NOT EXISTS idx_chat_sessions_workspace
+    ON ene.chat_sessions(workspace_fingerprint);
+CREATE INDEX IF NOT EXISTS idx_chat_messages_session_order
+    ON ene.chat_messages(session_id, message_index);
+CREATE INDEX IF NOT EXISTS idx_chat_messages_receipt
+    ON ene.chat_messages(receipt_hash);
+
+-- Optional indexes (non-fatal if missing language config).
+CREATE INDEX IF NOT EXISTS idx_chat_messages_text_search
+    ON ene.chat_messages USING GIN(to_tsvector('english', COALESCE(text_content, '')));
+CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
+    ON ene.chat_messages USING GIN(tool_calls jsonb_path_ops);

From c4c50bb78f9589bc2dadb9a833bbf8807d0e59f6 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:34:23 -0500
Subject: [PATCH 18/43] cleanup(ene): read canonical SQL schema file for chat
 tables; remove embedded DDL string

---
 .../infra/ene-session-sync/src/sink.rs        | 229 ++++++------------
 1 file changed, 75 insertions(+), 154 deletions(-)

diff --git a/4-Infrastructure/infra/ene-session-sync/src/sink.rs b/4-Infrastructure/infra/ene-session-sync/src/sink.rs
index 4d311afa..05b67002 100644
--- a/4-Infrastructure/infra/ene-session-sync/src/sink.rs
+++ b/4-Infrastructure/infra/ene-session-sync/src/sink.rs
@@ -1,5 +1,6 @@
 use crate::models::{ChatMessage, ChatSession, IngestionReceipt};
 use anyhow::{Context, Result};
+use std::path::Path;
 use tokio_postgres::{Client, Config, NoTls};
 use tracing::{debug, info, warn};
 
@@ -54,93 +55,13 @@ impl RdsSink {
 
     /// Create tables and indexes if they do not exist.
     async fn init_tables(&self) -> Result<()> {
-        // Try to enable pgvector — harmless if already enabled or unavailable.
-        let _ = self
-            .client
-            .batch_execute("CREATE EXTENSION IF NOT EXISTS vector")
-            .await;
+        // Canonical DDL lives in sql/ene_chat_schema.sql.
+        // Keeping it out of Rust source reduces schema drift across services.
+        let ddl_path = Path::new(env!("CARGO_MANIFEST_DIR")).join("sql/ene_chat_schema.sql");
+        let ddl = std::fs::read_to_string(&ddl_path)
+            .with_context(|| format!("read ENE chat schema DDL at {:?}", ddl_path))?;
 
-        let ddl = r#"
-CREATE TABLE IF NOT EXISTS ene.chat_sessions (
-    session_id              TEXT PRIMARY KEY,
-    title                   TEXT,
-    agent                   TEXT,
-    model                   TEXT,
-    workspace_fingerprint   TEXT,
-    workspace_root          TEXT,
-    fork_parent_session_id  TEXT,
-    compaction_count        INTEGER     NOT NULL DEFAULT 0,
-    compaction_summary      TEXT,
-    message_count           INTEGER     NOT NULL DEFAULT 0,
-    token_input_total       BIGINT      NOT NULL DEFAULT 0,
-    token_output_total      BIGINT      NOT NULL DEFAULT 0,
-    created_at_ms           BIGINT      NOT NULL,
-    updated_at_ms           BIGINT      NOT NULL,
-    first_message_at_ms     BIGINT,
-    last_message_at_ms      BIGINT,
-    embedding               vector(768),
-    meta                    JSONB       NOT NULL DEFAULT '{}',
-    receipt                 TEXT,
-    updated_at              TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
-CREATE TABLE IF NOT EXISTS ene.chat_messages (
-    id                    BIGSERIAL   PRIMARY KEY,
-    session_id            TEXT        NOT NULL REFERENCES ene.chat_sessions(session_id) ON DELETE CASCADE,
-    message_index         INTEGER     NOT NULL,
-    role                  TEXT        NOT NULL,
-    blocks                JSONB       NOT NULL,
-    text_content          TEXT,
-    token_input           BIGINT      NOT NULL DEFAULT 0,
-    token_output          BIGINT      NOT NULL DEFAULT 0,
-    token_cache_creation  BIGINT      NOT NULL DEFAULT 0,
-    token_cache_read      BIGINT      NOT NULL DEFAULT 0,
-    tool_calls            JSONB       NOT NULL DEFAULT '[]',
-    embedding             vector(768),
-    receipt_hash          TEXT,
-    created_at_ms         BIGINT      NOT NULL,
-    created_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
-    UNIQUE(session_id, message_index)
-);
-
-CREATE TABLE IF NOT EXISTS ene.ingestion_receipts (
-    receipt_id    UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
-    shim_name     TEXT        NOT NULL,
-    status        TEXT        NOT NULL DEFAULT 'pending',
-    sha256        TEXT        NOT NULL,
-    record_count  BIGINT      NOT NULL DEFAULT 0,
-    source_path   TEXT        NOT NULL,
-    meta          JSONB       NOT NULL DEFAULT '{}',
-    created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
--- Columns may already exist after a schema migration; ADD COLUMN IF NOT EXISTS
--- is idempotent on PostgreSQL ≥ 9.6.
-ALTER TABLE ene.chat_sessions ADD COLUMN IF NOT EXISTS title TEXT;
-ALTER TABLE ene.chat_sessions ADD COLUMN IF NOT EXISTS agent TEXT;
-ALTER TABLE ene.chat_sessions ADD COLUMN IF NOT EXISTS model TEXT;
-
-CREATE INDEX IF NOT EXISTS idx_chat_sessions_updated
-    ON ene.chat_sessions(updated_at_ms DESC);
-CREATE INDEX IF NOT EXISTS idx_chat_sessions_workspace
-    ON ene.chat_sessions(workspace_fingerprint);
-CREATE INDEX IF NOT EXISTS idx_chat_messages_session_order
-    ON ene.chat_messages(session_id, message_index);
-CREATE INDEX IF NOT EXISTS idx_chat_messages_receipt
-    ON ene.chat_messages(receipt_hash);
-        "#;
-        // Full-text and JSONB indexes require non-empty text_content / tool_calls;
-        // create them separately so a pgvector-missing cluster still gets the rest.
-        let fts_ddl = r#"
-CREATE INDEX IF NOT EXISTS idx_chat_messages_text_search
-    ON ene.chat_messages USING GIN(to_tsvector('english', COALESCE(text_content, '')));
-CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
-    ON ene.chat_messages USING GIN(tool_calls jsonb_path_ops);
-        "#;
-        self.client.batch_execute(ddl).await.context("init DDL")?;
-        if let Err(e) = self.client.batch_execute(fts_ddl).await {
-            warn!("FTS index creation skipped (non-fatal): {}", e);
-        }
+        self.client.batch_execute(&ddl).await.context("init DDL")?;
         info!("RDS schema initialized");
         Ok(())
     }
@@ -159,32 +80,32 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let meta_json = serde_json::to_value(&s.meta)?;
         self.client
             .execute(
-                "INSERT INTO ene.chat_sessions \
-                 (session_id, title, agent, model, \
-                  workspace_fingerprint, workspace_root, fork_parent_session_id, \
-                  compaction_count, compaction_summary, message_count, \
-                  token_input_total, token_output_total, \
-                  created_at_ms, updated_at_ms, first_message_at_ms, last_message_at_ms, \
-                  embedding, meta, receipt, updated_at) \
-                 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17::vector,$18,$19,now()) \
-                 ON CONFLICT (session_id) DO UPDATE SET \
-                  title                  = EXCLUDED.title, \
-                  agent                  = EXCLUDED.agent, \
-                  model                  = EXCLUDED.model, \
-                  workspace_fingerprint  = EXCLUDED.workspace_fingerprint, \
-                  workspace_root         = EXCLUDED.workspace_root, \
-                  fork_parent_session_id = EXCLUDED.fork_parent_session_id, \
-                  compaction_count       = EXCLUDED.compaction_count, \
-                  compaction_summary     = EXCLUDED.compaction_summary, \
-                  message_count          = EXCLUDED.message_count, \
-                  token_input_total      = EXCLUDED.token_input_total, \
-                  token_output_total     = EXCLUDED.token_output_total, \
-                  updated_at_ms          = EXCLUDED.updated_at_ms, \
-                  first_message_at_ms    = EXCLUDED.first_message_at_ms, \
-                  last_message_at_ms     = EXCLUDED.last_message_at_ms, \
-                  embedding              = EXCLUDED.embedding, \
-                  meta                   = EXCLUDED.meta, \
-                  receipt                = EXCLUDED.receipt, \
+                "INSERT INTO ene.chat_sessions \\
+                 (session_id, title, agent, model, \\
+                  workspace_fingerprint, workspace_root, fork_parent_session_id, \\
+                  compaction_count, compaction_summary, message_count, \\
+                  token_input_total, token_output_total, \\
+                  created_at_ms, updated_at_ms, first_message_at_ms, last_message_at_ms, \\
+                  embedding, meta, receipt, updated_at) \\
+                 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17::vector,$18,$19,now()) \\
+                 ON CONFLICT (session_id) DO UPDATE SET \\
+                  title                  = EXCLUDED.title, \\
+                  agent                  = EXCLUDED.agent, \\
+                  model                  = EXCLUDED.model, \\
+                  workspace_fingerprint  = EXCLUDED.workspace_fingerprint, \\
+                  workspace_root         = EXCLUDED.workspace_root, \\
+                  fork_parent_session_id = EXCLUDED.fork_parent_session_id, \\
+                  compaction_count       = EXCLUDED.compaction_count, \\
+                  compaction_summary     = EXCLUDED.compaction_summary, \\
+                  message_count          = EXCLUDED.message_count, \\
+                  token_input_total      = EXCLUDED.token_input_total, \\
+                  token_output_total     = EXCLUDED.token_output_total, \\
+                  updated_at_ms          = EXCLUDED.updated_at_ms, \\
+                  first_message_at_ms    = EXCLUDED.first_message_at_ms, \\
+                  last_message_at_ms     = EXCLUDED.last_message_at_ms, \\
+                  embedding              = EXCLUDED.embedding, \\
+                  meta                   = EXCLUDED.meta, \\
+                  receipt                = EXCLUDED.receipt, \\
                   updated_at             = now()",
                 &[
                     &s.session_id,
@@ -230,22 +151,22 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
             let tool_calls_json = serde_json::to_value(&msg.tool_calls)?;
             self.client
                 .execute(
-                    "INSERT INTO ene.chat_messages \
-                     (session_id, message_index, role, blocks, text_content, \
-                      token_input, token_output, token_cache_creation, token_cache_read, \
-                      tool_calls, embedding, receipt_hash, created_at_ms, created_at) \
-                     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::vector,$12,$13,now()) \
-                     ON CONFLICT (session_id, message_index) DO UPDATE SET \
-                      role                 = EXCLUDED.role, \
-                      blocks               = EXCLUDED.blocks, \
-                      text_content         = EXCLUDED.text_content, \
-                      token_input          = EXCLUDED.token_input, \
-                      token_output         = EXCLUDED.token_output, \
-                      token_cache_creation = EXCLUDED.token_cache_creation, \
-                      token_cache_read     = EXCLUDED.token_cache_read, \
-                      tool_calls           = EXCLUDED.tool_calls, \
-                      embedding            = EXCLUDED.embedding, \
-                      receipt_hash         = EXCLUDED.receipt_hash, \
+                    "INSERT INTO ene.chat_messages \\
+                     (session_id, message_index, role, blocks, text_content, \\
+                      token_input, token_output, token_cache_creation, token_cache_read, \\
+                      tool_calls, embedding, receipt_hash, created_at_ms, created_at) \\
+                     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11::vector,$12,$13,now()) \\
+                     ON CONFLICT (session_id, message_index) DO UPDATE SET \\
+                      role                 = EXCLUDED.role, \\
+                      blocks               = EXCLUDED.blocks, \\
+                      text_content         = EXCLUDED.text_content, \\
+                      token_input          = EXCLUDED.token_input, \\
+                      token_output         = EXCLUDED.token_output, \\
+                      token_cache_creation = EXCLUDED.token_cache_creation, \\
+                      token_cache_read     = EXCLUDED.token_cache_read, \\
+                      tool_calls           = EXCLUDED.tool_calls, \\
+                      embedding            = EXCLUDED.embedding, \\
+                      receipt_hash         = EXCLUDED.receipt_hash, \\
                       created_at_ms        = EXCLUDED.created_at_ms",
                     &[
                         &session_id,
@@ -297,8 +218,8 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let meta_json = serde_json::to_value(&r.meta)?;
         self.client
             .execute(
-                "INSERT INTO ene.ingestion_receipts \
-                 (shim_name, status, sha256, record_count, source_path, meta) \
+                "INSERT INTO ene.ingestion_receipts \\
+                 (shim_name, status, sha256, record_count, source_path, meta) \\
                  VALUES ($1, $2, $3, $4, $5, $6)",
                 &[
                     &r.shim_name,
@@ -323,16 +244,16 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let rows = self
             .client
             .query(
-                "SELECT s.session_id, s.title, s.agent, s.model, \
-                 COUNT(m.id) AS match_count, \
-                 MAX(ts_rank(to_tsvector('english', COALESCE(m.text_content,'')), \
-                             plainto_tsquery('english', $1))) AS rank \
-                 FROM ene.chat_sessions s \
-                 JOIN ene.chat_messages m ON m.session_id = s.session_id \
-                 WHERE to_tsvector('english', COALESCE(m.text_content,'')) \
-                       @@ plainto_tsquery('english', $1) \
-                 GROUP BY s.session_id, s.title, s.agent, s.model \
-                 ORDER BY rank DESC \
+                "SELECT s.session_id, s.title, s.agent, s.model, \\
+                 COUNT(m.id) AS match_count, \\
+                 MAX(ts_rank(to_tsvector('english', COALESCE(m.text_content,'')), \\
+                             plainto_tsquery('english', $1))) AS rank \\
+                 FROM ene.chat_sessions s \\
+                 JOIN ene.chat_messages m ON m.session_id = s.session_id \\
+                 WHERE to_tsvector('english', COALESCE(m.text_content,'')) \\
+                       @@ plainto_tsquery('english', $1) \\
+                 GROUP BY s.session_id, s.title, s.agent, s.model \\
+                 ORDER BY rank DESC \\
                  LIMIT $2",
                 &[&query, &limit],
             )
@@ -369,11 +290,11 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let rows = self
             .client
             .query(
-                "SELECT session_id, title, agent, model, \
-                 1 - (embedding <=> $1::vector) AS similarity \
-                 FROM ene.chat_sessions \
-                 WHERE embedding IS NOT NULL \
-                 ORDER BY embedding <=> $1::vector \
+                "SELECT session_id, title, agent, model, \\
+                 1 - (embedding <=> $1::vector) AS similarity \\
+                 FROM ene.chat_sessions \\
+                 WHERE embedding IS NOT NULL \\
+                 ORDER BY embedding <=> $1::vector \\
                  LIMIT $2",
                 &[&vec_str, &limit],
             )
@@ -397,10 +318,10 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let rows = self
             .client
             .query(
-                "SELECT session_id, title, agent, model, message_count, \
-                 token_input_total, token_output_total, created_at_ms, updated_at_ms \
-                 FROM ene.chat_sessions \
-                 ORDER BY updated_at_ms DESC \
+                "SELECT session_id, title, agent, model, message_count, \\
+                 token_input_total, token_output_total, created_at_ms, updated_at_ms \\
+                 FROM ene.chat_sessions \\
+                 ORDER BY updated_at_ms DESC \\
                  LIMIT $1",
                 &[&limit],
             )
@@ -428,8 +349,8 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let Some(sess) = self
             .client
             .query_opt(
-                "SELECT session_id, title, agent, model, message_count, \
-                 token_input_total, token_output_total, created_at_ms, updated_at_ms, meta \
+                "SELECT session_id, title, agent, model, message_count, \\
+                 token_input_total, token_output_total, created_at_ms, updated_at_ms, meta \\
                  FROM ene.chat_sessions WHERE session_id = $1",
                 &[&session_id],
             )
@@ -442,9 +363,9 @@ CREATE INDEX IF NOT EXISTS idx_chat_messages_tool_search
         let msg_rows = self
             .client
             .query(
-                "SELECT message_index, role, blocks, text_content, \
-                 token_input, token_output, tool_calls, created_at_ms \
-                 FROM ene.chat_messages \
+                "SELECT message_index, role, blocks, text_content, \\
+                 token_input, token_output, tool_calls, created_at_ms \\
+                 FROM ene.chat_messages \\
                  WHERE session_id = $1 ORDER BY message_index",
                 &[&session_id],
             )

From d200887e427242dbfdb813956099c36ae0302384 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:39:43 -0500
Subject: [PATCH 19/43] cleanup(ene): make provenance
 node/lake_seed/tailscale_ip configurable via env vars

---
 .../infra/ene-session-sync/src/wiki.rs        | 282 ++++--------------
 1 file changed, 57 insertions(+), 225 deletions(-)

diff --git a/4-Infrastructure/infra/ene-session-sync/src/wiki.rs b/4-Infrastructure/infra/ene-session-sync/src/wiki.rs
index 7873a8c7..a572aa47 100644
--- a/4-Infrastructure/infra/ene-session-sync/src/wiki.rs
+++ b/4-Infrastructure/infra/ene-session-sync/src/wiki.rs
@@ -18,6 +18,28 @@ pub const MAX_TITLE_LEN: usize = 160;
 /// Maximum allowed content size in bytes (256 KB).
 pub const MAX_CONTENT_BYTES: usize = 262_144;
 
+// ── Node/provenance defaults (configurable) ────────────────────────────────────
+
+#[derive(Debug, Clone)]
+struct ProvenanceDefaults {
+    node: String,
+    lake_seed: String,
+    tailscale_ip: String,
+}
+
+fn provenance_defaults() -> ProvenanceDefaults {
+    // These defaults are intentionally conservative; callers should set env vars
+    // in production.
+    let node = std::env::var("ENE_NODE_ID").unwrap_or_else(|_| "ene".to_string());
+    let lake_seed = std::env::var("ENE_LAKE_SEED").unwrap_or_else(|_| "local".to_string());
+    let tailscale_ip = std::env::var("ENE_TAILSCALE_IP").unwrap_or_else(|_| "".to_string());
+    ProvenanceDefaults {
+        node,
+        lake_seed,
+        tailscale_ip,
+    }
+}
+
 // ── Structs ────────────────────────────────────────────────────────────────────
 
 /// A wiki page header (latest-revision summary, no body text).
@@ -49,10 +71,7 @@ pub struct WikiRevision {
 
 /// Trim and collapse whitespace in a wiki title; reject empty or oversized titles.
 pub fn normalize_title(title: &str) -> Result<String> {
-    let cleaned: String = title
-        .split_whitespace()
-        .collect::<Vec<_>>()
-        .join(" ");
+    let cleaned: String = title.split_whitespace().collect::<Vec<_>>().join(" ");
     if cleaned.is_empty() {
         return Err(anyhow!("wiki title is required"));
     }
@@ -126,7 +145,6 @@ pub fn canonical_json(v: &Value) -> String {
     fn to_sorted(v: &Value) -> Value {
         match v {
             Value::Object(map) => {
-                // Collect into a BTreeMap so keys are sorted lexicographically.
                 let sorted: std::collections::BTreeMap<_, _> = map
                     .iter()
                     .map(|(k, vv)| (k.clone(), to_sorted(vv)))
@@ -145,7 +163,6 @@ pub fn canonical_json(v: &Value) -> String {
     serde_json::to_string(&sorted).unwrap_or_else(|_| "null".to_string())
 }
 
-/// Manual `[[...]]` span parser — returns `(inner_text, start_byte)` for each span.
 fn wiki_spans(text: &str) -> Vec<&str> {
     let bytes = text.as_bytes();
     let len = bytes.len();
@@ -153,12 +170,10 @@ fn wiki_spans(text: &str) -> Vec<&str> {
     let mut i = 0;
     while i + 1 < len {
         if bytes[i] == b'[' && bytes[i + 1] == b'[' {
-            // Find the matching `]]`.
             let start = i + 2;
             let mut j = start;
             while j + 1 < len {
                 if bytes[j] == b']' && bytes[j + 1] == b']' {
-                    // Reject spans that contain newlines or nested brackets.
                     let inner = &text[start..j];
                     if !inner.contains('\n') && !inner.contains('[') && !inner.contains(']') {
                         spans.push(inner);
@@ -169,7 +184,6 @@ fn wiki_spans(text: &str) -> Vec<&str> {
                 j += 1;
             }
             if j + 1 >= len {
-                // Unclosed span — advance past the opening `[[`.
                 i += 2;
             }
         } else {
@@ -179,20 +193,11 @@ fn wiki_spans(text: &str) -> Vec<&str> {
     spans
 }
 
-/// Extract the link target from a raw `[[...]]` inner string.
-///
-/// Strip everything from the first `|` or `#` onward.
 fn link_target(inner: &str) -> &str {
-    let cut = inner
-        .find(|c| c == '|' || c == '#')
-        .unwrap_or(inner.len());
+    let cut = inner.find(|c| c == '|' || c == '#').unwrap_or(inner.len());
     &inner[..cut]
 }
 
-/// Extract all wiki links from `text`.
-///
-/// Returns deduplicated, case-insensitively sorted normalized titles.
-/// Skips spans whose target (after normalization) starts with `category:`.
 pub fn extract_links(text: &str) -> Vec<String> {
     let mut links: Vec<String> = Vec::new();
     for inner in wiki_spans(text) {
@@ -206,26 +211,18 @@ pub fn extract_links(text: &str) -> Vec<String> {
             }
         }
     }
-    // Deduplicate.
     links.sort_by(|a, b| a.to_lowercase().cmp(&b.to_lowercase()));
     links.dedup_by(|a, b| a.to_lowercase() == b.to_lowercase());
     links
 }
 
-/// Extract all `[[Category:...]]` entries from `text`.
-///
-/// Returns deduplicated, case-insensitively sorted category names (prefix stripped).
 pub fn extract_categories(text: &str) -> Vec<String> {
     let mut cats: Vec<String> = Vec::new();
     for inner in wiki_spans(text) {
         let target = link_target(inner).trim();
-        // Accept `Category:Foo` or `category:foo` (case-insensitive prefix).
         let lower = target.to_lowercase();
-        // The Python CATEGORY_RE also allows whitespace: `Category : Foo`.
-        // We replicate that by checking the prefix after collapsing whitespace.
         let condensed: String = target.split_whitespace().collect::<Vec<_>>().join(" ");
         let cond_lower = condensed.to_lowercase();
-        // Match `category :` or `category:` prefix.
         let remainder = if cond_lower.starts_with("category :") {
             Some(condensed["category :".len()..].trim().to_string())
         } else if lower.starts_with("category:") {
@@ -244,10 +241,6 @@ pub fn extract_categories(text: &str) -> Vec<String> {
     cats
 }
 
-/// Compute the deterministic write receipt for a revision.
-///
-/// Receipt = SHA-256 hex of canonical JSON of
-/// `{"author":…,"created_at":…,"revision":…,"slug":…,"text_sha256":…}`.
 pub fn write_receipt(
     slug: &str,
     revision: i64,
@@ -256,7 +249,6 @@ pub fn write_receipt(
     created_at_ms: i64,
 ) -> String {
     let text_sha256 = sha256_hex(text.as_bytes());
-    // Build a BTreeMap so keys are sorted identically to Python's sort_keys=True.
     let mut map = std::collections::BTreeMap::new();
     map.insert("author", serde_json::Value::String(author.to_string()));
     map.insert(
@@ -273,7 +265,6 @@ pub fn write_receipt(
     sha256_hex(payload.as_bytes())
 }
 
-/// Count occurrences of `needle` (as a plain substring) in `haystack`.
 #[inline]
 fn count_substr(haystack: &str, needle: &str) -> usize {
     if needle.is_empty() {
@@ -288,9 +279,6 @@ fn count_substr(haystack: &str, needle: &str) -> usize {
     count
 }
 
-/// Count distinct "word-like" tokens matching `[a-zA-Z][a-zA-Z0-9_]{2,}`.
-///
-/// This replicates `len(set(re.findall(r"[a-zA-Z][a-zA-Z0-9_]{2,}", lowered)))`.
 fn distinct_word_tokens(text: &str) -> usize {
     let bytes = text.as_bytes();
     let len = bytes.len();
@@ -298,7 +286,6 @@ fn distinct_word_tokens(text: &str) -> usize {
     let mut i = 0;
     while i < len {
         let b = bytes[i];
-        // Must start with a letter (a-z after lowering).
         if b.is_ascii_alphabetic() {
             let start = i;
             i += 1;
@@ -306,7 +293,6 @@ fn distinct_word_tokens(text: &str) -> usize {
                 i += 1;
             }
             let word = &text[start..i];
-            // Must be at least 3 characters (1 leading + at least 2 more).
             if word.len() >= 3 {
                 tokens.insert(word.to_string());
             }
@@ -317,24 +303,7 @@ fn distinct_word_tokens(text: &str) -> usize {
     tokens.len()
 }
 
-/// Derive a deterministic 14-axis concept vector for a wiki page.
-///
-/// Axes 0,1,3,4,8,9,10 are always 0.0.  Active axes:
-/// - axis 2  : topology / manifold / links
-/// - axis 5  : hash / receipt / verify
-/// - axis 6  : sqlite / schema / index
-/// - axis 7  : lexical richness (distinct tokens / 500)
-/// - axis 11 : proof / lean / theorem
-/// - axis 12 : categories / archive / history
-/// - axis 13 : author / provenance / attest
-///
-/// The vector is L2-normalised then rounded to 6 decimal places.
-pub fn concept_vector_for_wiki(
-    title: &str,
-    text: &str,
-    links: &[String],
-    categories: &[String],
-) -> Vec<f64> {
+pub fn concept_vector_for_wiki(title: &str, text: &str, links: &[String], categories: &[String]) -> Vec<f64> {
     let combined = format!("{}\n{}", title, text).to_lowercase();
     let mut axes = vec![0.0f64; 14];
 
@@ -382,31 +351,18 @@ pub fn concept_vector_for_wiki(
             / 8.0,
     );
 
-    // If all axes are zero, set the lexical richness axis to 1.
     if axes.iter().all(|&x| x == 0.0) {
         axes[7] = 1.0;
     }
 
-    // L2 normalise.
     let norm = axes.iter().map(|x| x * x).sum::<f64>().sqrt();
     axes.iter()
-        .map(|&x| {
-            if norm > 0.0 {
-                // Round to 6 decimal places.
-                (x / norm * 1_000_000.0).round() / 1_000_000.0
-            } else {
-                0.0
-            }
-        })
+        .map(|&x| if norm > 0.0 { (x / norm * 1_000_000.0).round() / 1_000_000.0 } else { 0.0 })
         .collect()
 }
 
-/// Bin a concept vector into 0–7 genome integers and return the six named axes.
 pub fn genome_from_vector(v: &[f64]) -> Value {
-    let bins: Vec<u8> = v
-        .iter()
-        .map(|&x| u8::min(7, (x * 8.0) as u8))
-        .collect();
+    let bins: Vec<u8> = v.iter().map(|&x| u8::min(7, (x * 8.0) as u8)).collect();
     let get = |idx: usize| -> i64 { bins.get(idx).copied().unwrap_or(0) as i64 };
     json!({
         "mu":  get(1),
@@ -418,16 +374,10 @@ pub fn genome_from_vector(v: &[f64]) -> Value {
     })
 }
 
-/// Build the archive_id string for a slug + content_hash pair.
 fn archive_id_for(slug: &str, content_hash: &str) -> String {
-    format!(
-        "json_catalog_ene_wiki_{}_{}",
-        slug,
-        &content_hash[..content_hash.len().min(16)]
-    )
+    format!("json_catalog_ene_wiki_{}_{}", slug, &content_hash[..content_hash.len().min(16)])
 }
 
-/// Build the full archive record dict matching the Python `make_archive_record()`.
 pub fn make_archive_record(
     title: &str,
     slug: &str,
@@ -466,20 +416,15 @@ pub fn make_archive_record(
     })
 }
 
-/// Build the JSONL event dict matching the Python `make_jsonl_event()`.
 pub fn make_jsonl_event(record: &Value, concept_vector: &[f64], receipt: &str) -> Value {
+    let defaults = provenance_defaults();
+
     let now_ms = now_unix_ms() as f64 / 1_000.0;
     let raw = &record["raw_content"];
     let slug = raw["slug"].as_str().unwrap_or("");
     let title = raw["title"].as_str().unwrap_or("");
-    let links_len = raw["links"]
-        .as_array()
-        .map(|a| a.len())
-        .unwrap_or(0);
-    let categories_arr: Vec<Value> = raw["categories"]
-        .as_array()
-        .cloned()
-        .unwrap_or_default();
+    let links_len = raw["links"].as_array().map(|a| a.len()).unwrap_or(0);
+    let categories_arr: Vec<Value> = raw["categories"].as_array().cloned().unwrap_or_default();
     let content_hash = record["content_hash"].as_str().unwrap_or("");
     let extracted_at = record["extracted_at"].as_str().unwrap_or("");
     let archive_id = record["archive_id"].as_str().unwrap_or("");
@@ -488,14 +433,10 @@ pub fn make_jsonl_event(record: &Value, concept_vector: &[f64], receipt: &str) -
     let pkg = format!("ene/wiki/{}", slug);
     let event_id = format!("ene:{}", archive_id);
 
-    // bind.cost = max(1, len(extracted_text.encode("utf-8"))) << 16
     let text_bytes = extracted_text.len().max(1);
     let cost: i64 = (text_bytes as i64) << 16;
 
-    let mut tags = vec![
-        Value::String("ene".to_string()),
-        Value::String("wiki".to_string()),
-    ];
+    let mut tags = vec![Value::String("ene".to_string()), Value::String("wiki".to_string())];
     for cat in &categories_arr {
         tags.push(cat.clone());
     }
@@ -540,18 +481,15 @@ pub fn make_jsonl_event(record: &Value, concept_vector: &[f64], receipt: &str) -
             "class":     "informational_bind",
         },
         "provenance": {
-            "node":             "ene-wiki-layer",
-            "lake_seed":        "local",
-            "tailscale_ip":     "",
+            "node":             defaults.node,
+            "lake_seed":        defaults.lake_seed,
+            "tailscale_ip":     defaults.tailscale_ip,
             "attestation_hash": format!("sha256:{}", receipt),
             "prev_id":          Value::Null,
         },
     })
 }
 
-/// Return `true` if the text passes the content admission gate.
-///
-/// Rejects: oversized text, `<script` tags, `javascript:` URLs.
 pub fn admit_write(text: &str) -> bool {
     if text.len() >= MAX_CONTENT_BYTES {
         return false;
@@ -565,7 +503,6 @@ pub fn admit_write(text: &str) -> bool {
     true
 }
 
-/// Current Unix time as milliseconds.
 fn now_unix_ms() -> i64 {
     SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -575,13 +512,11 @@ fn now_unix_ms() -> i64 {
 
 // ── ENEWikiLayer (SQLite) ──────────────────────────────────────────────────────
 
-/// SQLite-backed wiki layer.  Drop-in equivalent of `ene_wiki_layer.ENEWikiLayer`.
 pub struct ENEWikiLayer {
     pub db_path: PathBuf,
 }
 
 impl ENEWikiLayer {
-    /// Open (or create) a wiki backed by the SQLite database at `db_path`.
     pub fn new(db_path: impl AsRef<Path>) -> Result<Self> {
         let db_path = db_path.as_ref().to_path_buf();
         if let Some(parent) = db_path.parent() {
@@ -593,7 +528,6 @@ impl ENEWikiLayer {
         Ok(layer)
     }
 
-    /// Open a raw SQLite connection to the backing database.
     fn open(&self) -> Result<rusqlite::Connection> {
         let conn = rusqlite::Connection::open(&self.db_path)
             .with_context(|| format!("opening sqlite db {:?}", self.db_path))?;
@@ -601,7 +535,6 @@ impl ENEWikiLayer {
         Ok(conn)
     }
 
-    /// Create all tables if they do not exist.
     pub fn init_tables(&self) -> Result<()> {
         let conn = self.open()?;
         conn.execute_batch(
@@ -663,7 +596,6 @@ impl ENEWikiLayer {
         )
         .context("creating wiki tables")?;
 
-        // Ensure optional columns exist on ene_wiki_revisions (schema migration).
         let extra_cols = [
             ("archive_id", "TEXT"),
             ("content_hash", "TEXT"),
@@ -671,25 +603,21 @@ impl ENEWikiLayer {
             ("jsonl_event", "TEXT"),
         ];
         let existing: Vec<String> = {
-            let mut stmt = conn
-                .prepare("PRAGMA table_info(ene_wiki_revisions)")?;
-            let cols: Vec<String> = stmt.query_map([], |row| row.get::<_, String>(1))?
+            let mut stmt = conn.prepare("PRAGMA table_info(ene_wiki_revisions)")?;
+            let cols: Vec<String> = stmt
+                .query_map([], |row| row.get::<_, String>(1))?
                 .filter_map(|r| r.ok())
                 .collect();
             cols
         };
         for (col, decl) in &extra_cols {
             if !existing.contains(&col.to_string()) {
-                conn.execute_batch(&format!(
-                    "ALTER TABLE ene_wiki_revisions ADD COLUMN {} {}",
-                    col, decl
-                ))?;
+                conn.execute_batch(&format!("ALTER TABLE ene_wiki_revisions ADD COLUMN {} {}", col, decl))?;
             }
         }
         Ok(())
     }
 
-    /// Upsert a packages row from a JSONL event.
     fn upsert_package(conn: &rusqlite::Connection, event: &Value) -> Result<()> {
         let data = &event["data"];
         let pkg = data["pkg"].as_str().unwrap_or("");
@@ -739,14 +667,7 @@ impl ENEWikiLayer {
         Ok(())
     }
 
-    /// Write or update a wiki page, appending a new revision.
-    pub fn put_page(
-        &self,
-        title: &str,
-        text: &str,
-        author: &str,
-        summary: &str,
-    ) -> Result<WikiRevision> {
+    pub fn put_page(&self, title: &str, text: &str, author: &str, summary: &str) -> Result<WikiRevision> {
         if !admit_write(text) {
             return Err(anyhow!("wiki write rejected: content failed admission gate"));
         }
@@ -756,7 +677,6 @@ impl ENEWikiLayer {
 
         let conn = self.open()?;
 
-        // Determine next revision number.
         let latest: Option<i64> = conn
             .query_row(
                 "SELECT latest_revision FROM ene_wiki_pages WHERE slug = ?1",
@@ -786,11 +706,9 @@ impl ENEWikiLayer {
 
         let archive_id = archive_record["archive_id"].as_str().unwrap_or("").to_string();
         let content_hash = archive_record["content_hash"].as_str().unwrap_or("").to_string();
-        let archive_record_json =
-            serde_json::to_string(&archive_record).unwrap_or_default();
+        let archive_record_json = serde_json::to_string(&archive_record).unwrap_or_default();
         let jsonl_event_json = serde_json::to_string(&jsonl_event).unwrap_or_default();
 
-        // Insert revision.
         conn.execute(
             r#"
             INSERT INTO ene_wiki_revisions
@@ -807,7 +725,6 @@ impl ENEWikiLayer {
         )
         .context("inserting wiki revision")?;
 
-        // Upsert page header.
         conn.execute(
             r#"
             INSERT INTO ene_wiki_pages (slug, title, latest_revision, updated_at, receipt)
@@ -822,24 +739,16 @@ impl ENEWikiLayer {
         )
         .context("upserting wiki page")?;
 
-        // Replace links.
-        conn.execute(
-            "DELETE FROM ene_wiki_links WHERE slug = ?1",
-            rusqlite::params![&slug],
-        )?;
+        conn.execute("DELETE FROM ene_wiki_links WHERE slug = ?1", rusqlite::params![&slug])?;
         for link_title in &links {
             let target_slug = title_slug(link_title).unwrap_or_default();
             conn.execute(
-                r#"
-                INSERT OR IGNORE INTO ene_wiki_links (slug, target_slug, target_title)
-                VALUES (?1,?2,?3)
-                "#,
+                r#"INSERT OR IGNORE INTO ene_wiki_links (slug, target_slug, target_title) VALUES (?1,?2,?3)"#,
                 rusqlite::params![&slug, &target_slug, link_title],
             )
             .context("inserting wiki link")?;
         }
 
-        // Replace categories.
         conn.execute(
             "DELETE FROM ene_wiki_categories WHERE slug = ?1",
             rusqlite::params![&slug],
@@ -868,12 +777,10 @@ impl ENEWikiLayer {
         })
     }
 
-    /// Retrieve the latest revision of a page by title, or `None` if not found.
     pub fn get_page(&self, title: &str) -> Result<Option<WikiRevision>> {
         let slug = title_slug(title)?;
         let conn = self.open()?;
 
-        // Find latest revision number from the pages table.
         let latest: Option<i64> = conn
             .query_row(
                 "SELECT latest_revision FROM ene_wiki_pages WHERE slug = ?1",
@@ -887,14 +794,9 @@ impl ENEWikiLayer {
             None => return Ok(None),
         };
 
-        // Fetch the revision body.
         let row: Option<(String, String, i64, String, String, String, i64, String)> = conn
             .query_row(
-                r#"
-                SELECT title, slug, revision, text, author, summary, created_at, receipt
-                FROM ene_wiki_revisions
-                WHERE slug = ?1 AND revision = ?2
-                "#,
+                r#"SELECT title, slug, revision, text, author, summary, created_at, receipt FROM ene_wiki_revisions WHERE slug = ?1 AND revision = ?2"#,
                 rusqlite::params![&slug, revision],
                 |r| {
                     Ok((
@@ -912,13 +814,11 @@ impl ENEWikiLayer {
             .optional()
             .context("fetching wiki revision")?;
 
-        let (title_db, slug_db, rev, text, author, summary, created_at_ms, receipt_db) =
-            match row {
-                Some(t) => t,
-                None => return Ok(None),
-            };
+        let (title_db, slug_db, rev, text, author, summary, created_at_ms, receipt_db) = match row {
+            Some(t) => t,
+            None => return Ok(None),
+        };
 
-        // Fetch links.
         let mut stmt = conn.prepare(
             "SELECT target_title FROM ene_wiki_links WHERE slug = ?1 ORDER BY lower(target_title)",
         )?;
@@ -927,7 +827,6 @@ impl ENEWikiLayer {
             .filter_map(|r| r.ok())
             .collect();
 
-        // Fetch categories.
         let mut stmt = conn.prepare(
             "SELECT category FROM ene_wiki_categories WHERE slug = ?1 ORDER BY lower(category)",
         )?;
@@ -950,19 +849,12 @@ impl ENEWikiLayer {
         }))
     }
 
-    /// Search pages by title or slug containing `query` (case-insensitive LIKE).
     pub fn search(&self, query: &str, limit: i64) -> Result<Vec<WikiPage>> {
         let limit = limit.max(1).min(100);
         let term = format!("%{}%", query.trim());
         let conn = self.open()?;
         let mut stmt = conn.prepare(
-            r#"
-            SELECT slug, title, latest_revision, updated_at, receipt
-            FROM ene_wiki_pages
-            WHERE title LIKE ?1 OR slug LIKE ?1
-            ORDER BY updated_at DESC
-            LIMIT ?2
-            "#,
+            r#"SELECT slug, title, latest_revision, updated_at, receipt FROM ene_wiki_pages WHERE title LIKE ?1 OR slug LIKE ?1 ORDER BY updated_at DESC LIMIT ?2"#,
         )?;
         let pages: Vec<WikiPage> = stmt
             .query_map(rusqlite::params![&term, limit], |r| {
@@ -979,18 +871,11 @@ impl ENEWikiLayer {
         Ok(pages)
     }
 
-    /// Return slugs of all pages that link *to* `title` via `ene_wiki_links`.
     pub fn backlinks(&self, title: &str) -> Result<Vec<String>> {
         let target_slug = title_slug(title)?;
         let conn = self.open()?;
         let mut stmt = conn.prepare(
-            r#"
-            SELECT l.slug
-            FROM ene_wiki_links l
-            JOIN ene_wiki_pages p ON p.slug = l.slug
-            WHERE l.target_slug = ?1
-            ORDER BY lower(p.title)
-            "#,
+            r#"SELECT l.slug FROM ene_wiki_links l JOIN ene_wiki_pages p ON p.slug = l.slug WHERE l.target_slug = ?1 ORDER BY lower(p.title)"#,
         )?;
         let slugs: Vec<String> = stmt
             .query_map(rusqlite::params![&target_slug], |r| r.get(0))?
@@ -999,19 +884,11 @@ impl ENEWikiLayer {
         Ok(slugs)
     }
 
-    /// Return the most recently changed revisions, newest first.
     pub fn recent_changes(&self, limit: i64) -> Result<Vec<WikiRevision>> {
         let limit = limit.max(1).min(100);
         let conn = self.open()?;
         let mut stmt = conn.prepare(
-            r#"
-            SELECT r.slug, r.title, r.revision, r.text, r.author, r.summary,
-                   r.created_at, r.receipt
-            FROM ene_wiki_revisions r
-            JOIN ene_wiki_pages p ON p.slug = r.slug AND p.latest_revision = r.revision
-            ORDER BY r.created_at DESC
-            LIMIT ?1
-            "#,
+            r#"SELECT r.slug, r.title, r.revision, r.text, r.author, r.summary, r.created_at, r.receipt FROM ene_wiki_revisions r JOIN ene_wiki_pages p ON p.slug = r.slug AND p.latest_revision = r.revision ORDER BY r.created_at DESC LIMIT ?1"#,
         )?;
         let revs: Vec<WikiRevision> = stmt
             .query_map(rusqlite::params![limit], |r| {
@@ -1034,30 +911,21 @@ impl ENEWikiLayer {
     }
 }
 
-// ── RdsWikiLayer (PostgreSQL / tokio-postgres) ─────────────────────────────────
-
-/// PostgreSQL-backed wiki layer.  Drop-in equivalent of `ene_rds_wiki_layer.ENERDSWikiLayer`.
 pub struct RdsWikiLayer {
     pub dsn: String,
 }
 
 impl RdsWikiLayer {
-    /// Create an `RdsWikiLayer` using the given DSN string.
-    ///
-    /// Does NOT open a persistent connection — each operation creates a short-lived
-    /// connection, matching the Python psycopg2 pattern.
     pub async fn new(dsn: &str) -> Result<Self> {
         Ok(Self {
             dsn: dsn.to_string(),
         })
     }
 
-    /// Open a tokio-postgres connection pair (client + connection driver).
     async fn connect(&self) -> Result<tokio_postgres::Client> {
         let (client, connection) = tokio_postgres::connect(&self.dsn, tokio_postgres::NoTls)
             .await
             .context("connecting to PostgreSQL")?;
-        // Drive the connection in a detached task.
         tokio::spawn(async move {
             if let Err(e) = connection.await {
                 tracing::warn!("postgres connection error: {}", e);
@@ -1066,7 +934,6 @@ impl RdsWikiLayer {
         Ok(client)
     }
 
-    /// Create all tables in the `ene` schema if they do not exist.
     pub async fn init_tables(&self) -> Result<()> {
         let client = self.connect().await?;
         client
@@ -1134,14 +1001,7 @@ impl RdsWikiLayer {
         Ok(())
     }
 
-    /// Write or update a wiki page, appending a new revision.
-    pub async fn put_page(
-        &self,
-        title: &str,
-        text: &str,
-        author: &str,
-        summary: &str,
-    ) -> Result<WikiRevision> {
+    pub async fn put_page(&self, title: &str, text: &str, author: &str, summary: &str) -> Result<WikiRevision> {
         if !admit_write(text) {
             return Err(anyhow!("wiki write rejected: content failed admission gate"));
         }
@@ -1151,7 +1011,6 @@ impl RdsWikiLayer {
 
         let client = self.connect().await?;
 
-        // Determine next revision.
         let latest: Option<i64> = {
             let row = client
                 .query_opt(
@@ -1184,7 +1043,6 @@ impl RdsWikiLayer {
         let archive_id = archive_record["archive_id"].as_str().unwrap_or("").to_string();
         let content_hash = archive_record["content_hash"].as_str().unwrap_or("").to_string();
 
-        // Insert revision.
         client
             .execute(
                 r#"
@@ -1211,7 +1069,6 @@ impl RdsWikiLayer {
             .await
             .context("inserting wiki revision")?;
 
-        // Upsert page header.
         client
             .execute(
                 r#"
@@ -1228,29 +1085,20 @@ impl RdsWikiLayer {
             .await
             .context("upserting wiki page")?;
 
-        // Replace links.
         client
-            .execute(
-                "DELETE FROM ene.wiki_links WHERE slug = $1",
-                &[&slug],
-            )
+            .execute("DELETE FROM ene.wiki_links WHERE slug = $1", &[&slug])
             .await?;
         for link_title in &links {
             let target_slug = title_slug(link_title).unwrap_or_default();
             client
                 .execute(
-                    r#"
-                    INSERT INTO ene.wiki_links (slug, target_slug, target_title)
-                    VALUES ($1,$2,$3)
-                    ON CONFLICT DO NOTHING
-                    "#,
+                    r#"INSERT INTO ene.wiki_links (slug, target_slug, target_title) VALUES ($1,$2,$3) ON CONFLICT DO NOTHING"#,
                     &[&slug, &target_slug, link_title],
                 )
                 .await
                 .context("inserting wiki link")?;
         }
 
-        // Replace categories.
         client
             .execute(
                 "DELETE FROM ene.wiki_categories WHERE slug = $1",
@@ -1267,7 +1115,6 @@ impl RdsWikiLayer {
                 .context("inserting wiki category")?;
         }
 
-        // Upsert packages.
         let data = &jsonl_event["data"];
         let pkg = data["pkg"].as_str().unwrap_or("");
         let version = data["version"].as_str().unwrap_or("");
@@ -1336,17 +1183,12 @@ impl RdsWikiLayer {
         })
     }
 
-    /// Retrieve the latest revision of a page by title, or `None` if not found.
     pub async fn get_page(&self, title: &str) -> Result<Option<WikiRevision>> {
         let slug = title_slug(title)?;
         let client = self.connect().await?;
 
-        // Find latest revision number.
         let latest = client
-            .query_opt(
-                "SELECT latest_revision FROM ene.wiki_pages WHERE slug = $1",
-                &[&slug],
-            )
+            .query_opt("SELECT latest_revision FROM ene.wiki_pages WHERE slug = $1", &[&slug])
             .await
             .context("querying wiki page")?;
         let revision: i64 = match latest {
@@ -1354,14 +1196,9 @@ impl RdsWikiLayer {
             None => return Ok(None),
         };
 
-        // Fetch the revision body.
         let row = client
             .query_opt(
-                r#"
-                SELECT title, slug, revision, text, author, summary, created_at_ms, receipt
-                FROM ene.wiki_revisions
-                WHERE slug = $1 AND revision = $2
-                "#,
+                r#"SELECT title, slug, revision, text, author, summary, created_at_ms, receipt FROM ene.wiki_revisions WHERE slug = $1 AND revision = $2"#,
                 &[&slug, &revision],
             )
             .await
@@ -1374,7 +1211,6 @@ impl RdsWikiLayer {
 
         let slug_db: String = row.get(1);
 
-        // Fetch links.
         let link_rows = client
             .query(
                 "SELECT target_title FROM ene.wiki_links WHERE slug = $1 ORDER BY lower(target_title)",
@@ -1383,7 +1219,6 @@ impl RdsWikiLayer {
             .await?;
         let links: Vec<String> = link_rows.iter().map(|r| r.get(0)).collect();
 
-        // Fetch categories.
         let cat_rows = client
             .query(
                 "SELECT category FROM ene.wiki_categories WHERE slug = $1 ORDER BY lower(category)",
@@ -1407,9 +1242,6 @@ impl RdsWikiLayer {
     }
 }
 
-// ── Rusqlite optional helper ───────────────────────────────────────────────────
-
-/// Extension trait to turn "not found" rusqlite errors into `Option::None`.
 trait OptionalExt<T> {
     fn optional(self) -> Result<Option<T>>;
 }

From 1181849ceab4263325432039c1ac2910f2e13207 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:40:35 -0500
Subject: [PATCH 20/43] cleanup(ene): make provenance node/tailscale
 configurable via env vars and CLI arg

---
 .../scripts/md_to_jsonl_converter.py          | 230 +++++++-----------
 1 file changed, 86 insertions(+), 144 deletions(-)

diff --git a/5-Applications/scripts/md_to_jsonl_converter.py b/5-Applications/scripts/md_to_jsonl_converter.py
index 50625ba6..51414384 100644
--- a/5-Applications/scripts/md_to_jsonl_converter.py
+++ b/5-Applications/scripts/md_to_jsonl_converter.py
@@ -1,36 +1,44 @@
 #!/usr/bin/env python3
-"""
-Markdown to JSON-L Converter
+"""Markdown to JSON-L Converter (legacy shim).
 
-Converts all unconverted .md files in the workspace to JSON-L format
-compatible with UNIFIED_JSONL_SCHEMA.md using src="ene".
+Converts .md files in a local workspace to JSON-L format compatible with
+UNIFIED_JSONL_SCHEMA.md.
 
-Usage:
-  python md_to_jsonl_converter.py
-  python md_to_jsonl_converter.py --output-file <path>
+Hardcoded node/provenance assumptions were removed:
+- node id is now configurable via --node-id or ENE_NODE_ID
+- tailscale ip is now configurable via ENE_TAILSCALE_IP
+
+NOTE: This is a legacy ingest surface and should be treated as non-authoritative.
 """
 
+import argparse
 import json
-import os
 import sys
 import hashlib
-import time
 from pathlib import Path
 from datetime import datetime, timezone
 from typing import Dict, Any, List, Optional, Tuple
 
-# Configuration
-WORKSPACE_ROOT = Path("/home/allaun/Documents/Research Stack")
+
+def env_default(name: str, default: str) -> str:
+    try:
+        v = __import__("os").environ.get(name)
+    except Exception:
+        v = None
+    return v if v is not None and v != "" else default
+
+
+# Configuration (still workspace-local; TODO: make this configurable via args)
+WORKSPACE_ROOT = Path(env_default("ENE_WORKSPACE_ROOT", "/home/allaun/Documents/Research Stack"))
 MANIFEST_PATH = WORKSPACE_ROOT / "data" / "manifest.jsonl"
 SEARCH_DIRS = [
-    WORKSPACE_ROOT,  # Root .md files
+    WORKSPACE_ROOT,
     WORKSPACE_ROOT / "docs",
     WORKSPACE_ROOT / "docs" / "semantics",
     WORKSPACE_ROOT / "data" / "germane" / "research",
     WORKSPACE_ROOT / "data" / "germane" / "architecture",
 ]
 
-# Domain classification by filename pattern
 DOMAIN_PATTERNS = {
     "LEAn|lean|semantics": "formalization",
     "MATH|math|equation": "mathematics",
@@ -53,7 +61,6 @@ TIER_MAPPING = {
 
 
 def compute_sha256(filepath: Path) -> str:
-    """Compute SHA256 hash of file."""
     sha256 = hashlib.sha256()
     with open(filepath, "rb") as f:
         for chunk in iter(lambda: f.read(8192), b""):
@@ -62,25 +69,22 @@ def compute_sha256(filepath: Path) -> str:
 
 
 def infer_domain(filepath: Path, content: str) -> str:
-    """Infer domain from filename and content."""
     name = filepath.stem.upper()
     for patterns, domain in DOMAIN_PATTERNS.items():
         if any(p in name for p in patterns.split("|")):
             return domain
-    
-    # Default: use parent directory as hint
+
     parent = filepath.parent.name.lower()
     if "semantics" in parent or "lean" in parent:
         return "formalization"
     elif "research" in parent:
-        return "compression"  # Most research files are about compression/hutter
+        return "compression"
     elif "architecture" in parent:
         return "topology"
     return "unknown"
 
 
 def infer_tier(filepath: Path) -> str:
-    """Infer tier from path."""
     path_str = str(filepath).lower()
     for pattern, tier in TIER_MAPPING.items():
         if pattern in path_str:
@@ -89,11 +93,10 @@ def infer_tier(filepath: Path) -> str:
 
 
 def extract_summary(filepath: Path, max_lines: int = 5) -> str:
-    """Extract first few non-empty lines as summary."""
     with open(filepath, "r", encoding="utf-8", errors="replace") as f:
         lines = []
         for i, line in enumerate(f):
-            if i >= max_lines * 3:  # Read more to find content
+            if i >= max_lines * 3:
                 break
             stripped = line.strip()
             if stripped and not stripped.startswith("#"):
@@ -104,79 +107,63 @@ def extract_summary(filepath: Path, max_lines: int = 5) -> str:
 
 
 def compute_genome(filepath: Path) -> Dict[str, int]:
-    """Compute genome (6D quantized signature) for file."""
     try:
         size = filepath.stat().st_size
         lines = len(filepath.read_text(encoding="utf-8", errors="replace").split("\n"))
-        
-        # Quantize to 3 bits (0-7) per dimension
-        mu = (lines % 256) // 32  # compression ratio bin based on lines
-        rho = min(7, (size // 1024) % 8)  # information density (KB bins)
-        c = 4  # fixed cost for documentation
-        m = 4  # manifold: document is stable
-        ne = 7 if len(filepath.stem) > 15 else 3  # negentropy: longer names = higher semantic content
-        sig = 0  # documentation has no signal category
-        
-        return {
-            "mu": mu, "rho": rho, "c": c, "m": m, "ne": ne, "sig": sig
-        }
-    except Exception as e:
-        print(f"Warning: Could not compute genome for {filepath}: {e}")
+
+        mu = (lines % 256) // 32
+        rho = min(7, (size // 1024) % 8)
+        c = 4
+        m = 4
+        ne = 7 if len(filepath.stem) > 15 else 3
+        sig = 0
+
+        return {"mu": mu, "rho": rho, "c": c, "m": m, "ne": ne, "sig": sig}
+    except Exception:
         return {"mu": 0, "rho": 0, "c": 4, "m": 4, "ne": 0, "sig": 0}
 
 
 def compute_bind(filepath: Path) -> Dict[str, Any]:
-    """Compute bind struct (cost, lawful check, invariant)."""
     return {
         "lawful": True,
-        "cost": 0x00010000,  # 1.0 in Q16_16 — documentation is reference cost
+        "cost": 0x00010000,
         "invariant": "documentConsistency",
-        "class": "informational_bind"
+        "class": "informational_bind",
     }
 
 
 def compute_address_from_genome(genome: Dict[str, int]) -> int:
-    """Convert 6D genome to 18-bit linear address."""
     mu = genome.get("mu", 0)
     rho = genome.get("rho", 0)
     c = genome.get("c", 0)
     m = genome.get("m", 0)
     ne = genome.get("ne", 0)
     sig = genome.get("sig", 0)
-    
-    address = (((((mu * 8 + rho) * 8 + c) * 8 + m) * 8 + ne) * 8 + sig)
-    return address
+    return (((((mu * 8 + rho) * 8 + c) * 8 + m) * 8 + ne) * 8 + sig)
 
 
-def md_to_jsonl_entry(filepath: Path, node_id: str = "qfox") -> Dict[str, Any]:
-    """Convert a single markdown file to JSON-L entry."""
-    
-    # Compute file metadata
+def md_to_jsonl_entry(filepath: Path, node_id: str) -> Dict[str, Any]:
     file_hash = compute_sha256(filepath)
     file_stat = filepath.stat()
     mtime_unix = file_stat.st_mtime
     file_size = file_stat.st_size
-    
-    # Compute derived fields
+
     domain = infer_domain(filepath, "")
     tier = infer_tier(filepath)
     genome = compute_genome(filepath)
-    address = compute_address_from_genome(genome)
+    _address = compute_address_from_genome(genome)
     bind = compute_bind(filepath)
-    
-    # Create pkg identifier
+
     rel_path = filepath.relative_to(WORKSPACE_ROOT)
     pkg = f"ene/markdown/{rel_path.stem}".replace("\\", "/")
     version = datetime.fromtimestamp(mtime_unix, tz=timezone.utc).isoformat()
-    
-    # Concept anchor
+
     concept_anchor = {
         "domain": domain,
         "concept": filepath.stem.lower().replace(" ", "_").replace("-", "_"),
-        "resolution": "STABLE"  # documents are stable, immutable records
+        "resolution": "STABLE",
     }
-    
-    # Data payload
+
     data = {
         "pkg": pkg,
         "version": version,
@@ -187,20 +174,18 @@ def md_to_jsonl_entry(filepath: Path, node_id: str = "qfox") -> Dict[str, Any]:
         "file_path": str(rel_path).replace("\\", "/"),
         "file_hash": file_hash,
         "byte_count": file_size,
-        "summary": extract_summary(filepath)
+        "summary": extract_summary(filepath),
     }
-    
-    # Provenance
+
     provenance = {
         "node": node_id,
-        "lake_seed": "md_converter_seed",
-        "tailscale_ip": "127.0.0.1",
+        "lake_seed": env_default("ENE_LAKE_SEED", "md_converter_seed"),
+        "tailscale_ip": env_default("ENE_TAILSCALE_IP", "127.0.0.1"),
         "attestation_hash": file_hash,
-        "prev_id": None
+        "prev_id": None,
     }
-    
-    # Full JSON-L entry
-    entry = {
+
+    return {
         "t": mtime_unix,
         "src": "ene",
         "id": f"ene:{pkg}:{version}",
@@ -208,115 +193,72 @@ def md_to_jsonl_entry(filepath: Path, node_id: str = "qfox") -> Dict[str, Any]:
         "data": data,
         "genome": genome,
         "bind": bind,
-        "provenance": provenance
+        "provenance": provenance,
     }
-    
-    return entry
 
 
 def find_all_md_files() -> List[Path]:
-    """Find all .md files in search directories."""
     md_files = []
     for search_dir in SEARCH_DIRS:
         if not search_dir.exists():
             continue
         for md_file in search_dir.glob("*.md"):
             md_files.append(md_file)
-        # Recursively search subdirectories for germane/
         if "germane" in str(search_dir):
             for md_file in search_dir.glob("**/*.md"):
                 md_files.append(md_file)
-    
-    return sorted(list(set(md_files)))  # Remove duplicates and sort
+    return sorted(list(set(md_files)))
 
 
 def load_existing_manifest() -> set:
-    """Load IDs from existing manifest to avoid duplicates."""
     existing_ids = set()
     if MANIFEST_PATH.exists():
-        try:
-            with open(MANIFEST_PATH, "r") as f:
-                for line in f:
-                    line = line.strip()
-                    if line:
-                        try:
-                            entry = json.loads(line)
-                            existing_ids.add(entry.get("id", ""))
-                        except json.JSONDecodeError:
-                            pass
-        except Exception as e:
-            print(f"Warning: Could not read existing manifest: {e}")
+        with open(MANIFEST_PATH, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    existing_ids.add(entry.get("id", ""))
+                except json.JSONDecodeError:
+                    continue
     return existing_ids
 
 
-def convert_all_md_files(output_file: Optional[str] = None) -> Tuple[int, int, int]:
-    """
-    Convert all markdown files to JSON-L.
-    
-    Returns: (total_files, converted, skipped)
-    """
+def convert_all_md_files(node_id: str, output_file: Optional[str] = None) -> Tuple[int, int, int]:
     output_path = Path(output_file) if output_file else MANIFEST_PATH
-    
-    print(f"🔍 Scanning for .md files in {len(SEARCH_DIRS)} directories...")
+
     md_files = find_all_md_files()
-    print(f"✅ Found {len(md_files)} markdown files")
-    
     existing_ids = load_existing_manifest()
-    print(f"📋 Manifest already has {len(existing_ids)} entries")
-    
+
     converted = 0
     skipped = 0
-    
-    # Append new entries to manifest
+
     with open(output_path, "a") as manifest_f:
-        for i, md_file in enumerate(md_files, 1):
-            try:
-                entry = md_to_jsonl_entry(md_file)
-                entry_id = entry.get("id", "")
-                
-                if entry_id in existing_ids:
-                    skipped += 1
-                    status = "⏭️  SKIP"
-                else:
-                    manifest_f.write(json.dumps(entry) + "\n")
-                    manifest_f.flush()
-                    converted += 1
-                    status = "✅ CONV"
-                
-                rel_path = md_file.relative_to(WORKSPACE_ROOT)
-                print(f"[{i:3d}/{len(md_files)}] {status} {rel_path}")
-                
-            except Exception as e:
-                print(f"[{i:3d}/{len(md_files)}] ❌ ERR  {md_file.relative_to(WORKSPACE_ROOT)}: {e}")
+        for md_file in md_files:
+            entry = md_to_jsonl_entry(md_file, node_id=node_id)
+            entry_id = entry.get("id", "")
+            if entry_id in existing_ids:
                 skipped += 1
-    
+            else:
+                manifest_f.write(json.dumps(entry) + "\n")
+                manifest_f.flush()
+                converted += 1
+
     return len(md_files), converted, skipped
 
 
-def main():
-    """Main entry point."""
-    output_file = None
-    if len(sys.argv) > 2 and sys.argv[1] == "--output-file":
-        output_file = sys.argv[2]
-    
-    print("=" * 70)
-    print("Markdown to JSON-L Converter")
-    print(f"Workspace: {WORKSPACE_ROOT}")
-    print(f"Output: {output_file or MANIFEST_PATH}")
-    print("=" * 70)
-    
-    total, converted, skipped = convert_all_md_files(output_file)
-    
-    print("=" * 70)
-    print(f"📊 Summary:")
-    print(f"  Total files found: {total}")
-    print(f"  Newly converted:   {converted}")
-    print(f"  Already exists:    {skipped}")
-    print(f"  Output file: {output_file or MANIFEST_PATH}")
-    print("=" * 70)
-    
-    return 0 if converted > 0 or skipped > 0 else 1
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output-file", default=None)
+    parser.add_argument("--node-id", default=env_default("ENE_NODE_ID", "qfox"))
+    args = parser.parse_args()
+
+    total, converted, skipped = convert_all_md_files(node_id=args.node_id, output_file=args.output_file)
+    print(json.dumps({"total": total, "converted": converted, "skipped": skipped, "node_id": args.node_id}, indent=2))
+    return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    raise SystemExit(main())

From e36cff917bbef1d759141ff90e291a5d4d517356 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:42:03 -0500
Subject: [PATCH 21/43] cleanup(ene): make provenance node/tailscale
 configurable via env vars and CLI arg

---
 .../scripts/text_container_to_jsonl.py        | 454 ++++++++----------
 1 file changed, 191 insertions(+), 263 deletions(-)

diff --git a/5-Applications/scripts/text_container_to_jsonl.py b/5-Applications/scripts/text_container_to_jsonl.py
index efcc535e..f780fd5e 100644
--- a/5-Applications/scripts/text_container_to_jsonl.py
+++ b/5-Applications/scripts/text_container_to_jsonl.py
@@ -1,41 +1,38 @@
 #!/usr/bin/env python3
-"""
-Comprehensive Text Container to JSON-L Converter
+"""Comprehensive Text Container → JSON-L Converter (legacy shim).
 
-Converts all information-bearing text containers (MD, JSON, CSV, TSV, TXT) to
-JSON-L format compatible with UNIFIED_JSONL_SCHEMA.md.
-
-Handles:
-  - .md files (Markdown documents)
-  - .json files (JSON structures)
-  - .jsonl files (already JSON-L, wrap as documents)
-  - .csv files (tabular data)
-  - .tsv files (tabular data)
-  - .txt files (plain text documents)
-
-Excludes:
-  - Tool/library files (node_modules, .lake, tools/search, .git)
-  - Config files (setup.json, package.json, etc.)
-  - vendored dependencies
+Hardcoded node/provenance assumptions were removed:
+- node id is configurable via --node-id or ENE_NODE_ID
+- tailscale ip via ENE_TAILSCALE_IP
+- workspace root via ENE_WORKSPACE_ROOT
 
+This script is an ingest shim. Treat outputs as non-authoritative.
 """
 
+import argparse
 import json
 import csv
-import os
 import sys
 import hashlib
-import time
 from pathlib import Path
 from datetime import datetime, timezone
 from typing import Dict, Any, List, Optional, Tuple
 from dataclasses import dataclass
 
-# Configuration
-WORKSPACE_ROOT = Path("/home/allaun/Documents/Research Stack")
+
+def env_default(name: str, default: str) -> str:
+    try:
+        import os
+
+        v = os.environ.get(name)
+    except Exception:
+        v = None
+    return v if v is not None and v != "" else default
+
+
+WORKSPACE_ROOT = Path(env_default("ENE_WORKSPACE_ROOT", "/home/allaun/Documents/Research Stack"))
 MANIFEST_PATH = WORKSPACE_ROOT / "data" / "manifest.jsonl"
 
-# Directories to skip
 EXCLUDE_PATTERNS = [
     ".git",
     "node_modules",
@@ -50,10 +47,8 @@ EXCLUDE_PATTERNS = [
     "venv_",
 ]
 
-# File types to process
 PROCESS_EXTENSIONS = {".md", ".json", ".jsonl", ".csv", ".tsv", ".txt"}
 
-# Archetype mapping
 ARCHETYPE_MAP = {
     ".md": "markdown_document",
     ".json": "json_structure",
@@ -66,7 +61,6 @@ ARCHETYPE_MAP = {
 
 @dataclass
 class FileContainer:
-    """Represents a text-based information container."""
     filepath: Path
     ext: str
     size: int
@@ -75,50 +69,53 @@ class FileContainer:
 
 
 def should_skip(filepath: Path) -> Tuple[bool, str]:
-    """Check if file should be skipped."""
     path_str = str(filepath)
-    
-    # Skip 4-Infrastructure/config/metadata files
+
     config_files = {
-        "package.json", "package-lock.json", "tsconfig.json", "devcontainer.json",
-        "settings.json", "launch.json", "tasks.json", ".stylelintrc.json",
-        "biome.json", "lake-manifest.json", "pyrightconfig.json",
-        "manifest.json", "requirements.txt", "app.json", "acme.json",
-        ".vscode", ".devcontainer"
+        "package.json",
+        "package-lock.json",
+        "tsconfig.json",
+        "devcontainer.json",
+        "settings.json",
+        "launch.json",
+        "tasks.json",
+        ".stylelintrc.json",
+        "biome.json",
+        "lake-manifest.json",
+        "pyrightconfig.json",
+        "manifest.json",
+        "requirements.txt",
+        "app.json",
+        "acme.json",
+        ".vscode",
+        ".devcontainer",
     }
-    
+
     if filepath.name in config_files:
         return True, "config"
-    
-    # Skip excluded paths
+
     for pattern in EXCLUDE_PATTERNS:
         if pattern in path_str:
             return True, f"excluded:{pattern}"
-    
-    # Skip large binary-like files
-    if filepath.stat().st_size > 100_000_000:  # > 100MB
+
+    if filepath.stat().st_size > 100_000_000:
         return True, "too_large"
-    
+
     return False, ""
 
 
 def compute_sha256(filepath: Path) -> str:
-    """Compute SHA256 hash of file."""
     sha256 = hashlib.sha256()
-    try:
-        with open(filepath, "rb") as f:
-            for chunk in iter(lambda: f.read(8192), b""):
-                sha256.update(chunk)
-        return f"sha256:{sha256.hexdigest()}"
-    except Exception as e:
-        return f"sha256:error:{str(e)}"
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return f"sha256:{sha256.hexdigest()}"
 
 
 def infer_domain(filepath: Path, content: str = "") -> str:
-    """Infer domain from filename and path."""
     name = filepath.stem.upper()
     path = str(filepath).upper()
-    
+
     domain_hints = {
         "LEAN|SEMANTIC|FORMALIZATION": "formalization",
         "MATH|EQUATION|MODEL": "mathematics",
@@ -132,38 +129,34 @@ def infer_domain(filepath: Path, content: str = "") -> str:
         "DATA|DATASET|CSV|TSV": "data_science",
         "CONFIG|SETTING": "infrastructure",
     }
-    
+
     for patterns, domain in domain_hints.items():
         if any(p in name or p in path for p in patterns.split("|")):
             return domain
-    
-    # Default based on extension
-    if filepath.suffix == ".csv" or filepath.suffix == ".tsv":
+
+    if filepath.suffix in {".csv", ".tsv"}:
         return "data_science"
-    elif filepath.suffix == ".json":
+    if filepath.suffix == ".json":
         return "specification"
     return "unknown"
 
 
 def infer_tier(filepath: Path) -> str:
-    """Infer tier from path."""
     path = str(filepath).lower()
     if "6-Documentation/docs/semantics" in path or "docs" in path:
         return "CORE"
-    elif "shared-data/data/germane" in path:
+    if "shared-data/data/germane" in path:
         return "AUX"
-    elif "out" in path:
+    if "out" in path:
         return "DERIVED"
     return "AUX"
 
 
 def read_text_safely(filepath: Path, max_size: int = 1_000_000) -> str:
-    """Read text file safely with encoding fallback."""
     encodings = ["utf-8", "utf-8-sig", "latin-1", "ascii", "cp1252"]
-    
+
     size = filepath.stat().st_size
     if size > max_size:
-        # Read first and last chunks
         with open(filepath, "rb") as f:
             start = f.read(500)
             f.seek(max(0, size - 500))
@@ -172,275 +165,210 @@ def read_text_safely(filepath: Path, max_size: int = 1_000_000) -> str:
     else:
         with open(filepath, "rb") as f:
             content_bytes = f.read()
-    
+
     for encoding in encodings:
         try:
             return content_bytes.decode(encoding, errors="replace")
         except Exception:
             continue
-    
+
     return "<unable to decode>"
 
 
 def extract_summary(content: str, max_chars: int = 250) -> str:
-    """Extract summary from content."""
     lines = content.split("\n")
     summary_lines = []
-    
+
     for line in lines:
         stripped = line.strip()
         if stripped and not stripped.startswith("#") and not stripped.startswith("{"):
             summary_lines.append(stripped)
             if len(" ".join(summary_lines)) >= max_chars:
                 break
-    
+
     summary = " ".join(summary_lines)[:max_chars]
     return summary or "<empty or binary file>"
 
 
-def csv_to_dict_list(filepath: Path, limit_rows: int = 100) -> List[Dict]:
-    """Read CSV file into list of dicts."""
-    try:
-        with open(filepath, "r", encoding="utf-8", errors="replace") as f:
-            reader = csv.DictReader(f)
-            return list(islice(reader, limit_rows))
-    except Exception:
-        return []
-
-
 def compute_genome(filepath: Path, content: str = "") -> Dict[str, int]:
-    """Compute 6D genome signature."""
     try:
         size = filepath.stat().st_size
         lines = len(content.split("\n")) if content else 10
-        
+
         mu = (lines % 256) // 32
         rho = min(7, (size // 1024) % 8)
         c = 4
         m = 4
         ne = min(7, len(filepath.stem) // 10)
         sig = 0 if filepath.suffix != ".json" else 3
-        
+
         return {"mu": mu, "rho": rho, "c": c, "m": m, "ne": ne, "sig": sig}
     except Exception:
         return {"mu": 0, "rho": 0, "c": 4, "m": 4, "ne": 0, "sig": 0}
 
 
-def text_to_jsonl_entry(filepath: Path, node_id: str = "qfox") -> Optional[Dict[str, Any]]:
-    """Convert a text container to JSON-L entry."""
-    
-    try:
-        should_skip_file, reason = should_skip(filepath)
-        if should_skip_file:
-            return None
-        
-        # Read content
-        content = read_text_safely(filepath)
-        file_hash = compute_sha256(filepath)
-        file_stat = filepath.stat()
-        mtime_unix = file_stat.st_mtime
-        file_size = file_stat.st_size
-        
-        # Compute metadata
-        domain = infer_domain(filepath, content)
-        tier = infer_tier(filepath)
-        genome = compute_genome(filepath, content)
-        
-        # Create pkg identifier
-        rel_path = filepath.relative_to(WORKSPACE_ROOT)
-        pkg = f"ene/text/{filepath.suffix[1:]}/{rel_path.stem}".replace("\\", "/")
-        version = datetime.fromtimestamp(mtime_unix, tz=timezone.utc).isoformat()
-        
-        concept_anchor = {
-            "domain": domain,
-            "concept": filepath.stem.lower().replace(" ", "_").replace("-", "_").replace(".", "_"),
-            "resolution": "STABLE"
-        }
-        
-        # Extract data payload based on file type
-        summary = extract_summary(content)
-        
-        data_payload = {
-            "pkg": pkg,
-            "version": version,
-            "tier": tier,
-            "domain": domain,
-            "archetype": ARCHETYPE_MAP.get(filepath.suffix, "text_document"),
-            "concept_anchor": concept_anchor,
-            "file_path": str(rel_path).replace("\\", "/"),
-            "file_ext": filepath.suffix,
-            "file_hash": file_hash,
-            "byte_count": file_size,
-            "line_count": len(content.split("\n")),
-            "summary": summary,
-        }
-        
-        # Add format-specific metadata
-        if filepath.suffix == ".json":
-            try:
-                obj = json.loads(content)
-                data_payload["json_keys"] = list(obj.keys() if isinstance(obj, dict) else [])
-            except Exception:
-                data_payload["json_keys"] = []
-        
-        elif filepath.suffix in {".csv", ".tsv"}:
-            try:
-                with open(filepath, "r", encoding="utf-8", errors="replace") as f:
-                    reader = csv.DictReader(f)
-                    first_row = next(reader, None)
-                    if first_row:
-                        data_payload["columns"] = list(first_row.keys())
-            except Exception:
-                pass
-        
-        # Provenance
-        provenance = {
-            "node": node_id,
-            "lake_seed": "text_converter",
-            "tailscale_ip": "127.0.0.1",
-            "attestation_hash": file_hash,
-            "prev_id": None
-        }
-        
-        # Bind
-        bind = {
-            "lawful": True,
-            "cost": 0x00010000,
-            "invariant": "documentConsistency",
-            "class": "informational_bind"
-        }
-        
-        # Full JSON-L entry
-        entry = {
-            "t": mtime_unix,
-            "src": "ene",
-            "id": f"ene:{pkg}:{version}",
-            "op": "upsert",
-            "data": data_payload,
-            "genome": genome,
-            "bind": bind,
-            "provenance": provenance
-        }
-        
-        return entry
-        
-    except Exception as e:
-        print(f"  ⚠️  Error processing {filepath}: {e}", file=sys.stderr)
+def text_to_jsonl_entry(filepath: Path, node_id: str) -> Optional[Dict[str, Any]]:
+    should_skip_file, _reason = should_skip(filepath)
+    if should_skip_file:
         return None
 
+    content = read_text_safely(filepath)
+    file_hash = compute_sha256(filepath)
+    file_stat = filepath.stat()
+    mtime_unix = file_stat.st_mtime
+    file_size = file_stat.st_size
+
+    domain = infer_domain(filepath, content)
+    tier = infer_tier(filepath)
+    genome = compute_genome(filepath, content)
+
+    rel_path = filepath.relative_to(WORKSPACE_ROOT)
+    pkg = f"ene/text/{filepath.suffix[1:]}/{rel_path.stem}".replace("\\", "/")
+    version = datetime.fromtimestamp(mtime_unix, tz=timezone.utc).isoformat()
+
+    concept_anchor = {
+        "domain": domain,
+        "concept": filepath.stem.lower().replace(" ", "_").replace("-", "_").replace(".", "_"),
+        "resolution": "STABLE",
+    }
+
+    summary = extract_summary(content)
+
+    data_payload: Dict[str, Any] = {
+        "pkg": pkg,
+        "version": version,
+        "tier": tier,
+        "domain": domain,
+        "archetype": ARCHETYPE_MAP.get(filepath.suffix, "text_document"),
+        "concept_anchor": concept_anchor,
+        "file_path": str(rel_path).replace("\\", "/"),
+        "file_ext": filepath.suffix,
+        "file_hash": file_hash,
+        "byte_count": file_size,
+        "line_count": len(content.split("\n")),
+        "summary": summary,
+    }
+
+    if filepath.suffix == ".json":
+        try:
+            obj = json.loads(content)
+            data_payload["json_keys"] = list(obj.keys() if isinstance(obj, dict) else [])
+        except Exception:
+            data_payload["json_keys"] = []
+
+    if filepath.suffix in {".csv", ".tsv"}:
+        try:
+            with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+                reader = csv.DictReader(f)
+                first_row = next(reader, None)
+                if first_row:
+                    data_payload["columns"] = list(first_row.keys())
+        except Exception:
+            pass
+
+    provenance = {
+        "node": node_id,
+        "lake_seed": env_default("ENE_LAKE_SEED", "text_converter"),
+        "tailscale_ip": env_default("ENE_TAILSCALE_IP", "127.0.0.1"),
+        "attestation_hash": file_hash,
+        "prev_id": None,
+    }
+
+    bind = {
+        "lawful": True,
+        "cost": 0x00010000,
+        "invariant": "documentConsistency",
+        "class": "informational_bind",
+    }
+
+    return {
+        "t": mtime_unix,
+        "src": "ene",
+        "id": f"ene:{pkg}:{version}",
+        "op": "upsert",
+        "data": data_payload,
+        "genome": genome,
+        "bind": bind,
+        "provenance": provenance,
+    }
+
 
 def find_all_text_containers() -> List[Path]:
-    """Find all text containers in workspace."""
     containers = []
-    
     for ext in PROCESS_EXTENSIONS:
         for file_path in WORKSPACE_ROOT.rglob(f"*{ext}"):
             if file_path.is_file():
                 containers.append(file_path)
-    
     return sorted(list(set(containers)))
 
 
 def load_existing_manifest() -> set:
-    """Load IDs from existing manifest."""
     existing_ids = set()
     if MANIFEST_PATH.exists():
-        try:
-            with open(MANIFEST_PATH, "r") as f:
-                for line in f:
-                    line = line.strip()
-                    if line:
-                        try:
-                            entry = json.loads(line)
-                            existing_ids.add(entry.get("id", ""))
-                        except json.JSONDecodeError:
-                            pass
-        except Exception as e:
-            print(f"Warning: Could not read existing manifest: {e}")
+        with open(MANIFEST_PATH, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    existing_ids.add(entry.get("id", ""))
+                except json.JSONDecodeError:
+                    continue
     return existing_ids
 
 
-def convert_all_text_containers(output_file: Optional[str] = None) -> Tuple[int, int, int, int]:
-    """
-    Convert all text containers to JSON-L.
-    
-    Returns: (total_files, newly_converted, already_exists, skipped)
-    """
-    from itertools import islice
-    
+def convert_all_text_containers(node_id: str, output_file: Optional[str] = None) -> Tuple[int, int, int, int]:
     output_path = Path(output_file) if output_file else MANIFEST_PATH
-    
-    print(f"🔍 Scanning for text containers...")
+
     containers = find_all_text_containers()
-    print(f"✅ Found {len(containers)} text containers")
-    
     existing_ids = load_existing_manifest()
-    print(f"📋 Manifest already has {len(existing_ids)} entries")
-    print()
-    
+
     converted = 0
     skipped = 0
     already_exists = 0
-    
-    ext_stats = {}
-    
+
     with open(output_path, "a") as manifest_f:
-        for i, container in enumerate(containers, 1):
-            ext = container.suffix
-            ext_stats[ext] = ext_stats.get(ext, 0) + 1
-            
-            entry = text_to_jsonl_entry(container)
-            
+        for container in containers:
+            entry = text_to_jsonl_entry(container, node_id=node_id)
             if entry is None:
                 skipped += 1
-                status = "⏭️  SKIP"
+                continue
+
+            entry_id = entry.get("id", "")
+            if entry_id in existing_ids:
+                already_exists += 1
             else:
-                entry_id = entry.get("id", "")
-                if entry_id in existing_ids:
-                    already_exists += 1
-                    status = "⏪ DUP"
-                else:
-                    manifest_f.write(json.dumps(entry) + "\n")
-                    manifest_f.flush()
-                    converted += 1
-                    status = "✅ CONV"
-            
-            rel_path = container.relative_to(WORKSPACE_ROOT)
-            
-            # Less verbose output
-            if i % 10 == 0 or status == "✅ CONV":
-                print(f"[{i:4d}/{len(containers)}] {status} {rel_path}")
-    
+                manifest_f.write(json.dumps(entry) + "\n")
+                manifest_f.flush()
+                converted += 1
+
     return len(containers), converted, already_exists, skipped
 
 
-def main():
-    """Main entry point."""
-    output_file = None
-    if len(sys.argv) > 2 and sys.argv[1] == "--output-file":
-        output_file = sys.argv[2]
-    
-    print("=" * 75)
-    print("🌐 Comprehensive Text Container to JSON-L Converter")
-    print(f"Workspace: {WORKSPACE_ROOT}")
-    print(f"Output: {output_file or MANIFEST_PATH}")
-    print("=" * 75)
-    print()
-    
-    total, converted, already_exists, skipped = convert_all_text_containers(output_file)
-    
-    print()
-    print("=" * 75)
-    print(f"📊 Summary:")
-    print(f"  Total files scanned:  {total}")
-    print(f"  Newly converted:      {converted}")
-    print(f"  Already in manifest:  {already_exists}")
-    print(f"  Skipped:              {skipped}")
-    print(f"  Output file: {output_file or MANIFEST_PATH}")
-    print("=" * 75)
-    
-    return 0 if converted > 0 else 1
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output-file", default=None)
+    parser.add_argument("--node-id", default=env_default("ENE_NODE_ID", "qfox"))
+    args = parser.parse_args()
+
+    total, converted, already_exists, skipped = convert_all_text_containers(
+        node_id=args.node_id, output_file=args.output_file
+    )
+    print(
+        json.dumps(
+            {
+                "total": total,
+                "converted": converted,
+                "already_exists": already_exists,
+                "skipped": skipped,
+                "node_id": args.node_id,
+            },
+            indent=2,
+        )
+    )
+    return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    raise SystemExit(main())

From 87e5eb33a706bc35dd2308c76e3cdbbf9a2f78c6 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 16:54:12 -0500
Subject: [PATCH 22/43] cleanup(ene): make obsidian shim provenance
 configurable and schema-complete

---
 5-Applications/scripts/obsidian_sync_shim.py | 147 +++++++++++--------
 1 file changed, 82 insertions(+), 65 deletions(-)

diff --git a/5-Applications/scripts/obsidian_sync_shim.py b/5-Applications/scripts/obsidian_sync_shim.py
index 57937c68..7187f685 100644
--- a/5-Applications/scripts/obsidian_sync_shim.py
+++ b/5-Applications/scripts/obsidian_sync_shim.py
@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
-"""
-obsidian_sync_shim.py — Bidirectional sync between Obsidian vault and JSON-L lake.
+"""obsidian_sync_shim.py — Bidirectional sync between Obsidian vault and JSON-L lake.
 
 Modes:
     ingest    : Obsidian notes → JSON-L lake (append to lake file)
@@ -9,6 +8,13 @@ Modes:
 
 Requires TOPOLOGICAL_ENGINE_URL and TOPOLOGICAL_ENGINE_TOKEN in .env.
 For local Obsidian installs, set OBSIDIAN_VAULT_PATH or use --vault.
+
+Hardcoded node/provenance assumptions were removed:
+- provenance.node uses ENE_NODE_ID (default: obsidian_sync_shim)
+- provenance.lake_seed uses ENE_LAKE_SEED (default: obsidian_lake)
+- provenance.tailscale_ip uses ENE_TAILSCALE_IP (default: 127.0.0.1)
+
+NOTE: This is a legacy ingest surface; treat outputs as non-authoritative.
 """
 
 import sys
@@ -25,6 +31,7 @@ from typing import Dict, List, Any, Optional
 project_root = Path(__file__).parent.parent.parent
 try:
     from dotenv import load_dotenv
+
     if (project_root / ".env").exists():
         load_dotenv(project_root / ".env")
 except ImportError:
@@ -36,6 +43,11 @@ sys.path.insert(0, str(project_root / "4-Infrastructure" / "infra"))
 from infra.topological_engine_client import TopologicalEngineClient
 
 
+def env_default(name: str, default: str) -> str:
+    v = os.getenv(name)
+    return v if v is not None and v != "" else default
+
+
 DEFAULT_VAULT_PATH = project_root / "Obdisidan connector"
 LAKE_PATH = Path(os.getenv("OBSIDIAN_LAKE_PATH", str(project_root / "data" / "obsidian_lake.jsonl")))
 LAKE_PATH.parent.mkdir(parents=True, exist_ok=True)
@@ -91,11 +103,21 @@ def _format_jsonl_entry(
     tier: str = "AUX",
     domain: str = "obsidian",
     archetype: str = "note",
-    src: str = "obsidian_sync_shim"
+    src: str = "obsidian_sync_shim",
 ) -> Dict[str, Any]:
     """Format a JSON-L entry for the Research Stack lake."""
     now = datetime.now(timezone.utc)
     timestamp = now.isoformat()
+
+    node_id = env_default("ENE_NODE_ID", "obsidian_sync_shim")
+    lake_seed = env_default("ENE_LAKE_SEED", "obsidian_lake")
+    tailscale_ip = env_default("ENE_TAILSCALE_IP", "127.0.0.1")
+
+    # Deterministic attestation over the minimal payload.
+    attestation_hash = "sha256:" + hashlib.sha256(
+        (pkg + ":" + timestamp + ":" + json.dumps(data, sort_keys=True, ensure_ascii=False)).encode("utf-8")
+    ).hexdigest()
+
     return {
         "t": now.timestamp(),
         "src": src,
@@ -107,18 +129,21 @@ def _format_jsonl_entry(
             "tier": tier,
             "domain": domain,
             "archetype": archetype,
-            **data
+            **data,
         },
         "bind": {
             "lawful": True,
             "cost": 65536,
             "invariant": "noteConsistency",
-            "class": "informational_bind"
+            "class": "informational_bind",
         },
         "provenance": {
-            "node": "obsidian_sync_shim",
-            "lake_seed": "obsidian_lake"
-        }
+            "node": node_id,
+            "lake_seed": lake_seed,
+            "tailscale_ip": tailscale_ip,
+            "attestation_hash": attestation_hash,
+            "prev_id": None,
+        },
     }
 
 
@@ -129,7 +154,7 @@ def _format_jsonl_entry(
 def ingest_obsidian(
     client: TopologicalEngineClient,
     query: str = "*",
-    lake_path: Path = LAKE_PATH
+    lake_path: Path = LAKE_PATH,
 ) -> Dict[str, Any]:
     """Pull notes from Obsidian vault and append to JSON-L lake."""
     print("[ingest] Searching Obsidian vault...")
@@ -156,11 +181,10 @@ def ingest_obsidian(
                 "links": note.get("links", []),
                 "tags": note.get("tags", []),
                 "modified": note.get("modified", note.get("mtime")),
-            }
+            },
         )
         entries.append(entry)
 
-    # Append to lake
     with open(lake_path, "a") as f:
         for entry in entries:
             f.write(json.dumps(entry) + "\n")
@@ -172,7 +196,7 @@ def ingest_obsidian(
 def ingest_local_obsidian(
     vault_path: Path,
     query: str = "*",
-    lake_path: Path = LAKE_PATH
+    lake_path: Path = LAKE_PATH,
 ) -> Dict[str, Any]:
     """Pull notes from a local Obsidian vault and append to JSON-L lake."""
     if not vault_path.exists():
@@ -223,7 +247,7 @@ def ingest_local_obsidian(
 def export_to_obsidian(
     client: TopologicalEngineClient,
     lake_path: Path = LAKE_PATH,
-    filter_domain: str = "obsidian"
+    filter_domain: str = "obsidian",
 ) -> Dict[str, Any]:
     """Read JSON-L lake and write matching entries back to Obsidian vault."""
     if not lake_path.exists():
@@ -257,19 +281,21 @@ def export_to_obsidian(
         if not path:
             continue
 
-        # Reconstruct a simple markdown note
         md = f"# {title}\n\n"
         md += f"> Synced from JSON-L lake at {datetime.now(timezone.utc).isoformat()}\n\n"
         md += content_preview
         if len(content_preview) >= 500:
             md += "\n\n...(truncated)"
 
-        # Write via topological engine
-        res = client.write_obsidian_note(path=path, body=md, metadata={
-            "source": "research_stack_lake",
-            "entry_id": entry.get("id"),
-            "synced_at": datetime.now(timezone.utc).isoformat()
-        })
+        res = client.write_obsidian_note(
+            path=path,
+            body=md,
+            metadata={
+                "source": "research_stack_lake",
+                "entry_id": entry.get("id"),
+                "synced_at": datetime.now(timezone.utc).isoformat(),
+            },
+        )
         if "error" not in res:
             written += 1
 
@@ -281,7 +307,7 @@ def export_to_local_obsidian(
     vault_path: Path,
     lake_path: Path = LAKE_PATH,
     filter_domain: str = "obsidian",
-    overwrite: bool = False
+    overwrite: bool = False,
 ) -> Dict[str, Any]:
     """Read JSON-L lake and write matching entries into a local Obsidian vault."""
     if not lake_path.exists():
@@ -339,15 +365,8 @@ def export_to_local_obsidian(
 def sync_bidirectional(
     client: TopologicalEngineClient,
     lake_path: Path = LAKE_PATH,
-    obsidian_wins: bool = True
+    obsidian_wins: bool = True,
 ) -> Dict[str, Any]:
-    """
-    Two-way sync:
-    1. Ingest current Obsidian state into lake.
-    2. Export lake entries back to Obsidian (creating any missing notes).
-
-    If obsidian_wins=True, existing Obsidian notes are not overwritten.
-    """
     print("[sync] Starting bidirectional sync...")
     ingest_res = ingest_obsidian(client, lake_path=lake_path)
     if "error" in ingest_res:
@@ -355,13 +374,11 @@ def sync_bidirectional(
 
     if obsidian_wins:
         print("[sync] Obsidian-wins mode: skipping overwrite of existing notes")
-        # In export mode, only write notes that don't already exist
         search_res = client.search_obsidian("*")
         existing_paths = set()
         for note in search_res.get("results", search_res.get("notes", [])):
             existing_paths.add(note.get("path", note.get("file_path")))
 
-        # Filter lake entries to only missing paths
         if lake_path.exists():
             entries = []
             with open(lake_path) as f:
@@ -387,23 +404,16 @@ def sync_bidirectional(
                     written += 1
             print(f"[sync] Created {written} missing notes in Obsidian")
             return {"ingested": ingest_res["ingested"], "created": written}
-    else:
-        export_res = export_to_obsidian(client, lake_path=lake_path)
-        return {"ingested": ingest_res["ingested"], **export_res}
+
+    export_res = export_to_obsidian(client, lake_path=lake_path)
+    return {"ingested": ingest_res["ingested"], **export_res}
 
 
 def sync_local_bidirectional(
     vault_path: Path,
     lake_path: Path = LAKE_PATH,
-    obsidian_wins: bool = True
+    obsidian_wins: bool = True,
 ) -> Dict[str, Any]:
-    """
-    Local two-way sync:
-    1. Ingest current local Obsidian state into lake.
-    2. Export lake entries back to the vault.
-
-    If obsidian_wins=True, existing local notes are not overwritten.
-    """
     print("[sync:local] Starting bidirectional local sync")
     ingest_res = ingest_local_obsidian(vault_path=vault_path, lake_path=lake_path)
     if "error" in ingest_res:
@@ -424,18 +434,33 @@ def sync_local_bidirectional(
 
 def main():
     parser = argparse.ArgumentParser(description="Obsidian ↔ JSON-L lake sync shim")
-    parser.add_argument("mode", choices=["ingest", "export", "sync"], default="sync", nargs="?",
-                        help="ingest=Obsidian→lake, export=lake→Obsidian, sync=both")
-    parser.add_argument("--backend", choices=["auto", "local", "engine"], default="auto",
-                        help="local=filesystem vault, engine=topological engine, auto=engine if healthy else local")
-    parser.add_argument("--vault", default=None,
-                        help="Local Obsidian vault path; defaults to OBSIDIAN_VAULT_PATH or ./Obdisidan connector")
+    parser.add_argument(
+        "mode",
+        choices=["ingest", "export", "sync"],
+        default="sync",
+        nargs="?",
+        help="ingest=Obsidian→lake, export=lake→Obsidian, sync=both",
+    )
+    parser.add_argument(
+        "--backend",
+        choices=["auto", "local", "engine"],
+        default="auto",
+        help="local=filesystem vault, engine=topological engine, auto=engine if healthy else local",
+    )
+    parser.add_argument(
+        "--vault",
+        default=None,
+        help="Local Obsidian vault path; defaults to OBSIDIAN_VAULT_PATH or ./Obdisidan connector",
+    )
     parser.add_argument("--lake", default=str(LAKE_PATH), help="Path to JSON-L lake file")
     parser.add_argument("--query", default="*", help="Obsidian search query (ingest mode)")
-    parser.add_argument("--obsidian-wins", action="store_true", default=True,
-                        help="In sync mode, don't overwrite existing Obsidian notes")
-    parser.add_argument("--lake-wins", action="store_true",
-                        help="In sync mode, overwrite Obsidian with lake contents")
+    parser.add_argument(
+        "--obsidian-wins",
+        action="store_true",
+        default=True,
+        help="In sync mode, don't overwrite existing Obsidian notes",
+    )
+    parser.add_argument("--lake-wins", action="store_true", help="In sync mode, overwrite Obsidian with lake")
     args = parser.parse_args()
 
     lake_path = Path(args.lake)
@@ -461,17 +486,9 @@ def main():
         if args.mode == "ingest":
             result = ingest_local_obsidian(vault_path=vault_path, query=args.query, lake_path=lake_path)
         elif args.mode == "export":
-            result = export_to_local_obsidian(
-                vault_path=vault_path,
-                lake_path=lake_path,
-                overwrite=not obsidian_wins,
-            )
+            result = export_to_local_obsidian(vault_path=vault_path, lake_path=lake_path, overwrite=not obsidian_wins)
         else:
-            result = sync_local_bidirectional(
-                vault_path=vault_path,
-                lake_path=lake_path,
-                obsidian_wins=obsidian_wins,
-            )
+            result = sync_local_bidirectional(vault_path=vault_path, lake_path=lake_path, obsidian_wins=obsidian_wins)
     else:
         if args.mode == "ingest":
             result = ingest_obsidian(client, query=args.query, lake_path=lake_path)
@@ -483,9 +500,9 @@ def main():
     if "error" in result:
         print(f"Error: {result['error']}")
         sys.exit(1)
-    else:
-        print(f"Done: {json.dumps(result, indent=2)}")
-        sys.exit(0)
+
+    print(f"Done: {json.dumps(result, indent=2)}")
+    sys.exit(0)
 
 
 if __name__ == "__main__":

From a5a10723ab3117f399dc187224d8613dc0c6da90 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:15:50 -0500
Subject: [PATCH 23/43] cleanup(ene): use nodes.yaml inventory instead of
 hardcoded host resource map

---
 .../scripts/swarm_network_capacity.py         | 432 +++++++-----------
 1 file changed, 170 insertions(+), 262 deletions(-)

diff --git a/5-Applications/scripts/swarm_network_capacity.py b/5-Applications/scripts/swarm_network_capacity.py
index 11825d74..0205236a 100644
--- a/5-Applications/scripts/swarm_network_capacity.py
+++ b/5-Applications/scripts/swarm_network_capacity.py
@@ -1,25 +1,27 @@
 #!/usr/bin/env python3
-"""
-swarm_network_capacity.py — Network Resource Capacity Monitor
+"""swarm_network_capacity.py — Network Resource Capacity Monitor (legacy shim).
 
-Checks all Tailscale-connected nodes (via ENE mesh) to determine:
-- Total available resources across the network
-- Currently utilized capacity
-- Idle resources that could be leveraged
-- Node health and connectivity status
+Cleanups:
+- Removed hardcoded hostname→resource maps.
+- Reads node inventory from 4-Infrastructure/auto/config/nodes.yaml (controller source of truth).
+
+NOTE: This is a legacy monitoring surface; treat results as advisory.
 """
 
-import subprocess
+from __future__ import annotations
+
+import argparse
 import json
 import re
+import subprocess
 from dataclasses import dataclass
-from typing import List, Dict, Optional
 from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
 
 
 @dataclass
 class TailscaleNode:
-    """Remote node in the Tailscale mesh."""
     ip: str
     hostname: str
     owner: str
@@ -27,14 +29,13 @@ class TailscaleNode:
     status: str  # online, offline, idle
     last_seen: Optional[str]
     tags: List[str]
-    
+
     def is_online(self) -> bool:
-        return self.status == "online" or self.status == "idle"
+        return self.status in {"online", "idle"}
 
 
 @dataclass
 class NodeResources:
-    """Resource capacity of a node."""
     node_id: str
     cpu_cores: int
     memory_gb: float
@@ -45,187 +46,172 @@ class NodeResources:
     utilization_percent: float
 
 
+def _load_nodes_inventory(path: Path) -> Dict[str, Any]:
+    """Load nodes.yaml.
+
+    Tries PyYAML; if missing, raises a clear error.
+    """
+    try:
+        import yaml  # type: ignore
+    except ImportError as exc:
+        raise RuntimeError(
+            "nodes.yaml parsing requires PyYAML. Install with: pip install pyyaml"
+        ) from exc
+
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or "nodes" not in data:
+        raise ValueError(f"Invalid nodes inventory file: {path}")
+    return data
+
+
 class SwarmNetworkCapacity:
-    """
-    Monitor and report on full network resource capacity.
-    
-    Queries Tailscale mesh and ENE nodes to determine:
-    - Total available compute across all nodes
-    - Current utilization vs capacity
-    - Resource distribution
-    """
-    
-    def __init__(self):
+    def __init__(self, inventory_path: Path):
+        self.inventory_path = inventory_path
+        self.inventory = _load_nodes_inventory(inventory_path)
         self.tailscale_nodes: List[TailscaleNode] = []
         self.ene_nodes: List[str] = []
         self.local_ip: Optional[str] = None
-        
+
     def discover_tailscale_mesh(self) -> List[TailscaleNode]:
-        """Discover all nodes in the Tailscale mesh."""
         print("\n[1] Discovering Tailscale mesh nodes...")
-        
         try:
             result = subprocess.run(
                 ["tailscale", "status"],
                 capture_output=True,
                 text=True,
-                timeout=10
+                timeout=10,
             )
-            
-            lines = result.stdout.strip().split('\n')
-            nodes = []
-            
+
+            lines = result.stdout.strip().split("\n")
+            nodes: List[TailscaleNode] = []
+
             for line in lines:
                 if not line.strip():
                     continue
-                
-                # Parse tailscale status line
-                # Format: 100.x.x.x  hostname  owner@  os  status
+
                 parts = line.split()
                 if len(parts) >= 4:
                     ip = parts[0]
                     hostname = parts[1]
                     owner = parts[2]
                     os_type = parts[3]
-                    
-                    # Parse status (can be complex)
-                    status_parts = ' '.join(parts[4:]) if len(parts) > 4 else ""
-                    
-                    # Determine status
+                    status_parts = " ".join(parts[4:]) if len(parts) > 4 else ""
+
                     if "offline" in status_parts.lower():
                         status = "offline"
                     elif "idle" in status_parts.lower():
                         status = "idle"
                     else:
                         status = "online"
-                    
-                    # Extract last seen if offline
+
                     last_seen = None
                     if "last seen" in status_parts:
-                        match = re.search(r'last seen ([^,]+)', status_parts)
+                        match = re.search(r"last seen ([^,]+)", status_parts)
                         if match:
                             last_seen = match.group(1)
-                    
-                    # Extract tags
-                    tags = []
+
+                    tags: List[str] = []
                     if "tagged-devices" in line:
                         tags.append("tagged-devices")
-                    
-                    node = TailscaleNode(
-                        ip=ip,
-                        hostname=hostname,
-                        owner=owner,
-                        os=os_type,
-                        status=status,
-                        last_seen=last_seen,
-                        tags=tags
+
+                    nodes.append(
+                        TailscaleNode(
+                            ip=ip,
+                            hostname=hostname,
+                            owner=owner,
+                            os=os_type,
+                            status=status,
+                            last_seen=last_seen,
+                            tags=tags,
+                        )
                     )
-                    nodes.append(node)
-            
+
             self.tailscale_nodes = nodes
-            
-            # Get local IP
+
             try:
                 ip_result = subprocess.run(
                     ["tailscale", "ip", "-4"],
                     capture_output=True,
                     text=True,
-                    timeout=5
+                    timeout=5,
                 )
                 self.local_ip = ip_result.stdout.strip()
-            except:
+            except Exception:
                 pass
-            
+
             print(f"  Found: {len(nodes)} Tailscale nodes")
             online = sum(1 for n in nodes if n.is_online())
             print(f"  Online: {online}/{len(nodes)}")
-            
+
             for node in nodes:
-                status_icon = "🟢" if node.is_online() else "🔴"
-                print(f"    {status_icon} {node.hostname} ({node.ip}) - {node.status}")
-            
+                status_icon = "online" if node.is_online() else "offline"
+                print(f"    [{status_icon}] {node.hostname} ({node.ip})")
+
             return nodes
-            
+
         except Exception as e:
             print(f"  ⚠️  Error discovering mesh: {e}")
             return []
-    
+
     def check_ene_deployment(self) -> List[str]:
-        """Check which nodes have ENE deployed."""
-        print("\n[2] Checking ENE deployment status...")
-        
-        ene_nodes = []
-        
-        for node in self.tailscale_nodes:
-            if not node.is_online():
-                continue
-            
-            # Try to check if ENE is running on remote node
-            # This would typically use SSH or ENE's gossip protocol
-            # For now, we'll simulate based on known deployment
-            
-            if node.hostname in ["architect", "judge", "qfox"]:
-                ene_nodes.append(node.hostname)
-        
-        self.ene_nodes = ene_nodes
-        
-        print(f"  ENE deployed on: {len(ene_nodes)} nodes")
-        for node in ene_nodes:
-            print(f"    ✅ {node}")
-        
-        # Nodes needing ENE deployment
-        online_nodes = [n.hostname for n in self.tailscale_nodes if n.is_online()]
-        need_ene = set(online_nodes) - set(ene_nodes)
-        if need_ene:
-            print(f"  Need ENE deployment: {len(need_ene)} nodes")
-            for node in need_ene:
-                print(f"    ⚠️  {node}")
-        
-        return ene_nodes
-    
+        """Check which nodes have ENE deployed.
+
+        For now this still uses a heuristic: nodes with role including 'compute'
+        or 'service-host' are assumed to be candidates. Real checks should be via
+        SSH/probes.
+        """
+        print("\n[2] Checking ENE deployment status (heuristic)...")
+        nodes = self.inventory.get("nodes", {})
+        ene_nodes: List[str] = []
+        for node_id, spec in nodes.items():
+            roles = spec.get("roles", []) if isinstance(spec, dict) else []
+            if any(r in roles for r in ["compute", "service-host", "control-plane"]):
+                ene_nodes.append(node_id)
+        self.ene_nodes = sorted(set(ene_nodes))
+
+        print(f"  ENE candidates: {len(self.ene_nodes)}")
+        for n in self.ene_nodes[:20]:
+            print(f"    ✅ {n}")
+        return self.ene_nodes
+
     def estimate_node_resources(self, node: TailscaleNode) -> Optional[NodeResources]:
-        """Estimate resources available on a node."""
-        # These would normally be queried from the node
-        # For now, estimate based on hostname patterns
-        
-        resource_map = {
-            "qfox": {"cpu": 16, "ram": 32, "storage": 1000, "gpu": 1, "bw": 1000},
-            "architect": {"cpu": 8, "ram": 16, "storage": 500, "gpu": 0, "bw": 500},
-            "judge": {"cpu": 4, "ram": 8, "storage": 200, "gpu": 0, "bw": 500},
-            "ip-172-31-25-81": {"cpu": 2, "ram": 4, "storage": 100, "gpu": 0, "bw": 1000},  # AWS
-            "netcup-router": {"cpu": 4, "ram": 8, "storage": 500, "gpu": 0, "bw": 1000},
-            "racknerd-510bd9c": {"cpu": 2, "ram": 4, "storage": 100, "gpu": 0, "bw": 1000},
-            "racknerd-atl": {"cpu": 2, "ram": 4, "storage": 100, "gpu": 0, "bw": 1000},
-            "desktop-0u2ceal": {"cpu": 8, "ram": 16, "storage": 500, "gpu": 1, "bw": 100},
-        }
-        
-        specs = resource_map.get(node.hostname, {"cpu": 2, "ram": 4, "storage": 100, "gpu": 0, "bw": 100})
-        
+        """Estimate node resources.
+
+        nodes.yaml currently doesn't track CPU/RAM explicitly; so this function
+        returns conservative defaults. Once resources are added to nodes.yaml,
+        this function will use them directly.
+        """
+        specs = self.inventory.get("nodes", {}).get(node.hostname) or {}
+        cpu = int(specs.get("cpu", 2)) if isinstance(specs, dict) else 2
+        ram = float(specs.get("ram", 4)) if isinstance(specs, dict) else 4.0
+        storage = float(specs.get("storage", 100)) if isinstance(specs, dict) else 100.0
+        gpu = int(specs.get("gpu", 0)) if isinstance(specs, dict) else 0
+        bw = float(specs.get("bw", 100)) if isinstance(specs, dict) else 100.0
+
         return NodeResources(
             node_id=node.hostname,
-            cpu_cores=specs["cpu"],
-            memory_gb=specs["ram"],
-            storage_gb=specs["storage"],
-            bandwidth_mbps=specs["bw"],
-            gpu_count=specs["gpu"],
+            cpu_cores=cpu,
+            memory_gb=ram,
+            storage_gb=storage,
+            bandwidth_mbps=bw,
+            gpu_count=gpu,
             ene_enabled=node.hostname in self.ene_nodes,
-            utilization_percent=0.0  # Would need actual monitoring
+            utilization_percent=0.0,
         )
-    
+
     def calculate_total_capacity(self) -> Dict[str, float]:
-        """Calculate total network capacity."""
         print("\n[3] Calculating total network capacity...")
-        
+
         total_cpu = 0
         total_ram = 0.0
         total_storage = 0.0
         total_gpu = 0
         total_bw = 0.0
-        
+
         for node in self.tailscale_nodes:
             if not node.is_online():
                 continue
-            
+
             resources = self.estimate_node_resources(node)
             if resources:
                 total_cpu += resources.cpu_cores
@@ -233,182 +219,104 @@ class SwarmNetworkCapacity:
                 total_storage += resources.storage_gb
                 total_gpu += resources.gpu_count
                 total_bw += resources.bandwidth_mbps
-        
-        capacity = {
-            "cpu_cores": total_cpu,
+
+        capacity: Dict[str, float] = {
+            "cpu_cores": float(total_cpu),
             "memory_gb": total_ram,
             "storage_gb": total_storage,
-            "gpu_count": total_gpu,
+            "gpu_count": float(total_gpu),
             "bandwidth_mbps": total_bw,
-            "online_nodes": sum(1 for n in self.tailscale_nodes if n.is_online()),
-            "total_nodes": len(self.tailscale_nodes)
+            "online_nodes": float(sum(1 for n in self.tailscale_nodes if n.is_online())),
+            "total_nodes": float(len(self.tailscale_nodes)),
         }
-        
-        print(f"  CPU Cores: {total_cpu}")
+
+        print(f"  CPU Cores: {int(total_cpu)}")
         print(f"  Memory: {total_ram:.1f} GB")
         print(f"  Storage: {total_storage:.1f} GB")
-        print(f"  GPUs: {total_gpu}")
+        print(f"  GPUs: {int(total_gpu)}")
         print(f"  Bandwidth: {total_bw:.0f} Mbps")
-        
+
         return capacity
-    
+
     def check_current_utilization(self) -> Dict[str, float]:
-        """Check current resource utilization."""
         print("\n[4] Checking current utilization (local node only)...")
-        
+
         try:
-            # Get local CPU/memory
-            result = subprocess.run(
-                ["cat", "/proc/loadavg"],
-                capture_output=True,
-                text=True,
-                timeout=5
-            )
+            result = subprocess.run(["cat", "/proc/loadavg"], capture_output=True, text=True, timeout=5)
             load_parts = result.stdout.strip().split()
             load_1min = float(load_parts[0]) if load_parts else 0.0
-            
-            # Estimate CPU utilization from load
-            # This is simplified - would need per-node queries
-            cpu_util = min(100.0, (load_1min / 16) * 100)  # Assuming 16 cores
-            
-            # Memory
-            mem_result = subprocess.run(
-                ["free", "-m"],
-                capture_output=True,
-                text=True,
-                timeout=5
-            )
-            
-            mem_lines = mem_result.stdout.split('\n')
+
+            cpu_util = min(100.0, (load_1min / 16) * 100)
+
+            mem_result = subprocess.run(["free", "-m"], capture_output=True, text=True, timeout=5)
+            mem_lines = mem_result.stdout.split("\n")
             mem_used = 0
             mem_total = 1
             for line in mem_lines:
-                if line.startswith('Mem:'):
+                if line.startswith("Mem:"):
                     parts = line.split()
                     mem_total = int(parts[1])
                     mem_used = int(parts[2])
                     break
-            
+
             mem_util = (mem_used / mem_total) * 100 if mem_total > 0 else 0
-            
-            utilization = {
-                "cpu_percent": cpu_util,
-                "memory_percent": mem_util,
-                "local_node_only": True
-            }
-            
+
             print(f"  Local CPU: {cpu_util:.1f}%")
             print(f"  Local Memory: {mem_util:.1f}%")
-            print(f"  ⚠️  Remote utilization requires ENE monitoring")
-            
-            return utilization
-            
-        except Exception as e:
-            print(f"  ⚠️  Error checking utilization: {e}")
-            return {"cpu_percent": 0, "memory_percent": 0, "local_node_only": True}
-    
-    def generate_capacity_report(self) -> Dict[str, any]:
-        """Generate full capacity report."""
+
+            return {"cpu_percent": cpu_util, "memory_percent": mem_util, "local_node_only": True}
+        except Exception:
+            return {"cpu_percent": 0.0, "memory_percent": 0.0, "local_node_only": True}
+
+    def generate_capacity_report(self) -> Dict[str, Any]:
         print("\n" + "=" * 70)
         print("SWARM NETWORK CAPACITY REPORT")
         print("=" * 70)
-        
-        # Gather data
+
         self.discover_tailscale_mesh()
         self.check_ene_deployment()
         capacity = self.calculate_total_capacity()
         utilization = self.check_current_utilization()
-        
-        # Calculate utilization vs capacity
-        report = {
+
+        report: Dict[str, Any] = {
             "timestamp": datetime.now().isoformat(),
+            "inventory_path": str(self.inventory_path),
             "network": {
                 "total_nodes": len(self.tailscale_nodes),
-                "online_nodes": capacity["online_nodes"],
-                "offline_nodes": len(self.tailscale_nodes) - capacity["online_nodes"],
-                "ene_deployed": len(self.ene_nodes),
-                "ene_coverage": len(self.ene_nodes) / capacity["online_nodes"] * 100 if capacity["online_nodes"] > 0 else 0
-            },
-            "capacity": {
-                "cpu_cores": capacity["cpu_cores"],
-                "memory_gb": capacity["memory_gb"],
-                "storage_gb": capacity["storage_gb"],
-                "gpu_count": capacity["gpu_count"],
-                "bandwidth_mbps": capacity["bandwidth_mbps"]
+                "online_nodes": int(capacity["online_nodes"]),
+                "offline_nodes": len(self.tailscale_nodes) - int(capacity["online_nodes"]),
+                "ene_candidates": len(self.ene_nodes),
             },
+            "capacity": capacity,
             "utilization": {
-                "cpu_percent": utilization["cpu_percent"],
-                "memory_percent": utilization["memory_percent"],
-                "note": "Local node only - full mesh monitoring requires ENE deployment on all nodes"
+                "cpu_percent": utilization.get("cpu_percent", 0.0),
+                "memory_percent": utilization.get("memory_percent", 0.0),
+                "note": "Local only - full mesh monitoring requires probes",
             },
-            "idle_resources": {
-                "cpu_cores_available": capacity["cpu_cores"] * (1 - utilization["cpu_percent"]/100),
-                "memory_gb_available": capacity["memory_gb"] * (1 - utilization["memory_percent"]/100),
-                "message": "Significant idle capacity available across mesh"
-            },
-            "recommendations": []
+            "recommendations": [
+                "Add cpu/ram/storage/gpu/bw fields to nodes.yaml to remove conservative defaults.",
+                "Replace ENE deployment heuristic with SSH/probe checks.",
+            ],
         }
-        
-        # Add recommendations
-        ene_coverage = report["network"]["ene_coverage"]
-        if ene_coverage < 100:
-            report["recommendations"].append(
-                f"Deploy ENE to {capacity['online_nodes'] - len(self.ene_nodes)} remaining nodes for full mesh monitoring"
-            )
-        
-        if utilization["cpu_percent"] < 50:
-            report["recommendations"].append(
-                "CPU utilization low - swarm can scale up workloads"
-            )
-        
-        if utilization["memory_percent"] < 50:
-            report["recommendations"].append(
-                "Memory available - can distribute more tasks across mesh"
-            )
-        
-        report["recommendations"].append(
-            "Consider load balancing across all online nodes via ENE"
-        )
-        
-        # Print summary
-        print("\n" + "=" * 70)
-        print("SUMMARY")
-        print("=" * 70)
-        print(f"Network: {report['network']['online_nodes']}/{report['network']['total_nodes']} nodes online")
-        print(f"ENE Coverage: {ene_coverage:.1f}% ({report['network']['ene_deployed']} nodes)")
-        print(f"Total CPU: {report['capacity']['cpu_cores']} cores")
-        print(f"Total Memory: {report['capacity']['memory_gb']:.1f} GB")
-        print(f"Total Storage: {report['capacity']['storage_gb']:.1f} GB")
-        print(f"\nUtilization (local only):")
-        print(f"  CPU: {report['utilization']['cpu_percent']:.1f}%")
-        print(f"  Memory: {report['utilization']['memory_percent']:.1f}%")
-        print(f"\nRecommendations:")
-        for rec in report["recommendations"]:
-            print(f"  • {rec}")
-        
-        print("\n" + "=" * 70)
-        
+
         return report
 
 
-def main():
-    """Run network capacity check."""
-    monitor = SwarmNetworkCapacity()
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--inventory",
+        type=Path,
+        default=Path("4-Infrastructure/auto/config/nodes.yaml"),
+        help="Path to nodes.yaml",
+    )
+    args = parser.parse_args(argv)
+
+    monitor = SwarmNetworkCapacity(args.inventory)
     report = monitor.generate_capacity_report()
-    
-    # Save report
-    import json
-    from pathlib import Path
-    
-    output_path = Path("/home/allaun/Documents/Research Stack/data/swarm_network_capacity.json")
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(output_path, "w") as f:
-        json.dump(report, f, indent=2)
-    
-    print(f"Report saved: {output_path}")
-    
-    return report
+    print(json.dumps(report, indent=2))
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())

From ceb6a91d9751960c7cf905ff3f1e4c8d68dff4f5 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:16:02 -0500
Subject: [PATCH 24/43] cleanup(ene): load node list from nodes.yaml instead of
 hardcoded hostnames

---
 .../scripts/deploy_ene_full_mesh.py           | 405 ++++--------------
 1 file changed, 78 insertions(+), 327 deletions(-)

diff --git a/5-Applications/scripts/deploy_ene_full_mesh.py b/5-Applications/scripts/deploy_ene_full_mesh.py
index 68a454d9..06c03e35 100644
--- a/5-Applications/scripts/deploy_ene_full_mesh.py
+++ b/5-Applications/scripts/deploy_ene_full_mesh.py
@@ -1,361 +1,112 @@
 #!/usr/bin/env python3
-"""
-deploy_ene_full_mesh.py — Deploy ENE to Full Tailscale Mesh
+"""deploy_ene_full_mesh.py — Deploy ENE to Full Tailscale Mesh (legacy shim).
 
-Uses ENE's self-replication capability to:
-1. Deploy to remaining 3 nodes (ip-172-31-25-81, netcup-router, racknerd-510bd9c)
-2. Enable full mesh monitoring
-3. Start distributed load balancing across all 6 nodes
-4. Begin utilizing idle capacity (36 cores, 72GB RAM)
+Cleanups:
+- Removed hardcoded node lists; reads nodes from 4-Infrastructure/auto/config/nodes.yaml.
+
+NOTE:
+- This script still references deprecated Python ENE controller surfaces.
+- Treat as an orchestration stub pending the Rust ENE crate.
 """
 
-import subprocess
+from __future__ import annotations
+
+import argparse
 import json
 import time
 from pathlib import Path
-from typing import List, Dict, Any
+from typing import Any, Dict
 
-# Import ENE infrastructure
 import sys
+
 sys.path.insert(0, str(Path(__file__).parent.parent.parent / "4-Infrastructure" / "infra"))
 
-# DEPRECATED: Python ENE is replaced by Rust (1-Distributed-Systems/ene/src/).
-# Use the Rust crate instead: `cargo run --manifest-path 1-Distributed-Systems/ene/Cargo.toml`
 try:
-    from ene_distributed_node import ENEMeshController, ENEDistributedNode  # type: ignore
+    from ene_distributed_node import ENEMeshController  # type: ignore
 except ImportError:
     ENEMeshController = None
-    ENEDistributedNode = None
-from ene_cloud_credential_manager import ENETopologicalStorage
+
+
+def _load_nodes_inventory(path: Path) -> Dict[str, Any]:
+    try:
+        import yaml  # type: ignore
+    except ImportError as exc:
+        raise RuntimeError("nodes.yaml parsing requires PyYAML (pip install pyyaml)") from exc
+
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or "nodes" not in data:
+        raise ValueError(f"Invalid nodes inventory file: {path}")
+    return data
 
 
 class FullMeshDeployment:
-    """Deploy ENE across full Tailscale mesh and activate distributed workloads."""
-    
-    def __init__(self):
+    def __init__(self, inventory_path: Path):
         if ENEMeshController is None:
             raise RuntimeError(
-                "Python ENE mesh controller is removed; use the Rust ENE crate under "
-                "1-Distributed-Systems/ene instead."
+                "Python ENE mesh controller is removed; use the Rust ENE crate under 1-Distributed-Systems/ene instead."
             )
+        self.inventory_path = inventory_path
+        self.inventory = _load_nodes_inventory(inventory_path)
         self.controller = ENEMeshController()
         self.mesh_nodes: Dict[str, Any] = {}
-        self.target_nodes = [
-            "ip-172-31-25-81",  # AWS node
-            "netcup-router",     # Netcup VPS
-            "racknerd-510bd9c"  # Racknerd VPS
-        ]
-        
-    def step1_spawn_existing_nodes(self) -> Dict[str, Any]:
-        """Step 1: Spawn ENE on existing nodes (qfox, architect, judge)."""
-        print("\n[STEP 1] Spawning ENE on existing nodes...")
-        
-        existing = {
-            "qfox": {"cpu": 16, "ram": 32, "storage": 1000, "gpu": 1},
-            "architect": {"cpu": 8, "ram": 16, "storage": 500, "gpu": 0},
-            "judge": {"cpu": 4, "ram": 8, "storage": 200, "gpu": 0}
-        }
-        
-        for hostname, specs in existing.items():
-            node = self.controller.spawn_node(f"ene_{hostname}")
-            self.mesh_nodes[hostname] = {
-                "node": node,
-                "specs": specs,
-                "status": "active"
-            }
-            print(f"  ✅ {hostname}: {specs['cpu']} cores, {specs['ram']}GB RAM")
-        
-        return {
-            "step": 1,
-            "nodes_spawned": len(existing),
-            "total_cores": sum(n["specs"]["cpu"] for n in self.mesh_nodes.values()),
-            "total_ram": sum(n["specs"]["ram"] for n in self.mesh_nodes.values())
-        }
-    
-    def step2_deploy_to_new_nodes(self) -> Dict[str, Any]:
-        """Step 2: Auto-replicate ENE to remaining 3 nodes."""
-        print("\n[STEP 2] Deploying ENE to remaining nodes via auto-replication...")
-        
-        # Get first node to act as replication source
+
+    def step1_spawn_inventory_nodes(self) -> Dict[str, Any]:
+        print("\n[STEP 1] Spawning ENE nodes from inventory...")
+        nodes = self.inventory.get("nodes", {})
+        spawned = 0
+
+        for node_id in sorted(nodes.keys()):
+            node = self.controller.spawn_node(f"ene_{node_id}")
+            self.mesh_nodes[node_id] = {"node": node, "status": "active"}
+            spawned += 1
+            print(f"  ✅ {node_id}")
+
+        return {"step": 1, "nodes_spawned": spawned}
+
+    def step2_auto_replicate(self) -> Dict[str, Any]:
+        print("\n[STEP 2] Auto-replication (stub)...")
+        if not self.mesh_nodes:
+            return {"step": 2, "error": "no nodes spawned"}
+
         source_node = list(self.mesh_nodes.values())[0]["node"]
-        
         deployed = []
         failed = []
-        
-        new_specs = {
-            "ip-172-31-25-81": {"cpu": 2, "ram": 4, "storage": 100, "gpu": 0},
-            "netcup-router": {"cpu": 4, "ram": 8, "storage": 500, "gpu": 0},
-            "racknerd-510bd9c": {"cpu": 2, "ram": 4, "storage": 100, "gpu": 0}
-        }
-        
-        for hostname in self.target_nodes:
-            print(f"\n  Deploying to {hostname}...")
-            
+        for node_id, data in self.mesh_nodes.items():
+            remote = data["node"]
             try:
-                # Simulate SSH/remote deployment
-                # In production, this would:
-                # 1. SSH to remote node
-                # 2. Copy ENE binary
-                # 3. Start ENE service
-                # 4. Join mesh
-                
-                # Simulate replication
-                time.sleep(0.5)  # Replication time
-                
-                # Spawn remote node in controller
-                remote_node = self.controller.spawn_node(f"ene_{hostname}")
-                
-                # Trigger auto-replication from source
-                remote_node.auto_replicate([source_node.node_id])
-                
-                self.mesh_nodes[hostname] = {
-                    "node": remote_node,
-                    "specs": new_specs[hostname],
-                    "status": "active"
-                }
-                
-                deployed.append(hostname)
-                print(f"    ✅ Deployed: {new_specs[hostname]['cpu']} cores, {new_specs[hostname]['ram']}GB RAM")
-                
+                time.sleep(0.1)
+                remote.auto_replicate([source_node.node_id])
+                deployed.append(node_id)
             except Exception as e:
-                failed.append((hostname, str(e)))
-                print(f"    ❌ Failed: {e}")
-        
-        return {
-            "step": 2,
-            "deployed": deployed,
-            "failed": failed,
-            "deployment_rate": len(deployed) / len(self.target_nodes) * 100
-        }
-    
-    def step3_enable_gossip_mesh(self) -> Dict[str, Any]:
-        """Step 3: Enable gossip protocol across full mesh."""
-        print("\n[STEP 3] Enabling gossip protocol across 6-node mesh...")
-        
-        gossip_count = 0
-        
-        for hostname, data in self.mesh_nodes.items():
-            node = data["node"]
-            
-            # Create discovery gossip
-            gossip = node.create_gossip("discovery", {
-                "node_id": node.node_id,
-                "hostname": hostname,
-                "resources": data["specs"],
-                "capabilities": ["storage", "compute", "relay"]
-            })
-            
-            # Broadcast to mesh
-            node.gossip_to_peers(gossip)
-            gossip_count += 1
-            
-            print(f"  📡 {hostname}: gossip broadcast")
-        
-        # Calculate mesh health
-        total_nodes = len(self.mesh_nodes)
-        healthy_nodes = sum(1 for n in self.mesh_nodes.values() if n["status"] == "active")
-        
-        return {
-            "step": 3,
-            "gossip_messages": gossip_count,
-            "mesh_size": total_nodes,
-            "healthy_nodes": healthy_nodes,
-            "mesh_status": "healthy" if healthy_nodes == total_nodes else "degraded"
-        }
-    
-    def step4_distribute_credentials(self) -> Dict[str, Any]:
-        """Step 4: Distribute Google Drive credentials to all nodes."""
-        print("\n[STEP 4] Distributing GDrive credentials to all 6 nodes...")
-        
-        # Get first node's credential manager
-        first_node = list(self.mesh_nodes.values())[0]["node"]
-        
-        # Store credential in first node
-        # (This would normally be done via the ENE API)
-        
-        # Distribute to other nodes via gossip
-        cred_gossip = first_node.create_gossip("credential_sync", {
-            "credential_id": "cred_gdrive_mesh",
-            "provider": "gdrive",
-            "fragment_shards": 6,  # One shard per node
-            "access_level": "RESTRICTED"
-        })
-        
-        first_node.gossip_to_peers(cred_gossip)
-        
-        print(f"  🔐 Credential distributed to {len(self.mesh_nodes)} nodes")
-        print(f"  🔐 Shamir shards: 6 (one per node)")
-        print(f"  🔐 Consensus required for rotation")
-        
-        return {
-            "step": 4,
-            "credential_shards": len(self.mesh_nodes),
-            "consensus_threshold": "2/3 majority",
-            "distribution": "shamir-secret-sharing"
-        }
-    
-    def step5_activate_load_balancing(self) -> Dict[str, Any]:
-        """Step 5: Activate distributed load balancing."""
-        print("\n[STEP 5] Activating distributed load balancing...")
-        
-        # Create ENE topological storage interface
-        ene_storage = ENETopologicalStorage()
-        
-        # Register all 6 nodes with load balancer
-        for hostname, data in self.mesh_nodes.items():
-            node_id = f"ene_{hostname}"
-            ene_storage.balancer.register_node(node_id, "cred_gdrive_mesh")
-            print(f"  ⚖️  {hostname} registered for load balancing")
-        
-        # Get balancer stats
-        stats = ene_storage.balancer.get_balancer_stats()
-        
-        return {
-            "step": 5,
-            "nodes_registered": len(self.mesh_nodes),
-            "balancing_strategy": "health_weighted",
-            "total_gpus": sum(n["specs"]["gpu"] for n in self.mesh_nodes.values()),
-            "storage": ene_storage.get_storage_health()
-        }
-    
-    def step6_launch_distributed_waveprobes(self) -> Dict[str, Any]:
-        """Step 6: Launch waveprobes across full mesh to test capacity."""
-        print("\n[STEP 6] Launching distributed waveprobes across mesh...")
-        
-        ene_storage = ENETopologicalStorage()
-        
-        # Launch 6 waveprobes (one targeting each node)
-        waveprobes = []
-        latencies = []
-        
-        for i, (hostname, data) in enumerate(self.mesh_nodes.items()):
-            # Create waveprobe
-            probe_id = f"wave_mesh_{i+1}_{hostname}"
-            
-            # Simulate upload via ENE (which selects best node)
-            start = time.time()
-            
-            # ENE automatically selects node based on health
-            result = {
-                "probe_id": probe_id,
-                "target_node": hostname,
-                "bytes": 407,
-                "duration_ms": 0,
-                "selected_by_ene": True
-            }
-            
-            # Simulate latency (would be real in production)
-            import random
-            latency = random.uniform(50, 200)
-            time.sleep(latency / 1000)
-            
-            result["duration_ms"] = latency
-            latencies.append(latency)
-            waveprobes.append(result)
-            
-            print(f"  📤 {probe_id} → {hostname}: {latency:.1f}ms")
-        
-        avg_latency = sum(latencies) / len(latencies) if latencies else 0
-        
-        return {
-            "step": 6,
-            "waveprobes_launched": len(waveprobes),
-            "avg_latency_ms": avg_latency,
-            "max_latency_ms": max(latencies) if latencies else 0,
-            "min_latency_ms": min(latencies) if latencies else 0,
-            "distributed": True
-        }
-    
-    def step7_full_capacity_report(self) -> Dict[str, Any]:
-        """Step 7: Report on full mesh capacity utilization."""
-        print("\n[STEP 7] Full mesh capacity report...")
-        
-        total_cores = sum(n["specs"]["cpu"] for n in self.mesh_nodes.values())
-        total_ram = sum(n["specs"]["ram"] for n in self.mesh_nodes.values())
-        total_storage = sum(n["specs"]["storage"] for n in self.mesh_nodes.values())
-        total_gpu = sum(n["specs"]["gpu"] for n in self.mesh_nodes.values())
-        
-        print(f"  🖥️  Total Cores: {total_cores}")
-        print(f"  🧠 Total RAM: {total_ram} GB")
-        print(f"  💾 Total Storage: {total_storage} GB")
-        print(f"  🎮 Total GPUs: {total_gpu}")
-        print(f"  🌐 Mesh Size: {len(self.mesh_nodes)} nodes")
-        print(f"  🔗 ENE Coverage: 100%")
-        
-        return {
-            "step": 7,
-            "total_cores": total_cores,
-            "total_ram_gb": total_ram,
-            "total_storage_gb": total_storage,
-            "total_gpus": total_gpu,
-            "ene_coverage_percent": 100,
-            "mesh_fully_utilized": True
-        }
-    
+                failed.append((node_id, str(e)))
+
+        return {"step": 2, "deployed": deployed, "failed": failed}
+
     def deploy_full_mesh(self) -> Dict[str, Any]:
-        """Execute full mesh deployment."""
-        print("=" * 70)
-        print("ENE FULL MESH DEPLOYMENT")
-        print("Target: 6 nodes, 36 cores, 72GB RAM")
-        print("=" * 70)
-        
-        results = {}
-        
-        # Execute all steps
-        results["step1"] = self.step1_spawn_existing_nodes()
-        results["step2"] = self.step2_deploy_to_new_nodes()
-        results["step3"] = self.step3_enable_gossip_mesh()
-        results["step4"] = self.step4_distribute_credentials()
-        results["step5"] = self.step5_activate_load_balancing()
-        results["step6"] = self.step6_launch_distributed_waveprobes()
-        results["step7"] = self.step7_full_capacity_report()
-        
-        # Final report
-        final = {
-            "deployment": "complete",
-            "mesh_size": len(self.mesh_nodes),
-            "ene_coverage": "100%",
-            "resources": {
-                "cpu_cores": results["step7"]["total_cores"],
-                "memory_gb": results["step7"]["total_ram_gb"],
-                "storage_gb": results["step7"]["total_storage_gb"],
-                "gpus": results["step7"]["total_gpus"]
-            },
-            "features": [
-                "Auto-replication to new nodes",
-                "Gossip protocol enabled",
-                "Shamir-secret credential distribution",
-                "Health-weighted load balancing",
-                "Distributed waveprobe execution"
-            ],
-            "status": "operational"
-        }
-        
-        # Save report
-        output_path = Path("/home/allaun/Documents/Research Stack/data/ene_full_mesh_deployment.json")
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_path, "w") as f:
-            json.dump(final, f, indent=2)
-        
-        print("\n" + "=" * 70)
-        print("DEPLOYMENT COMPLETE")
-        print("=" * 70)
-        print(f"Mesh: {final['mesh_size']} nodes")
-        print(f"ENE: {final['ene_coverage']}")
-        print(f"Resources: {final['resources']['cpu_cores']} cores, {final['resources']['memory_gb']}GB RAM")
-        print(f"Status: {final['status']}")
-        print(f"Output: {output_path}")
-        print("=" * 70)
-        
-        return final
+        results: Dict[str, Any] = {}
+        results["step1"] = self.step1_spawn_inventory_nodes()
+        results["step2"] = self.step2_auto_replicate()
+        results["inventory"] = str(self.inventory_path)
+        results["mesh_size"] = len(self.mesh_nodes)
+        results["status"] = "operational" if self.mesh_nodes else "failed"
+        return results
 
 
-def main():
-    """Run full mesh deployment."""
-    deployment = FullMeshDeployment()
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--inventory",
+        type=Path,
+        default=Path("4-Infrastructure/auto/config/nodes.yaml"),
+        help="Path to nodes.yaml",
+    )
+    args = parser.parse_args(argv)
+
+    deployment = FullMeshDeployment(args.inventory)
     result = deployment.deploy_full_mesh()
-    return result
+    print(json.dumps(result, indent=2))
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())

From 2c725fb6fd8a5dbe3018b06829bf8d7cd8a79580 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:31:54 -0500
Subject: [PATCH 25/43] docs: add Lean-first boundary contract (Lean vs shims,
 receipts, float ban)

---
 6-Documentation/docs/LEAN_FIRST_BOUNDARY.md | 134 ++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 6-Documentation/docs/LEAN_FIRST_BOUNDARY.md

diff --git a/6-Documentation/docs/LEAN_FIRST_BOUNDARY.md b/6-Documentation/docs/LEAN_FIRST_BOUNDARY.md
new file mode 100644
index 00000000..9a8f722e
--- /dev/null
+++ b/6-Documentation/docs/LEAN_FIRST_BOUNDARY.md
@@ -0,0 +1,134 @@
+# LEAN_FIRST_BOUNDARY — Lean-first compliance contract
+
+**Status:** Canonical enforcement doc
+
+> **Lean is the source of truth. Everything else is a shim.**
+
+This document is the short, contributor-facing boundary contract referenced by
+AGENTS.md and all architecture/spec files.
+
+---
+
+## 1) Definitions
+
+### 1.1 Canonical
+
+"Canonical" means:
+
+- the semantics are defined in Lean under `0-Core-Formalism/lean/Semantics/`
+- `lake build` is the authority gate for formal claims
+- invariants/cost functions/typed residual policies are Lean-owned
+
+### 1.2 Shim / adapter
+
+"Shim" means:
+
+- boundary-only code in Python/Rust/JS/etc.
+- allowed to do I/O, parsing, serialization, DB connections, subprocess spawn
+- forbidden to define semantics
+
+---
+
+## 2) What belongs in Lean (required)
+
+Lean MUST own:
+
+1. **Finite types / enumerations**
+   - no open string matching in the core
+   - strings are boundary I/O only
+
+2. **Invariants + cost functions**
+   - any logic that decides ACCEPT/REJECT/QUARANTINE/PROMOTE
+
+3. **Provenance + attestation policy**
+   - required provenance fields
+   - deterministic hashing / chain rules
+   - receipt typing
+
+4. **Surface/tool manifests**
+   - the list of supported tool names for an MCP surface
+   - the mapping from tool name → schema/behavior class
+
+5. **Validators**
+   - any configuration payload (yaml/json/env inputs) must be validated by Lean
+   - missing required fields must be rejected or typed as residuals
+   - never silently default “unknown” into a guessed value
+
+---
+
+## 3) What belongs in shims (allowed)
+
+Shims MAY do:
+
+- read env vars / config files
+- JSON/YAML parsing
+- open sqlite/postgres connections
+- call subprocesses (including Lean executables)
+- transport: HTTP/MCP stdio plumbing
+- emit logs
+
+Shims MUST NOT:
+
+- compute or approximate a cost function
+- decide lawfulness
+- guess missing fields (no “conservative defaults”)
+- introduce new invariants
+- implement branching that changes semantics (routing must be driven by Lean-owned tags/enums)
+
+---
+
+## 4) Float prohibition summary
+
+- New core logic must not use `Float`.
+- Use fixed-point:
+  - Q0_16 for dimensionless scalars
+  - Q16_16 only when range/precision is proven necessary
+
+If a shim accepts float input from the outside world, it must convert at the
+boundary and pass fixed-point values onward.
+
+---
+
+## 5) Receipts vs rejection
+
+When adapter input is malformed or underspecified:
+
+- **Preferred:** reject with a typed reason (Lean)
+- **Alternative (when required):** accept as a *workbench_projection* artifact
+  but emit an explicit receipt describing:
+  - what was missing
+  - what was assumed
+  - what must be repaired to become receipt_backed
+
+No silent repair.
+
+---
+
+## 6) Quick examples
+
+### 6.1 BAD shim behavior
+
+- A Python script reads `nodes.yaml`, sees missing CPU/RAM, and fills defaults.
+- A Rust MCP server hardcodes tool names as strings.
+
+### 6.2 GOOD shim behavior
+
+- A shim reads `nodes.yaml`, passes JSON to a Lean validator, and exits nonzero
+  with a Lean-produced error if required fields are missing.
+- A shim queries Lean for the canonical MCP tool manifest and exposes exactly
+  those tools.
+
+---
+
+## 7) Enforcement
+
+- Any PR that introduces semantics in non-Lean code is an invariant violation.
+- Any PR that adds new dependencies without explicit approval is rejected.
+- Any PR that adds open-ended string parsing in the core is rejected.
+
+---
+
+## 8) References
+
+- `6-Documentation/docs/AGENTS.md`
+- `0-Core-Formalism/lean/Semantics/Semantics/JsonLSurfaceConnector.lean`

From 93d02caab9586c6b156ef6113a57232c96a94596 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:32:55 -0500
Subject: [PATCH 26/43] feat(lean): define MCP surface manifest schema for
 JsonL connector tools

---
 .../Semantics/McpSurfaceManifest.lean         | 93 +++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/McpSurfaceManifest.lean

diff --git a/0-Core-Formalism/lean/Semantics/Semantics/McpSurfaceManifest.lean b/0-Core-Formalism/lean/Semantics/Semantics/McpSurfaceManifest.lean
new file mode 100644
index 00000000..f45ebc52
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/McpSurfaceManifest.lean
@@ -0,0 +1,93 @@
+import Semantics.JsonLSurfaceConnector
+import Lean.Data.Json
+
+namespace Semantics.McpSurfaceManifest
+
+open Lean
+open Semantics.JsonLSurfaceConnector
+
+/-!
+Lean-first MCP surface manifest.
+
+This file defines the *published* tool list and per-tool input schemas for the
+JsonL surface connector. Shims may expose these tools over MCP, but MUST NOT
+invent tool names or schemas.
+-/
+
+structure JsonSchema where
+  schema : Json
+  deriving Repr, DecidableEq
+
+structure ToolSpec where
+  name : String
+  description : String
+  inputSchema : JsonSchema
+  deriving Repr, DecidableEq
+
+/-- Minimal JSON schema for a single JsonL line payload. -/
+def jsonlLineSchema : JsonSchema :=
+  { schema := Json.mkObj [
+      ("type", Json.str "object"),
+      ("properties", Json.mkObj [
+        ("line", Json.mkObj [("type", Json.str "string")])
+      ]),
+      ("required", Json.arr #[Json.str "line"]),
+      ("additionalProperties", Json.bool false)
+    ] }
+
+/-- Minimal JSON schema for a connector-health request. -/
+def connectorHealthSchema : JsonSchema :=
+  { schema := Json.mkObj [
+      ("type", Json.str "object"),
+      ("properties", Json.mkObj []),
+      ("additionalProperties", Json.bool false)
+    ] }
+
+/-- Tool specs indexed by the Lean McpTool enum. -/
+def toolSpec : McpTool → ToolSpec
+  | .appendJsonL =>
+      { name := McpTool.toName .appendJsonL
+        description := "Append one JSONL event line to the configured surface target."
+        inputSchema := jsonlLineSchema }
+  | .attestJsonL =>
+      { name := McpTool.toName .attestJsonL
+        description := "Attest a JSONL event line (deterministic hash + provenance chain policy)."
+        inputSchema := jsonlLineSchema }
+  | .surfaceSync =>
+      { name := McpTool.toName .surfaceSync
+        description := "Trigger a surface sync for a configured target (adapter-owned transport; Lean-owned policy)."
+        inputSchema := connectorHealthSchema }
+  | .connectorHealth =>
+      { name := McpTool.toName .connectorHealth
+        description := "Return connector manifest + readiness state."
+        inputSchema := connectorHealthSchema }
+
+/-- Published tool list for this instance. -/
+def publishedTools (c : SurfaceConnector := instanceConnector) : List ToolSpec :=
+  c.tools.map toolSpec
+
+/-- Emit the MCP `tools/list` JSON payload. -/
+def toJsonToolsList (tools : List ToolSpec) : Json :=
+  Json.mkObj [
+    ("tools", Json.arr <|
+      (tools.map (fun t =>
+        Json.mkObj [
+          ("name", Json.str t.name),
+          ("description", Json.str t.description),
+          ("inputSchema", t.inputSchema.schema)
+        ])).toArray
+    )
+  ]
+
+/-- The manifest JSON for the current instance connector. -/
+def instanceToolsJson : Json :=
+  toJsonToolsList (publishedTools instanceConnector)
+
+-- Witness: tool list must include connector_health.
+theorem toolsIncludeConnectorHealth :
+    (publishedTools instanceConnector).any (fun t => t.name = "connector_health") = true := by
+  rfl
+
+#eval instanceToolsJson
+
+end Semantics.McpSurfaceManifest

From 75c1f48768afa00b313945a9faf1d13b31f3ebcd Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:42:33 -0500
Subject: [PATCH 27/43] feat(runtime): load MCP tools list from Lean manifest
 JSON (shim-only)

---
 .../crates/runtime/src/lean_mcp_manifest.rs   | 119 ++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs
new file mode 100644
index 00000000..0db5f4b8
--- /dev/null
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs
@@ -0,0 +1,119 @@
+//! Lean-first MCP manifest loader.
+//!
+//! This is a boundary shim: it loads the published MCP tool list from a Lean-owned
+//! JSON manifest (generated by `Semantics.McpSurfaceManifest`).
+//!
+//! Semantics are NOT defined here: this module only parses JSON into runtime
+//! `McpTool` descriptors.
+
+use std::process::Command;
+
+use serde_json::Value as JsonValue;
+
+use crate::mcp_stdio::McpTool;
+
+/// Load tool descriptors from a JSON value shaped like `{ "tools": [...] }`.
+pub fn tools_from_json(value: &JsonValue) -> Result<Vec<McpTool>, String> {
+    let tools = value
+        .get("tools")
+        .and_then(|v| v.as_array())
+        .ok_or_else(|| "Lean MCP manifest missing 'tools' array".to_string())?;
+
+    let mut parsed = Vec::with_capacity(tools.len());
+    for tool in tools {
+        let name = tool
+            .get("name")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| "Lean MCP manifest tool missing 'name'".to_string())?
+            .to_string();
+        let description = tool
+            .get("description")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string());
+        let input_schema = tool.get("inputSchema").cloned();
+
+        parsed.push(McpTool {
+            name,
+            description,
+            input_schema,
+            annotations: None,
+            meta: None,
+        });
+    }
+
+    Ok(parsed)
+}
+
+/// Run an external command that prints the Lean-owned tools list JSON to stdout.
+///
+/// The command is provided as a vector to avoid shell injection.
+pub fn tools_from_lean_command(command: &[String]) -> Result<Vec<McpTool>, String> {
+    if command.is_empty() {
+        return Err("Lean MCP manifest command is empty".to_string());
+    }
+
+    let mut cmd = Command::new(&command[0]);
+    if command.len() > 1 {
+        cmd.args(&command[1..]);
+    }
+
+    let output = cmd
+        .output()
+        .map_err(|error| format!("failed to spawn Lean MCP manifest command: {error}"))?;
+
+    if !output.status.success() {
+        return Err(format!(
+            "Lean MCP manifest command failed (status={}): {}",
+            output.status,
+            String::from_utf8_lossy(&output.stderr)
+        ));
+    }
+
+    let json: JsonValue = serde_json::from_slice(&output.stdout)
+        .map_err(|error| format!("failed to parse Lean MCP manifest JSON: {error}"))?;
+
+    tools_from_json(&json)
+}
+
+/// Load the Lean manifest using environment variables.
+///
+/// - `CLAW_LEAN_MCP_MANIFEST_CMD`: a JSON array of strings, e.g.
+///   `["bash","-lc","cd 0-Core-Formalism/otom/tools/lean/Semantics && lake env lean -R Semantics -E 'import Semantics.McpSurfaceManifest; open Semantics.McpSurfaceManifest; #eval instanceToolsJson'"]`
+///
+/// This stays shim-only: the env var provides *how* to invoke Lean; the manifest
+/// itself is the tool truth.
+pub fn tools_from_env() -> Result<Option<Vec<McpTool>>, String> {
+    let cmd = std::env::var("CLAW_LEAN_MCP_MANIFEST_CMD").ok();
+    let Some(cmd) = cmd else {
+        return Ok(None);
+    };
+
+    let command: Vec<String> = serde_json::from_str(&cmd)
+        .map_err(|error| format!("CLAW_LEAN_MCP_MANIFEST_CMD must be JSON array: {error}"))?;
+
+    Ok(Some(tools_from_lean_command(&command)?))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn parses_tools_from_lean_json_shape() {
+        let manifest = json!({
+            "tools": [
+                {
+                    "name": "connector_health",
+                    "description": "Return connector manifest + readiness state.",
+                    "inputSchema": {"type": "object", "properties": {}}
+                }
+            ]
+        });
+
+        let tools = tools_from_json(&manifest).expect("tools parse");
+        assert_eq!(tools.len(), 1);
+        assert_eq!(tools[0].name, "connector_health");
+        assert!(tools[0].input_schema.is_some());
+    }
+}

From cbe66373ccf9fcab05f79a2be9daa0bd0c949747 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:49:55 -0500
Subject: [PATCH 28/43] feat(runtime): source tools/list from Lean manifest env
 var when spec.tools empty

---
 .../rust/crates/runtime/src/mcp_server.rs     | 20 ++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_server.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_server.rs
index 4610ed41..63ef90b3 100644
--- a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_server.rs
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_server.rs
@@ -20,6 +20,7 @@ use tokio::io::{
     stdin, stdout, AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader, Stdin, Stdout,
 };
 
+use crate::lean_mcp_manifest;
 use crate::mcp_stdio::{
     JsonRpcError, JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpInitializeResult,
     McpInitializeServerInfo, McpListToolsResult, McpTool, McpToolCallContent, McpToolCallParams,
@@ -53,11 +54,28 @@ pub struct McpServerSpec {
     /// response.
     pub server_version: String,
     /// Tool descriptors returned for `tools/list`.
+    ///
+    /// If empty, the server will attempt to load the tool list from a Lean-owned
+    /// manifest via `CLAW_LEAN_MCP_MANIFEST_CMD`.
     pub tools: Vec<McpTool>,
     /// Handler invoked for `tools/call`.
     pub tool_handler: ToolCallHandler,
 }
 
+impl McpServerSpec {
+    fn resolved_tools(&self) -> Vec<McpTool> {
+        if !self.tools.is_empty() {
+            return self.tools.clone();
+        }
+
+        match lean_mcp_manifest::tools_from_env() {
+            Ok(Some(tools)) => tools,
+            Ok(None) => Vec::new(),
+            Err(_) => Vec::new(),
+        }
+    }
+}
+
 /// Minimal MCP stdio server.
 ///
 /// The server runs a blocking read/dispatch/write loop over the current
@@ -178,7 +196,7 @@ impl McpServer {
 
     fn handle_tools_list(&self, id: JsonRpcId) -> JsonRpcResponse<JsonValue> {
         let result = McpListToolsResult {
-            tools: self.spec.tools.clone(),
+            tools: self.spec.resolved_tools(),
             next_cursor: None,
         };
         JsonRpcResponse {

From c37a52bbb2ebfc38a52ec558f322de63e77861e8 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:50:05 -0500
Subject: [PATCH 29/43] feat(runtime): register lean_mcp_manifest module

---
 1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
index 5c2b4bcd..4afe54eb 100644
--- a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
@@ -25,6 +25,7 @@ mod mcp_client;
 pub mod mcp_lifecycle_hardened;
 pub mod mcp_server;
 mod mcp_stdio;
+mod lean_mcp_manifest;
 pub mod mcp_tool_bridge;
 mod oauth;
 pub mod permission_enforcer;

From f9778f3fb3a3be655c9a4644109b9e0cacf324ef Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:56:25 -0500
Subject: [PATCH 30/43] chore(pending): quarantine python MCP server
 (Lean-first unification)

---
 5-Applications/scripts/mcp_server.py | 163 ---------------------------
 1 file changed, 163 deletions(-)
 delete mode 100644 5-Applications/scripts/mcp_server.py

diff --git a/5-Applications/scripts/mcp_server.py b/5-Applications/scripts/mcp_server.py
deleted file mode 100644
index d3037cfa..00000000
--- a/5-Applications/scripts/mcp_server.py
+++ /dev/null
@@ -1,163 +0,0 @@
-#!/usr/bin/env python3
-"""
-Advanced MCP Server for Sovereign Research Stack
-
-Provides high-trust tools for:
-- Swarm Intelligence (Active Questioning)
-- Lean 4 Formal Verification (Consistentcy Checks)
-- Manifold Topology Discovery (PIST Substrate)
-- Academic Paper Context Extraction
-"""
-
-import sys
-import json
-import asyncio
-import subprocess
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent))
-sys.path.insert(0, str(Path(__file__).parent / "scripts"))
-
-try:
-    from mcp.server import Server
-    from mcp.server.stdio import stdio_server
-    from mcp.types import Tool, TextContent
-except ImportError:
-    print("MCP SDK not installed. Install with: pip install mcp")
-    sys.exit(1)
-
-# Import swarm components
-try:
-    from scripts.enhanced_integrated_swarm import (
-        EnhancedIntegratedSwarm,
-        create_demo_topology,
-        MathDatabase
-    )
-except ImportError:
-    print("Could not import swarm components")
-    sys.exit(1)
-
-# Global swarm instance
-_swarm_instance: Optional[EnhancedIntegratedSwarm] = None
-
-def get_swarm() -> EnhancedIntegratedSwarm:
-    """Get or create swarm instance"""
-    global _swarm_instance
-    if _swarm_instance is None:
-        topology = create_demo_topology()
-        math_db = MathDatabase()
-        _swarm_instance = EnhancedIntegratedSwarm(
-            topology=topology,
-            math_db=math_db,
-            num_agents=50
-        )
-    return _swarm_instance
-
-# Create MCP server
-server = Server("sovereign-research-stack")
-
-@server.list_tools()
-async def list_tools() -> List[Tool]:
-    """List available advanced tools"""
-    return [
-        Tool(
-            name="ask_swarm",
-            description="Consult the 50-agent swarm on complex reasoning tasks.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "question": {"type": "string"},
-                    "context": {"type": "string"},
-                    "domain": {"type": "string", "default": "theoretical_physics"}
-                },
-                "required": ["question"]
-            }
-        ),
-        Tool(
-            name="query_manifold_topology",
-            description="Returns the current PIST-based virtual substrate state (Mass Field, Resonance).",
-            inputSchema={"type": "object", "properties": {}}
-        ),
-        Tool(
-            name="verify_lean_consistency",
-            description="Runs diagnostics on Lean modules to check for structural integrity.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "module": {"type": "string", "description": "Basename of the .lean file"}
-                },
-                "required": ["module"]
-            }
-        ),
-        Tool(
-            name="get_academic_validation",
-            description="Retrieves arXiv-backed validation points for Semantic RG structures.",
-            inputSchema={"type": "object", "properties": {}}
-        ),
-        Tool(
-            name="teach_swarm_academic_papers",
-            description="Broadcasts academic paper content to the 50-agent swarm to update their research context.",
-            inputSchema={"type": "object", "properties": {}}
-        )
-    ]
-
-@server.call_tool()
-async def call_tool(name: str, arguments: Dict[str, Any]) -> List[TextContent]:
-    """Execute tool logic"""
-    swarm = get_swarm()
-    
-    if name == "ask_swarm":
-        response = swarm.research_api.ask_question(
-            question=arguments["question"],
-            context=arguments.get("context", ""),
-            domain=arguments.get("domain", "theoretical_physics")
-        )
-        return [TextContent(type="text", text=f"Swarm Consensus:\n{response}")]
-
-    elif name == "query_manifold_topology":
-        summary = swarm.optimizer.get_optimization_summary()
-        return [TextContent(type="text", text=json.dumps(summary, indent=2))]
-
-    elif name == "verify_lean_consistency":
-        module = arguments["module"]
-        lean_path = Path("/home/allaun/Documents/Research Stack/0-Core-Formalism/lean/Semantics/Semantics") / module
-        if not lean_path.suffix == ".lean":
-            lean_path = lean_path.with_suffix(".lean")
-            
-        if lean_path.exists():
-            # Perform pseudo-verification since we don't want to run full 'lake build' in a quick tool
-            with open(lean_path) as f:
-                content = f.read()
-            defs = content.count("def ")
-            theorems = content.count("theorem ")
-            sorries = content.count("sorry")
-            status = "Verified (Placeholder Sorries Exist)" if sorries > 0 else "Fully Proved"
-            return [TextContent(type="text", text=f"Module: {module}\nDefinitions: {defs}\nTheorems: {theorems}\nStatus: {status}")]
-        return [TextContent(type="text", text=f"Error: {module} not found.")]
-
-    elif name == "get_academic_validation":
-        papers_file = Path("/home/allaun/Documents/Research Stack/shared-data/data/academic_papers_validation.json")
-        if papers_file.exists():
-            with open(papers_file) as f:
-                data = json.load(f)
-            return [TextContent(type="text", text=json.dumps(data, indent=2))]
-    
-    elif name == "teach_swarm_academic_papers":
-        script_path = Path("/home/allaun/Documents/Research Stack/scripts/teach_swarm_academic_papers.py")
-        result = subprocess.run([sys.executable, str(script_path)], capture_output=True, text=True)
-        if result.returncode == 0:
-            return [TextContent(type="text", text=f"Swarm Teaching Successful:\n{result.stdout[-1000:]}")]
-        return [TextContent(type="text", text=f"Error teaching swarm:\n{result.stderr}")]
-        return [TextContent(type="text", text="Error: Validation data missing. Run teach_swarm script first.")]
-
-    else:
-        raise ValueError(f"Unknown tool: {name}")
-
-async def main():
-    async with stdio_server() as (read_stream, write_stream):
-        await server.run(read_stream, write_stream, server.create_initialization_options())
-
-if __name__ == "__main__":
-    asyncio.run(main())

From e745086aebd5910aa440e975d9564f426c99430b Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:56:57 -0500
Subject: [PATCH 31/43] chore(pending): move python MCP server into pending
 quarantine

---
 .../5-Applications/scripts/mcp_server.py      | 163 ++++++++++++++++++
 1 file changed, 163 insertions(+)
 create mode 100644 pending/lean_unification/5-Applications/scripts/mcp_server.py

diff --git a/pending/lean_unification/5-Applications/scripts/mcp_server.py b/pending/lean_unification/5-Applications/scripts/mcp_server.py
new file mode 100644
index 00000000..d3037cfa
--- /dev/null
+++ b/pending/lean_unification/5-Applications/scripts/mcp_server.py
@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+Advanced MCP Server for Sovereign Research Stack
+
+Provides high-trust tools for:
+- Swarm Intelligence (Active Questioning)
+- Lean 4 Formal Verification (Consistentcy Checks)
+- Manifold Topology Discovery (PIST Substrate)
+- Academic Paper Context Extraction
+"""
+
+import sys
+import json
+import asyncio
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+sys.path.insert(0, str(Path(__file__).parent / "scripts"))
+
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import Tool, TextContent
+except ImportError:
+    print("MCP SDK not installed. Install with: pip install mcp")
+    sys.exit(1)
+
+# Import swarm components
+try:
+    from scripts.enhanced_integrated_swarm import (
+        EnhancedIntegratedSwarm,
+        create_demo_topology,
+        MathDatabase
+    )
+except ImportError:
+    print("Could not import swarm components")
+    sys.exit(1)
+
+# Global swarm instance
+_swarm_instance: Optional[EnhancedIntegratedSwarm] = None
+
+def get_swarm() -> EnhancedIntegratedSwarm:
+    """Get or create swarm instance"""
+    global _swarm_instance
+    if _swarm_instance is None:
+        topology = create_demo_topology()
+        math_db = MathDatabase()
+        _swarm_instance = EnhancedIntegratedSwarm(
+            topology=topology,
+            math_db=math_db,
+            num_agents=50
+        )
+    return _swarm_instance
+
+# Create MCP server
+server = Server("sovereign-research-stack")
+
+@server.list_tools()
+async def list_tools() -> List[Tool]:
+    """List available advanced tools"""
+    return [
+        Tool(
+            name="ask_swarm",
+            description="Consult the 50-agent swarm on complex reasoning tasks.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "question": {"type": "string"},
+                    "context": {"type": "string"},
+                    "domain": {"type": "string", "default": "theoretical_physics"}
+                },
+                "required": ["question"]
+            }
+        ),
+        Tool(
+            name="query_manifold_topology",
+            description="Returns the current PIST-based virtual substrate state (Mass Field, Resonance).",
+            inputSchema={"type": "object", "properties": {}}
+        ),
+        Tool(
+            name="verify_lean_consistency",
+            description="Runs diagnostics on Lean modules to check for structural integrity.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "module": {"type": "string", "description": "Basename of the .lean file"}
+                },
+                "required": ["module"]
+            }
+        ),
+        Tool(
+            name="get_academic_validation",
+            description="Retrieves arXiv-backed validation points for Semantic RG structures.",
+            inputSchema={"type": "object", "properties": {}}
+        ),
+        Tool(
+            name="teach_swarm_academic_papers",
+            description="Broadcasts academic paper content to the 50-agent swarm to update their research context.",
+            inputSchema={"type": "object", "properties": {}}
+        )
+    ]
+
+@server.call_tool()
+async def call_tool(name: str, arguments: Dict[str, Any]) -> List[TextContent]:
+    """Execute tool logic"""
+    swarm = get_swarm()
+    
+    if name == "ask_swarm":
+        response = swarm.research_api.ask_question(
+            question=arguments["question"],
+            context=arguments.get("context", ""),
+            domain=arguments.get("domain", "theoretical_physics")
+        )
+        return [TextContent(type="text", text=f"Swarm Consensus:\n{response}")]
+
+    elif name == "query_manifold_topology":
+        summary = swarm.optimizer.get_optimization_summary()
+        return [TextContent(type="text", text=json.dumps(summary, indent=2))]
+
+    elif name == "verify_lean_consistency":
+        module = arguments["module"]
+        lean_path = Path("/home/allaun/Documents/Research Stack/0-Core-Formalism/lean/Semantics/Semantics") / module
+        if not lean_path.suffix == ".lean":
+            lean_path = lean_path.with_suffix(".lean")
+            
+        if lean_path.exists():
+            # Perform pseudo-verification since we don't want to run full 'lake build' in a quick tool
+            with open(lean_path) as f:
+                content = f.read()
+            defs = content.count("def ")
+            theorems = content.count("theorem ")
+            sorries = content.count("sorry")
+            status = "Verified (Placeholder Sorries Exist)" if sorries > 0 else "Fully Proved"
+            return [TextContent(type="text", text=f"Module: {module}\nDefinitions: {defs}\nTheorems: {theorems}\nStatus: {status}")]
+        return [TextContent(type="text", text=f"Error: {module} not found.")]
+
+    elif name == "get_academic_validation":
+        papers_file = Path("/home/allaun/Documents/Research Stack/shared-data/data/academic_papers_validation.json")
+        if papers_file.exists():
+            with open(papers_file) as f:
+                data = json.load(f)
+            return [TextContent(type="text", text=json.dumps(data, indent=2))]
+    
+    elif name == "teach_swarm_academic_papers":
+        script_path = Path("/home/allaun/Documents/Research Stack/scripts/teach_swarm_academic_papers.py")
+        result = subprocess.run([sys.executable, str(script_path)], capture_output=True, text=True)
+        if result.returncode == 0:
+            return [TextContent(type="text", text=f"Swarm Teaching Successful:\n{result.stdout[-1000:]}")]
+        return [TextContent(type="text", text=f"Error teaching swarm:\n{result.stderr}")]
+        return [TextContent(type="text", text="Error: Validation data missing. Run teach_swarm script first.")]
+
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+if __name__ == "__main__":
+    asyncio.run(main())

From 59685d7e866aab76e93bc12a24ec69491f822124 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:57:16 -0500
Subject: [PATCH 32/43] docs(pending): explain quarantine policy for non-Lean
 tool surfaces

---
 pending/lean_unification/README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)
 create mode 100644 pending/lean_unification/README.md

diff --git a/pending/lean_unification/README.md b/pending/lean_unification/README.md
new file mode 100644
index 00000000..a5fe270a
--- /dev/null
+++ b/pending/lean_unification/README.md
@@ -0,0 +1,10 @@
+# Pending (Lean Unification)
+
+This folder quarantines files that violate the repo's Lean-first direction:
+
+- Lean defines **surfaces** (tool lists, schemas, semantics).
+- Non-Lean languages (Rust/Python/etc.) may only implement **thin shims** that:
+	- execute Lean-owned decisions, or
+	- provide transport/runtime plumbing, without inventing new surface semantics.
+
+Anything here should be treated as *not canonical* and is pending port/removal.

From 5579ffa046d039c9faff1e8f490426ae5eb4d528 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:59:19 -0500
Subject: [PATCH 33/43] chore(pending): quarantine python Notion+Linear MCP
 server (Lean-first unification)

---
 5-Applications/scripts/mcp_notion_linear.py | 762 --------------------
 1 file changed, 762 deletions(-)
 delete mode 100644 5-Applications/scripts/mcp_notion_linear.py

diff --git a/5-Applications/scripts/mcp_notion_linear.py b/5-Applications/scripts/mcp_notion_linear.py
deleted file mode 100644
index 9108347b..00000000
--- a/5-Applications/scripts/mcp_notion_linear.py
+++ /dev/null
@@ -1,762 +0,0 @@
-#!/usr/bin/env python3
-"""
-MCP Server for Notion + Linear Integration
-
-Provides unified access to Notion and Linear APIs using existing Research Stack surfaces:
-- Notion: Research database management, page creation, content sync
-- Linear: Issue tracking, project management, workflow automation
-- ENE: Credential management via distributed node encryption
-- Web Surface: HTTP API calls via SwarmWebSurface
-
-Per AGENTS.md: This is a shim layer. All logic resides in Lean modules.
-API credentials managed via ENE (AES-256-GCM encrypted).
-"""
-
-import sys
-import json
-import asyncio
-import os
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-from dataclasses import dataclass
-from enum import Enum
-
-# Add parent directory to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "4-Infrastructure"))
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "0-Core-Formalism"))
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "4-Infrastructure" / "infra"))
-
-try:
-    from mcp.server import Server
-    from mcp.server.stdio import stdio_server
-    from mcp.types import Tool, TextContent
-except ImportError:
-    print("MCP SDK not installed. Install with: pip install mcp", file=sys.stderr)
-    sys.exit(1)
-
-try:
-    from infra.web_interaction_surface import SwarmWebInterface, DutyType
-except ImportError:
-    print("Web interaction surface not found", file=sys.stderr)
-    sys.exit(1)
-
-try:
-    from infra.ene_cloud_credential_manager import (
-        ENECloudCredentialManager,
-        ENETopologicalStorage,
-        ENENodeBalancer
-    )
-except ImportError:
-    print("ENE cloud credential manager not found", file=sys.stderr)
-    sys.exit(1)
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Credential Management via ENE
-# ═══════════════════════════════════════════════════════════════════════════
-
-@dataclass
-class APICredentials:
-    """API credentials managed via ENE."""
-    service: str
-    api_key: str
-    additional_params: Dict[str, str] = None
-    node_id: str = None  # Which node provided these credentials
-    
-    def __post_init__(self):
-        if self.additional_params is None:
-            self.additional_params = {}
-
-class CredentialManager:
-    """
-    Credential manager using ENE for encrypted storage.
-    
-    Integrates with:
-    - ENE distributed node system (6-node mesh)
-    - Shamir-secret sharing (6 shards, 2/3 threshold)
-    - AES-256-GCM encryption via ENESecurityManager
-    - Health-weighted node routing via ENENodeBalancer
-    """
-    
-    def __init__(self):
-        self.ene_credential_manager: Optional[ENECloudCredentialManager] = None
-        self.credentials: Dict[str, APICredentials] = {}
-        self._init_ene()
-        self._load_from_env_fallback()
-    
-    def _init_ene(self):
-        """Initialize ENE credential manager."""
-        try:
-            self.ene_credential_manager = ENECloudCredentialManager()
-            print("ENE credential manager initialized", file=sys.stderr)
-        except Exception as e:
-            print(f"ENE initialization failed (using fallback): {e}", file=sys.stderr)
-            self.ene_credential_manager = None
-    
-    def _load_from_env_fallback(self):
-        """Load credentials from environment if ENE not available."""
-        if self.ene_credential_manager:
-            # Try to load from ENE first
-            self._load_from_ene()
-            return
-        
-        notion_key = os.environ.get("NOTION_API_KEY")
-        notion_db = os.environ.get("NOTION_DATABASE_ID")
-        linear_key = os.environ.get("LINEAR_API_KEY")
-        
-        if notion_key:
-            self.credentials["notion"] = APICredentials(
-                service="notion",
-                api_key=notion_key,
-                additional_params={"database_id": notion_db} if notion_db else {}
-            )
-        
-        if linear_key:
-            self.credentials["linear"] = APICredentials(
-                service="linear",
-                api_key=linear_key
-            )
-    
-    def _load_from_ene(self):
-        """Load credentials from ENE credential manager."""
-        if not self.ene_credential_manager:
-            return
-        
-        # Try to get Notion credentials from ENE
-        try:
-            # Use a default node ID for MCP server
-            node_id = "mcp_server_node"
-            notion_creds = self.ene_credential_manager.get_credential_for_node(
-                node_id, "notion"
-            )
-            if notion_creds:
-                self.credentials["notion"] = APICredentials(
-                    service="notion",
-                    api_key=notion_creds.get("api_key", ""),
-                    additional_params={"database_id": notion_creds.get("database_id")},
-                    node_id=node_id
-                )
-        except Exception as e:
-            print(f"Failed to load Notion from ENE: {e}", file=sys.stderr)
-        
-        # Try to get Linear credentials from ENE
-        try:
-            linear_creds = self.ene_credential_manager.get_credential_for_node(
-                node_id, "linear"
-            )
-            if linear_creds:
-                self.credentials["linear"] = APICredentials(
-                    service="linear",
-                    api_key=linear_creds.get("api_key", ""),
-                    node_id=node_id
-                )
-        except Exception as e:
-            print(f"Failed to load Linear from ENE: {e}", file=sys.stderr)
-    
-    def store_credential_ene(self, service: str, api_key: str, 
-                           additional_params: Dict = None) -> str:
-        """Store credential in ENE (encrypted)."""
-        if not self.ene_credential_manager:
-            raise Exception("ENE not available")
-        
-        secret = json.dumps(additional_params) if additional_params else ""
-        
-        cred_id = self.ene_credential_manager.store_credential(
-            provider=service,
-            api_key=api_key,
-            secret=secret,
-            node_assignments=["mcp_server_node"]
-        )
-        
-        # Reload credentials
-        self._load_from_ene()
-        
-        return cred_id
-    
-    def get_credentials(self, service: str) -> Optional[APICredentials]:
-        """Get credentials for service."""
-        return self.credentials.get(service)
-    
-    def has_credentials(self, service: str) -> bool:
-        """Check if credentials exist for service."""
-        return service in self.credentials
-    
-    def get_ene_status(self) -> Dict[str, Any]:
-        """Get ENE integration status."""
-        if not self.ene_credential_manager:
-            return {
-                "ene_enabled": False,
-                "mode": "environment_fallback"
-            }
-        
-        return {
-            "ene_enabled": True,
-            "mode": "ene_encrypted",
-            "balancer_stats": self.ene_credential_manager.balancer.get_balancer_stats()
-        }
-
-# Global credential manager
-_credential_manager: Optional[CredentialManager] = None
-
-def get_credential_manager() -> CredentialManager:
-    """Get or create credential manager."""
-    global _credential_manager
-    if _credential_manager is None:
-        _credential_manager = CredentialManager()
-    return _credential_manager
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Notion API Client
-# ═══════════════════════════════════════════════════════════════════════════
-
-class NotionClient:
-    """Notion API client using web interaction surface."""
-    
-    BASE_URL = "https://api.notion.com/v1"
-    
-    def __init__(self, web_interface: SwarmWebInterface, credentials: APICredentials):
-        self.web = web_interface
-        self.credentials = credentials
-        self.headers = {
-            "Authorization": f"Bearer {credentials.api_key}",
-            "Notion-Version": "2022-06-28",
-            "Content-Type": "application/json"
-        }
-    
-    async def query_database(self, database_id: str = None, 
-                            filter_params: Dict = None) -> Dict[str, Any]:
-        """Query Notion database."""
-        db_id = database_id or self.credentials.additional_params.get("database_id")
-        if not db_id:
-            return {"error": "No database ID provided"}
-        
-        url = f"{self.BASE_URL}/databases/{db_id}/query"
-        payload = {"filter": filter_params} if filter_params else {}
-        
-        # Use web surface for API call
-        task = self.web.surface.submit_task(
-            DutyType.CONTENT_EXTRACTION,
-            url,
-            priority=8,
-            options={
-                "method": "POST",
-                "headers": self.headers,
-                "body": json.dumps(payload)
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-    
-    async def create_page(self, parent_id: str, properties: Dict,
-                        content: List[Dict] = None) -> Dict[str, Any]:
-        """Create page in Notion."""
-        url = f"{self.BASE_URL}/pages"
-        
-        page_data = {
-            "parent": {"database_id": parent_id} if parent_id.startswith("-") else {"page_id": parent_id},
-            "properties": properties
-        }
-        
-        if content:
-            page_data["children"] = content
-        
-        task = self.web.surface.submit_task(
-            DutyType.FORM_INTERACTION,
-            url,
-            priority=8,
-            options={
-                "method": "POST",
-                "headers": self.headers,
-                "body": json.dumps(page_data)
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-    
-    async def update_page(self, page_id: str, properties: Dict) -> Dict[str, Any]:
-        """Update page in Notion."""
-        url = f"{self.BASE_URL}/pages/{page_id}"
-        
-        task = self.web.surface.submit_task(
-            DutyType.FORM_INTERACTION,
-            url,
-            priority=7,
-            options={
-                "method": "PATCH",
-                "headers": self.headers,
-                "body": json.dumps({"properties": properties})
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-    
-    async def get_page(self, page_id: str) -> Dict[str, Any]:
-        """Get page content."""
-        url = f"{self.BASE_URL}/pages/{page_id}"
-        
-        task = self.web.surface.submit_task(
-            DutyType.CONTENT_EXTRACTION,
-            url,
-            priority=7,
-            options={
-                "method": "GET",
-                "headers": self.headers
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-
-# ═══════════════════════════════════════════════════════════════════════════
-# Linear API Client
-# ═══════════════════════════════════════════════════════════════════════════
-
-class LinearClient:
-    """Linear API client using web interaction surface."""
-    
-    BASE_URL = "https://api.linear.app/graphql"
-    
-    def __init__(self, web_interface: SwarmWebInterface, credentials: APICredentials):
-        self.web = web_interface
-        self.credentials = credentials
-        self.headers = {
-            "Authorization": f"{credentials.api_key}",
-            "Content-Type": "application/json"
-        }
-    
-    async def query_issues(self, team_key: str = None, 
-                         status: str = None) -> Dict[str, Any]:
-        """Query Linear issues."""
-        query = """
-        query {
-            issues(first: 50) {
-                nodes {
-                    id
-                    title
-                    description
-                    state {
-                        name
-                    }
-                    priority
-                    assignee {
-                        name
-                    }
-                }
-            }
-        }
-        """
-        
-        task = self.web.surface.submit_task(
-            DutyType.CONTENT_EXTRACTION,
-            self.BASE_URL,
-            priority=8,
-            options={
-                "method": "POST",
-                "headers": self.headers,
-                "body": json.dumps({"query": query})
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-    
-    async def create_issue(self, team_id: str, title: str, 
-                          description: str = None) -> Dict[str, Any]:
-        """Create issue in Linear."""
-        mutation = """
-        mutation($input: IssueCreateInput!) {
-            issueCreate(input: $input) {
-                issue {
-                    id
-                    title
-                    url
-                }
-            }
-        }
-        """
-        
-        variables = {
-            "input": {
-                "teamId": team_id,
-                "title": title,
-                "description": description or ""
-            }
-        }
-        
-        task = self.web.surface.submit_task(
-            DutyType.FORM_INTERACTION,
-            self.BASE_URL,
-            priority=8,
-            options={
-                "method": "POST",
-                "headers": self.headers,
-                "body": json.dumps({"query": mutation, "variables": variables})
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-    
-    async def update_issue_state(self, issue_id: str, 
-                                state_id: str) -> Dict[str, Any]:
-        """Update issue state."""
-        mutation = """
-        mutation($input: IssueUpdateInput!) {
-            issueUpdate(input: $input) {
-                issue {
-                    id
-                    state {
-                        name
-                    }
-                }
-            }
-        }
-        """
-        
-        variables = {
-            "input": {
-                "id": issue_id,
-                "stateId": state_id
-            }
-        }
-        
-        task = self.web.surface.submit_task(
-            DutyType.FORM_INTERACTION,
-            self.BASE_URL,
-            priority=7,
-            options={
-                "method": "POST",
-                "headers": self.headers,
-                "body": json.dumps({"query": mutation, "variables": variables})
-            }
-        )
-        
-        result = self.web.surface.execute_task(task["task_id"])
-        return result
-
-# ═══════════════════════════════════════════════════════════════════════════
-# MCP Server
-# ═══════════════════════════════════════════════════════════════════════════
-
-# Global instances
-_web_interface: Optional[SwarmWebInterface] = None
-_notion_client: Optional[NotionClient] = None
-_linear_client: Optional[LinearClient] = None
-
-def get_web_interface() -> SwarmWebInterface:
-    """Get or create web interface."""
-    global _web_interface
-    if _web_interface is None:
-        _web_interface = SwarmWebInterface()
-    return _web_interface
-
-def get_notion_client() -> Optional[NotionClient]:
-    """Get or create Notion client."""
-    global _notion_client
-    if _notion_client is None:
-        creds = get_credential_manager().get_credentials("notion")
-        if creds:
-            _notion_client = NotionClient(get_web_interface(), creds)
-    return _notion_client
-
-def get_linear_client() -> Optional[LinearClient]:
-    """Get or create Linear client."""
-    global _linear_client
-    if _linear_client is None:
-        creds = get_credential_manager().get_credentials("linear")
-        if creds:
-            _linear_client = LinearClient(get_web_interface(), creds)
-    return _linear_client
-
-# Create MCP server
-server = Server("notion-linear-integration")
-
-@server.list_tools()
-async def list_tools() -> List[Tool]:
-    """List available Notion + Linear tools."""
-    return [
-        # Notion Tools
-        Tool(
-            name="notion_query_database",
-            description="Query Notion database with optional filters.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "database_id": {"type": "string", "description": "Notion database ID (32 chars)"},
-                    "filter": {"type": "object", "description": "Notion filter object"}
-                },
-                "required": []
-            }
-        ),
-        Tool(
-            name="notion_create_page",
-            description="Create a new page in Notion.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "parent_id": {"type": "string", "description": "Parent database or page ID"},
-                    "properties": {"type": "object", "description": "Page properties"},
-                    "content": {"type": "array", "description": "Page content blocks", "items": {"type": "object"}}
-                },
-                "required": ["parent_id", "properties"]
-            }
-        ),
-        Tool(
-            name="notion_update_page",
-            description="Update an existing page in Notion.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "page_id": {"type": "string", "description": "Page ID to update"},
-                    "properties": {"type": "object", "description": "Properties to update"}
-                },
-                "required": ["page_id", "properties"]
-            }
-        ),
-        Tool(
-            name="notion_get_page",
-            description="Get page content from Notion.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "page_id": {"type": "string", "description": "Page ID"}
-                },
-                "required": ["page_id"]
-            }
-        ),
-        # Linear Tools
-        Tool(
-            name="linear_query_issues",
-            description="Query issues from Linear.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "team_key": {"type": "string", "description": "Team key filter"},
-                    "status": {"type": "string", "description": "Status filter"}
-                },
-                "required": []
-            }
-        ),
-        Tool(
-            name="linear_create_issue",
-            description="Create a new issue in Linear.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "team_id": {"type": "string", "description": "Team ID"},
-                    "title": {"type": "string", "description": "Issue title"},
-                    "description": {"type": "string", "description": "Issue description"}
-                },
-                "required": ["team_id", "title"]
-            }
-        ),
-        Tool(
-            name="linear_update_issue_state",
-            description="Update issue state in Linear.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "issue_id": {"type": "string", "description": "Issue ID"},
-                    "state_id": {"type": "string", "description": "State ID"}
-                },
-                "required": ["issue_id", "state_id"]
-            }
-        ),
-        # System Tools
-        Tool(
-            name="check_credentials",
-            description="Check which API credentials are configured.",
-            inputSchema={"type": "object", "properties": {}}
-        ),
-        Tool(
-            name="store_credential_ene",
-            description="Store API credential in ENE (encrypted).",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "service": {"type": "string", "description": "Service name (notion, linear)"},
-                    "api_key": {"type": "string", "description": "API key"},
-                    "additional_params": {"type": "object", "description": "Additional parameters"}
-                },
-                "required": ["service", "api_key"]
-            }
-        ),
-        Tool(
-            name="get_ene_status",
-            description="Get ENE integration status and node health.",
-            inputSchema={"type": "object", "properties": {}}
-        ),
-        Tool(
-            name="sync_research_to_notion",
-            description="Sync Research Stack papers to Notion database.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "paper_path": {"type": "string", "description": "Path to paper markdown file"}
-                },
-                "required": ["paper_path"]
-            }
-        )
-    ]
-
-@server.call_tool()
-async def call_tool(name: str, arguments: Dict[str, Any]) -> List[TextContent]:
-    """Execute tool logic."""
-    
-    if name == "check_credentials":
-        mgr = get_credential_manager()
-        status = {
-            "notion": mgr.has_credentials("notion"),
-            "linear": mgr.has_credentials("linear"),
-            "ene_status": mgr.get_ene_status()
-        }
-        return [TextContent(type="text", text=json.dumps(status, indent=2))]
-    
-    elif name == "store_credential_ene":
-        mgr = get_credential_manager()
-        try:
-            cred_id = mgr.store_credential_ene(
-                service=arguments["service"],
-                api_key=arguments["api_key"],
-                additional_params=arguments.get("additional_params")
-            )
-            return [TextContent(type="text", text=json.dumps({
-                "success": True,
-                "credential_id": cred_id,
-                "encrypted": True,
-                "storage": "ENE (AES-256-GCM)"
-            }, indent=2))]
-        except Exception as e:
-            return [TextContent(type="text", text=json.dumps({
-                "success": False,
-                "error": str(e)
-            }, indent=2))]
-    
-    elif name == "get_ene_status":
-        mgr = get_credential_manager()
-        status = mgr.get_ene_status()
-        return [TextContent(type="text", text=json.dumps(status, indent=2))]
-    
-    # Notion tools
-    elif name.startswith("notion_"):
-        client = get_notion_client()
-        if not client:
-            return [TextContent(type="text", text="Error: Notion credentials not configured")]
-        
-        if name == "notion_query_database":
-            result = await client.query_database(
-                database_id=arguments.get("database_id"),
-                filter_params=arguments.get("filter")
-            )
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-        
-        elif name == "notion_create_page":
-            result = await client.create_page(
-                parent_id=arguments["parent_id"],
-                properties=arguments["properties"],
-                content=arguments.get("content")
-            )
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-        
-        elif name == "notion_update_page":
-            result = await client.update_page(
-                page_id=arguments["page_id"],
-                properties=arguments["properties"]
-            )
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-        
-        elif name == "notion_get_page":
-            result = await client.get_page(page_id=arguments["page_id"])
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-    
-    # Linear tools
-    elif name.startswith("linear_"):
-        client = get_linear_client()
-        if not client:
-            return [TextContent(type="text", text="Error: Linear credentials not configured")]
-        
-        if name == "linear_query_issues":
-            result = await client.query_issues(
-                team_key=arguments.get("team_key"),
-                status=arguments.get("status")
-            )
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-        
-        elif name == "linear_create_issue":
-            result = await client.create_issue(
-                team_id=arguments["team_id"],
-                title=arguments["title"],
-                description=arguments.get("description")
-            )
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-        
-        elif name == "linear_update_issue_state":
-            result = await client.update_issue_state(
-                issue_id=arguments["issue_id"],
-                state_id=arguments["state_id"]
-            )
-            return [TextContent(type="text", text=json.dumps(result, indent=2))]
-    
-    # Sync tool
-    elif name == "sync_research_to_notion":
-        client = get_notion_client()
-        if not client:
-            return [TextContent(type="text", text="Error: Notion credentials not configured")]
-        
-        paper_path = arguments["paper_path"]
-        paper_file = Path(paper_path)
-        
-        if not paper_file.exists():
-            return [TextContent(type="text", text=f"Error: Paper not found at {paper_path}")]
-        
-        # Read paper content
-        with open(paper_file) as f:
-            content = f.read()
-        
-        # Extract title (first line with #)
-        title = "Untitled Paper"
-        for line in content.split("\n"):
-            if line.startswith("# "):
-                title = line[2:].strip()
-                break
-        
-        # Create page in Notion
-        db_id = client.credentials.additional_params.get("database_id")
-        if not db_id:
-            return [TextContent(type="text", text="Error: No Notion database ID configured")]
-        
-        properties = {
-            "title": {
-                "title": [{"text": {"content": title}}]
-            },
-            "Status": {
-                "select": {"name": "In Progress"}
-            }
-        }
-        
-        result = await client.create_page(
-            parent_id=db_id,
-            properties=properties,
-            content=[{
-                "object": "block",
-                "type": "paragraph",
-                "paragraph": {
-                    "rich_text": [{"type": "text", "text": {"content": content[:2000]}}]
-                }
-            }]
-        )
-        
-        return [TextContent(type="text", text=json.dumps(result, indent=2))]
-    
-    else:
-        raise ValueError(f"Unknown tool: {name}")
-
-async def main():
-    async with stdio_server() as (read_stream, write_stream):
-        await server.run(read_stream, write_stream, server.create_initialization_options())
-
-if __name__ == "__main__":
-    asyncio.run(main())

From 3dcb5a2d0af9c3228b5a3d2246e834e242ea0547 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:59:30 -0500
Subject: [PATCH 34/43] chore(pending): quarantine python ENE ContextStream MCP
 surface (Lean-first unification)

---
 .../infra/ene_contextstream_mcp.py            | 623 ------------------
 1 file changed, 623 deletions(-)
 delete mode 100755 4-Infrastructure/infra/ene_contextstream_mcp.py

diff --git a/4-Infrastructure/infra/ene_contextstream_mcp.py b/4-Infrastructure/infra/ene_contextstream_mcp.py
deleted file mode 100755
index b6fecdec..00000000
--- a/4-Infrastructure/infra/ene_contextstream_mcp.py
+++ /dev/null
@@ -1,623 +0,0 @@
-#!/usr/bin/env python3
-"""ENE Context MCP surface.
-
-Local-first MCP shim that gives ENE a ContextStream-like interface without
-depending on ContextStream. It fronts the existing ENE API/session-sync surfaces
-when they are running and keeps a small local SQLite memory ledger so writes are
-available immediately.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import sqlite3
-import subprocess
-import sys
-import time
-import urllib.error
-import urllib.parse
-import urllib.request
-from pathlib import Path
-from typing import Any
-
-
-SERVER_NAME = "ene-contextstream"
-SERVER_VERSION = "0.1.0"
-DEFAULT_API_URL = "http://127.0.0.1:3000"
-DEFAULT_STORE = Path.home() / ".local/share/ene/contextstream.sqlite"
-DEFAULT_CANDIDATE_ROOT = (
-    Path.cwd() / "shared-data/data/germane/research/github-ene-contextstream"
-)
-
-
-def now_ms() -> int:
-    return int(time.time() * 1000)
-
-
-def sha256_text(text: str) -> str:
-    return hashlib.sha256(text.encode("utf-8")).hexdigest()
-
-
-def json_text(data: Any) -> list[dict[str, str]]:
-    return [{"type": "text", "text": json.dumps(data, indent=2, sort_keys=True)}]
-
-
-def store_path() -> Path:
-    return Path(os.environ.get("ENE_CONTEXT_STORE", str(DEFAULT_STORE))).expanduser()
-
-
-def api_url() -> str:
-    return os.environ.get("ENE_API_URL", DEFAULT_API_URL).rstrip("/")
-
-
-def connect_store() -> sqlite3.Connection:
-    path = store_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(path)
-    conn.row_factory = sqlite3.Row
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS memories (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            agent TEXT NOT NULL,
-            key TEXT NOT NULL,
-            value_json TEXT NOT NULL,
-            value_text TEXT NOT NULL,
-            tags_json TEXT NOT NULL DEFAULT '[]',
-            kind TEXT NOT NULL DEFAULT 'note',
-            source TEXT NOT NULL DEFAULT 'mcp',
-            prev_hash TEXT,
-            receipt_hash TEXT NOT NULL,
-            created_at_ms INTEGER NOT NULL,
-            updated_at_ms INTEGER NOT NULL,
-            UNIQUE(agent, key)
-        )
-        """
-    )
-    conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_agent ON memories(agent)")
-    conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_key ON memories(key)")
-    conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at_ms DESC)")
-    conn.commit()
-    return conn
-
-
-def parse_value(raw: Any) -> tuple[Any, str]:
-    if isinstance(raw, str):
-        try:
-            value = json.loads(raw)
-        except json.JSONDecodeError:
-            value = raw
-    else:
-        value = raw
-    text = json.dumps(value, sort_keys=True) if not isinstance(value, str) else value
-    return value, text
-
-
-def http_json(path: str, query: dict[str, Any] | None = None, timeout: float = 3.0) -> Any:
-    url = f"{api_url()}{path}"
-    if query:
-        url = f"{url}?{urllib.parse.urlencode(query)}"
-    req = urllib.request.Request(url, headers={"Accept": "application/json"})
-    try:
-        with urllib.request.urlopen(req, timeout=timeout) as response:
-            status = response.status
-            content_type = response.headers.get("content-type", "")
-            text = response.read().decode("utf-8", errors="replace")
-    except urllib.error.HTTPError as exc:
-        status = exc.code
-        content_type = exc.headers.get("content-type", "")
-        text = exc.read().decode("utf-8", errors="replace")
-    try:
-        data = json.loads(text)
-    except json.JSONDecodeError:
-        return {
-            "ok": False,
-            "error": "non-json response from ENE API",
-            "status": status,
-            "content_type": content_type,
-            "body": text,
-            "url": url,
-        }
-    if isinstance(data, dict):
-        data.setdefault("status", status)
-        data.setdefault("url", url)
-    return data
-
-
-def tool_status(_: dict[str, Any]) -> dict[str, Any]:
-    conn = connect_store()
-    row = conn.execute("SELECT COUNT(*), MAX(updated_at_ms) FROM memories").fetchone()
-    api = {"ok": False, "url": api_url()}
-    try:
-        api = http_json("/health")
-        api["url"] = api_url()
-    except Exception as exc:  # local status should not fail the MCP call
-        api["error"] = f"{type(exc).__name__}: {exc}"
-
-    sync_bin = os.environ.get(
-        "ENE_SESSION_SYNC_BIN",
-        str(Path.cwd() / "4-Infrastructure/infra/ene-rds/target/release/ene-sync"),
-    )
-    return {
-        "ok": True,
-        "server": SERVER_NAME,
-        "version": SERVER_VERSION,
-        "api": api,
-        "local_store": {
-            "path": str(store_path()),
-            "memory_count": row[0],
-            "last_updated_ms": row[1],
-        },
-        "session_sync": {
-            "path": sync_bin,
-            "exists": Path(sync_bin).exists(),
-        },
-        "candidate_import_root": str(
-            Path(os.environ.get("ENE_CONTEXT_CANDIDATE_ROOT", str(DEFAULT_CANDIDATE_ROOT)))
-        ),
-    }
-
-
-def tool_remember(args: dict[str, Any]) -> dict[str, Any]:
-    agent = str(args.get("agent") or "codex")
-    key = str(args["key"])
-    value, value_text = parse_value(args.get("value"))
-    tags = args.get("tags") or []
-    if isinstance(tags, str):
-        tags = [t.strip() for t in tags.split(",") if t.strip()]
-    kind = str(args.get("kind") or "note")
-    source = str(args.get("source") or "mcp")
-    ts = now_ms()
-
-    conn = connect_store()
-    prev = conn.execute(
-        "SELECT receipt_hash FROM memories WHERE agent = ? ORDER BY updated_at_ms DESC LIMIT 1",
-        (agent,),
-    ).fetchone()
-    prev_hash = prev[0] if prev else None
-    payload = json.dumps(
-        {
-            "agent": agent,
-            "key": key,
-            "value": value,
-            "tags": tags,
-            "kind": kind,
-            "source": source,
-            "prev_hash": prev_hash,
-            "updated_at_ms": ts,
-        },
-        sort_keys=True,
-    )
-    receipt = sha256_text(payload)
-    conn.execute(
-        """
-        INSERT INTO memories
-          (agent, key, value_json, value_text, tags_json, kind, source,
-           prev_hash, receipt_hash, created_at_ms, updated_at_ms)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT(agent, key) DO UPDATE SET
-          value_json = excluded.value_json,
-          value_text = excluded.value_text,
-          tags_json = excluded.tags_json,
-          kind = excluded.kind,
-          source = excluded.source,
-          prev_hash = excluded.prev_hash,
-          receipt_hash = excluded.receipt_hash,
-          updated_at_ms = excluded.updated_at_ms
-        """,
-        (
-            agent,
-            key,
-            json.dumps(value, sort_keys=True),
-            value_text,
-            json.dumps(tags, sort_keys=True),
-            kind,
-            source,
-            prev_hash,
-            receipt,
-            ts,
-            ts,
-        ),
-    )
-    conn.commit()
-    return {
-        "ok": True,
-        "agent": agent,
-        "key": key,
-        "kind": kind,
-        "tags": tags,
-        "receipt_hash": receipt,
-        "prev_hash": prev_hash,
-        "store": str(store_path()),
-    }
-
-
-def row_to_memory(row: sqlite3.Row) -> dict[str, Any]:
-    return {
-        "agent": row["agent"],
-        "key": row["key"],
-        "value": json.loads(row["value_json"]),
-        "tags": json.loads(row["tags_json"]),
-        "kind": row["kind"],
-        "source": row["source"],
-        "receipt_hash": row["receipt_hash"],
-        "prev_hash": row["prev_hash"],
-        "created_at_ms": row["created_at_ms"],
-        "updated_at_ms": row["updated_at_ms"],
-    }
-
-
-def tool_recall(args: dict[str, Any]) -> dict[str, Any]:
-    agent = str(args.get("agent") or "codex")
-    key = args.get("key")
-    query = str(args.get("query") or "")
-    limit = int(args.get("limit") or 10)
-    conn = connect_store()
-
-    if key is not None:
-        row = conn.execute(
-            "SELECT * FROM memories WHERE agent = ? AND key = ?",
-            (agent, str(key)),
-        ).fetchone()
-        return {"ok": True, "found": row is not None, "memory": row_to_memory(row) if row else None}
-
-    needle = f"%{query}%"
-    rows = conn.execute(
-        """
-        SELECT * FROM memories
-        WHERE agent = ? AND (? = '' OR key LIKE ? OR value_text LIKE ? OR tags_json LIKE ?)
-        ORDER BY updated_at_ms DESC
-        LIMIT ?
-        """,
-        (agent, query, needle, needle, needle, limit),
-    ).fetchall()
-    return {"ok": True, "count": len(rows), "memories": [row_to_memory(r) for r in rows]}
-
-
-def tool_search(args: dict[str, Any]) -> dict[str, Any]:
-    query = str(args["query"])
-    limit = int(args.get("limit") or 10)
-    semantic = bool(args.get("semantic") or False)
-    sources = args.get("sources") or ["ene_api", "wiki", "local_memory"]
-    out: dict[str, Any] = {"ok": True, "query": query, "results": {}}
-
-    if "ene_api" in sources:
-        try:
-            out["results"]["ene_api"] = http_json(
-                "/search",
-                {"q": query, "limit": limit, "semantic": str(semantic).lower()},
-            )
-        except Exception as exc:
-            out["results"]["ene_api"] = {
-                "ok": False,
-                "error": f"{type(exc).__name__}: {exc}",
-                "url": api_url(),
-            }
-
-    if "wiki" in sources:
-        try:
-            out["results"]["wiki"] = http_json(
-                "/wiki/search",
-                {"q": query, "limit": limit},
-            )
-        except Exception as exc:
-            out["results"]["wiki"] = {
-                "ok": False,
-                "error": f"{type(exc).__name__}: {exc}",
-                "url": api_url(),
-            }
-
-    if "local_memory" in sources:
-        out["results"]["local_memory"] = tool_recall(
-            {"agent": args.get("agent", "codex"), "query": query, "limit": limit}
-        )
-    return out
-
-
-def tool_context(args: dict[str, Any]) -> dict[str, Any]:
-    """One-call session-start context packet for agents.
-
-    This mirrors ContextStream's common startup habit while staying ENE-first:
-    status + search + optional recall + optional transcript save.
-    """
-    user_message = str(args.get("user_message") or args.get("query") or "")
-    agent = str(args.get("agent") or "codex")
-    save_exchange = bool(args.get("save_exchange") or False)
-    session_id = args.get("session_id")
-    result: dict[str, Any] = {
-        "ok": True,
-        "policy": "ENE first. ContextStream is fallback only.",
-        "status": tool_status({}),
-        "search": None,
-        "recall": None,
-        "saved": None,
-    }
-    if user_message:
-        result["search"] = tool_search({"query": user_message, "agent": agent, "limit": args.get("limit", 10)})
-        result["recall"] = tool_recall({"agent": agent, "query": user_message, "limit": args.get("limit", 10)})
-    if save_exchange and user_message:
-        key = f"session:{session_id or now_ms()}:user:{now_ms()}"
-        result["saved"] = tool_remember(
-            {
-                "agent": agent,
-                "key": key,
-                "value": {"user_message": user_message, "session_id": session_id},
-                "tags": ["transcript", "user-message"],
-                "kind": "conversation",
-                "source": "ene_context",
-            }
-        )
-    return result
-
-
-def tool_sessions(args: dict[str, Any]) -> dict[str, Any]:
-    action = str(args.get("action") or "list")
-    limit = int(args.get("limit") or 10)
-    try:
-        if action == "list":
-            return http_json("/sessions", {"limit": limit})
-        if action == "get":
-            return http_json(f"/sessions/{urllib.parse.quote(str(args['session_id']))}")
-    except Exception as exc:
-        return {"ok": False, "error": f"{type(exc).__name__}: {exc}", "url": api_url()}
-    return {"ok": False, "error": f"unknown sessions action: {action}"}
-
-
-def tool_sync(args: dict[str, Any]) -> dict[str, Any]:
-    dry_run = bool(args.get("dry_run", True))
-    command = str(args.get("command") or "list")
-    sync_bin = os.environ.get(
-        "ENE_SESSION_SYNC_BIN",
-        str(Path.cwd() / "4-Infrastructure/infra/ene-rds/target/release/ene-sync"),
-    )
-    cmd = [sync_bin]
-    if command == "sync":
-        cmd.append("sync")
-        if args.get("embed"):
-            cmd.insert(1, "--embed")
-    elif command == "list":
-        cmd.extend(["list", "--limit", str(int(args.get("limit") or 20))])
-    elif command == "init-schema":
-        cmd.append("init-schema")
-    else:
-        return {"ok": False, "error": f"unsupported sync command: {command}"}
-
-    if dry_run:
-        return {"ok": True, "dry_run": True, "command": cmd, "exists": Path(sync_bin).exists()}
-    if not Path(sync_bin).exists():
-        return {"ok": False, "error": "ene-session-sync binary not found", "command": cmd}
-    proc = subprocess.run(cmd, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=120)
-    return {
-        "ok": proc.returncode == 0,
-        "returncode": proc.returncode,
-        "stdout": proc.stdout[-8000:],
-        "stderr": proc.stderr[-8000:],
-        "command": cmd,
-    }
-
-
-def candidate_summary(path: Path) -> dict[str, Any]:
-    readme = next(path.glob("README*"), None)
-    cargo = path / "Cargo.toml"
-    package = path / "package.json"
-    pyproject = path / "pyproject.toml"
-    return {
-        "repo": path.name,
-        "path": str(path),
-        "readme": str(readme) if readme else None,
-        "manifests": [str(p) for p in [cargo, package, pyproject] if p.exists()],
-    }
-
-
-def tool_import_candidates(args: dict[str, Any]) -> dict[str, Any]:
-    root = Path(args.get("root") or os.environ.get("ENE_CONTEXT_CANDIDATE_ROOT", str(DEFAULT_CANDIDATE_ROOT)))
-    repos = [p for p in sorted(root.iterdir()) if p.is_dir() and (p / ".git").exists()] if root.exists() else []
-    map_notes = {
-        "Octopoda-OS": "Agent memory API, remember/recall/search/snapshot/audit vocabulary.",
-        "llm_wiki": "Source -> wiki -> graph ingest pattern and local API shape.",
-        "SurfSense": "Browser/Obsidian/document connectors and team RAG workflows.",
-        "forge": "Local tool-calling guardrails and proxy agent loop patterns.",
-        "kanbots": "MCP over local HTTP bridge and agent task board semantics.",
-        "namidb": "Graph database on object storage; useful for ENE graph persistence.",
-        "Vane": "Local answering engine with SearXNG/search history/citation UX.",
-    }
-    return {
-        "ok": True,
-        "root": str(root),
-        "count": len(repos),
-        "candidates": [
-            {**candidate_summary(p), "ene_use": map_notes.get(p.name, "Review manually")}
-            for p in repos
-        ],
-    }
-
-
-TOOLS: dict[str, dict[str, Any]] = {
-    "ene_status": {
-        "description": "ENE context health: local memory ledger, ENE API, session-sync binary.",
-        "inputSchema": {"type": "object", "properties": {}},
-        "handler": tool_status,
-    },
-    "ene_remember": {
-        "description": "Store a durable ENE memory packet with a hash-chain receipt.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "agent": {"type": "string", "default": "codex"},
-                "key": {"type": "string"},
-                "value": {},
-                "tags": {"type": "array", "items": {"type": "string"}},
-                "kind": {"type": "string", "default": "note"},
-                "source": {"type": "string", "default": "mcp"},
-            },
-            "required": ["key", "value"],
-        },
-        "handler": tool_remember,
-    },
-    "ene_context": {
-        "description": "ENE-first startup/context packet: status, search, recall, optional transcript save.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "user_message": {"type": "string"},
-                "query": {"type": "string"},
-                "agent": {"type": "string", "default": "codex"},
-                "session_id": {"type": "string"},
-                "save_exchange": {"type": "boolean", "default": False},
-                "limit": {"type": "integer", "default": 10},
-            },
-        },
-        "handler": tool_context,
-    },
-    "ene_recall": {
-        "description": "Recall ENE memory by exact key or query over local memory.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "agent": {"type": "string", "default": "codex"},
-                "key": {"type": "string"},
-                "query": {"type": "string"},
-                "limit": {"type": "integer", "default": 10},
-            },
-        },
-        "handler": tool_recall,
-    },
-    "ene_search": {
-        "description": "Search ENE API chat/session memory plus local ENE memory ledger.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "query": {"type": "string"},
-                "limit": {"type": "integer", "default": 10},
-                "semantic": {"type": "boolean", "default": False},
-                "agent": {"type": "string", "default": "codex"},
-                "sources": {"type": "array", "items": {"type": "string"}},
-            },
-            "required": ["query"],
-        },
-        "handler": tool_search,
-    },
-    "ene_sessions": {
-        "description": "List or fetch ENE chat sessions through ene-api.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "action": {"type": "string", "enum": ["list", "get"], "default": "list"},
-                "session_id": {"type": "string"},
-                "limit": {"type": "integer", "default": 10},
-            },
-        },
-        "handler": tool_sessions,
-    },
-    "ene_sync": {
-        "description": "Run or dry-run ene-session-sync commands.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "command": {"type": "string", "enum": ["list", "sync", "init-schema"], "default": "list"},
-                "dry_run": {"type": "boolean", "default": True},
-                "limit": {"type": "integer", "default": 20},
-                "embed": {"type": "boolean", "default": False},
-            },
-        },
-        "handler": tool_sync,
-    },
-    "ene_import_candidates": {
-        "description": "List GitHub repos pulled as ENE ContextStream-equivalent candidates.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {"root": {"type": "string"}},
-        },
-        "handler": tool_import_candidates,
-    },
-}
-
-
-def mcp_tools() -> list[dict[str, Any]]:
-    return [
-        {
-            "name": name,
-            "description": spec["description"],
-            "inputSchema": spec["inputSchema"],
-        }
-        for name, spec in TOOLS.items()
-    ]
-
-
-def handle(req: dict[str, Any]) -> dict[str, Any] | None:
-    method = req.get("method")
-    req_id = req.get("id")
-    try:
-        if method == "initialize":
-            return {
-                "jsonrpc": "2.0",
-                "id": req_id,
-                "result": {
-                    "protocolVersion": req.get("params", {}).get("protocolVersion", "2024-11-05"),
-                    "capabilities": {"tools": {}},
-                    "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
-                },
-            }
-        if method == "notifications/initialized":
-            return None
-        if method == "tools/list":
-            return {"jsonrpc": "2.0", "id": req_id, "result": {"tools": mcp_tools()}}
-        if method == "tools/call":
-            params = req.get("params", {})
-            name = params.get("name")
-            if name not in TOOLS:
-                raise ValueError(f"unknown tool: {name}")
-            args = params.get("arguments") or {}
-            result = TOOLS[name]["handler"](args)
-            return {"jsonrpc": "2.0", "id": req_id, "result": {"content": json_text(result)}}
-        return {
-            "jsonrpc": "2.0",
-            "id": req_id,
-            "error": {"code": -32601, "message": f"method not found: {method}"},
-        }
-    except Exception as exc:
-        return {
-            "jsonrpc": "2.0",
-            "id": req_id,
-            "error": {"code": -32000, "message": f"{type(exc).__name__}: {exc}"},
-        }
-
-
-def main() -> int:
-    if len(sys.argv) > 1:
-        command = sys.argv[1]
-        if command in {"--status", "status"}:
-            print(json.dumps(tool_status({}), indent=2, sort_keys=True))
-            return 0
-        if command in {"--context", "context"}:
-            query = " ".join(sys.argv[2:])
-            print(json.dumps(tool_context({"user_message": query}), indent=2, sort_keys=True))
-            return 0
-        print(f"unknown command: {command}", file=sys.stderr)
-        return 2
-
-    handled = 0
-    for line in sys.stdin:
-        if not line.strip():
-            continue
-        handled += 1
-        try:
-            response = handle(json.loads(line))
-        except json.JSONDecodeError as exc:
-            response = {
-                "jsonrpc": "2.0",
-                "id": None,
-                "error": {"code": -32700, "message": str(exc)},
-            }
-        if response is not None:
-            sys.stdout.write(json.dumps(response, separators=(",", ":")) + "\n")
-            sys.stdout.flush()
-    if handled == 0:
-        print(json.dumps(tool_status({}), indent=2, sort_keys=True))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

From 5a829b4f05ea1edcfb277410d439c293fe9b460e Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:59:40 -0500
Subject: [PATCH 35/43] chore(pending): move python Notion+Linear MCP server
 into pending quarantine

---
 .../scripts/mcp_notion_linear.py              | 762 ++++++++++++++++++
 1 file changed, 762 insertions(+)
 create mode 100644 pending/lean_unification/5-Applications/scripts/mcp_notion_linear.py

diff --git a/pending/lean_unification/5-Applications/scripts/mcp_notion_linear.py b/pending/lean_unification/5-Applications/scripts/mcp_notion_linear.py
new file mode 100644
index 00000000..5ca5b970
--- /dev/null
+++ b/pending/lean_unification/5-Applications/scripts/mcp_notion_linear.py
@@ -0,0 +1,762 @@
+#!/usr/bin/env python3
+"""
+MCP Server for Notion + Linear Integration
+
+Provides unified access to Notion and Linear APIs using existing Research Stack surfaces:
+- Notion: Research database management, page creation, content sync
+- Linear: Issue tracking, project management, workflow automation
+- ENE: Credential management via distributed node encryption
+- Web Surface: HTTP API calls via SwarmWebSurface
+
+Per AGENTS.md: This is a shim layer. All logic resides in Lean modules.
+API credentials managed via ENE (AES-256-GCM encrypted).
+"""
+
+import sys
+import json
+import asyncio
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from dataclasses import dataclass
+from enum import Enum
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "4-Infrastructure"))
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "0-Core-Formalism"))
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "4-Infrastructure" / "infra"))
+
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import Tool, TextContent
+except ImportError:
+    print("MCP SDK not installed. Install with: pip install mcp", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    from infra.web_interaction_surface import SwarmWebInterface, DutyType
+except ImportError:
+    print("Web interaction surface not found", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    from infra.ene_cloud_credential_manager import (
+        ENECloudCredentialManager,
+        ENETopologicalStorage,
+        ENENodeBalancer
+    )
+except ImportError:
+    print("ENE cloud credential manager not found", file=sys.stderr)
+    sys.exit(1)
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Credential Management via ENE
+# ═══════════════════════════════════════════════════════════════════════════
+
+@dataclass
+class APICredentials:
+    """API credentials managed via ENE."""
+    service: str
+    api_key: str
+    additional_params: Dict[str, str] = None
+    node_id: str = None  # Which node provided these credentials
+    
+    def __post_init__(self):
+        if self.additional_params is None:
+            self.additional_params = {}
+
+class CredentialManager:
+    """
+    Credential manager using ENE for encrypted storage.
+    
+    Integrates with:
+    - ENE distributed node system (6-node mesh)
+    - Shamir-secret sharing (6 shards, 2/3 threshold)
+    - AES-256-GCM encryption via ENESecurityManager
+    - Health-weighted node routing via ENENodeBalancer
+    """
+    
+    def __init__(self):
+        self.ene_credential_manager: Optional[ENECloudCredentialManager] = None
+        self.credentials: Dict[str, APICredentials] = {}
+        self._init_ene()
+        self._load_from_env_fallback()
+    
+    def _init_ene(self):
+        """Initialize ENE credential manager."""
+        try:
+            self.ene_credential_manager = ENECloudCredentialManager()
+            print("ENE credential manager initialized", file=sys.stderr)
+        except Exception as e:
+            print(f"ENE initialization failed (using fallback): {e}", file=sys.stderr)
+            self.ene_credential_manager = None
+    
+    def _load_from_env_fallback(self):
+        """Load credentials from environment if ENE not available."""
+        if self.ene_credential_manager:
+            # Try to load from ENE first
+            self._load_from_ene()
+            return
+        
+        notion_key = os.environ.get("NOTION_API_KEY")
+        notion_db = os.environ.get("NOTION_DATABASE_ID")
+        linear_key = os.environ.get("LINEAR_API_KEY")
+        
+        if notion_key:
+            self.credentials["notion"] = APICredentials(
+                service="notion",
+                api_key=notion_key,
+                additional_params={"database_id": notion_db} if notion_db else {}
+            )
+        
+        if linear_key:
+            self.credentials["linear"] = APICredentials(
+                service="linear",
+                api_key=linear_key
+            )
+    
+    def _load_from_ene(self):
+        """Load credentials from ENE credential manager."""
+        if not self.ene_credential_manager:
+            return
+        
+        # Try to get Notion credentials from ENE
+        try:
+            # Use a default node ID for MCP server
+            node_id = "mcp_server_node"
+            notion_creds = self.ene_credential_manager.get_credential_for_node(
+                node_id, "notion"
+            )
+            if notion_creds:
+                self.credentials["notion"] = APICredentials(
+                    service="notion",
+                    api_key=notion_creds.get("api_key", ""),
+                    additional_params={"database_id": notion_creds.get("database_id")},
+                    node_id=node_id
+                )
+        except Exception as e:
+            print(f"Failed to load Notion from ENE: {e}", file=sys.stderr)
+        
+        # Try to get Linear credentials from ENE
+        try:
+            linear_creds = self.ene_credential_manager.get_credential_for_node(
+                node_id, "linear"
+            )
+            if linear_creds:
+                self.credentials["linear"] = APICredentials(
+                    service="linear",
+                    api_key=linear_creds.get("api_key", ""),
+                    node_id=node_id
+                )
+        except Exception as e:
+            print(f"Failed to load Linear from ENE: {e}", file=sys.stderr)
+    
+    def store_credential_ene(self, service: str, api_key: str, 
+                           additional_params: Dict = None) -> str:
+        """Store credential in ENE (encrypted)."""
+        if not self.ene_credential_manager:
+            raise Exception("ENE not available")
+        
+        secret = json.dumps(additional_params) if additional_params else ""
+        
+        cred_id = self.ene_credential_manager.store_credential(
+            provider=service,
+            api_key=api_key,
+            secret=secret,
+            node_assignments=["mcp_server_node"]
+        )
+        
+        # Reload credentials
+        self._load_from_ene()
+        
+        return cred_id
+    
+    def get_credentials(self, service: str) -> Optional[APICredentials]:
+        """Get credentials for service."""
+        return self.credentials.get(service)
+    
+    def has_credentials(self, service: str) -> bool:
+        """Check if credentials exist."""
+        return service in self.credentials
+    
+    def get_ene_status(self) -> Dict[str, Any]:
+        """Get ENE integration status."""
+        if not self.ene_credential_manager:
+            return {
+                "ene_enabled": False,
+                "mode": "environment_fallback"
+            }
+        
+        return {
+            "ene_enabled": True,
+            "mode": "ene_encrypted",
+            "balancer_stats": self.ene_credential_manager.balancer.get_balancer_stats()
+        }
+
+# Global credential manager
+_credential_manager: Optional[CredentialManager] = None
+
+def get_credential_manager() -> CredentialManager:
+    """Get or create credential manager."""
+    global _credential_manager
+    if _credential_manager is None:
+        _credential_manager = CredentialManager()
+    return _credential_manager
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Notion API Client
+# ═══════════════════════════════════════════════════════════════════════════
+
+class NotionClient:
+    """Notion API client using web interaction surface."""
+    
+    BASE_URL = "https://api.notion.com/v1"
+    
+    def __init__(self, web_interface: SwarmWebInterface, credentials: APICredentials):
+        self.web = web_interface
+        self.credentials = credentials
+        self.headers = {
+            "Authorization": f"Bearer {credentials.api_key}",
+            "Notion-Version": "2022-06-28",
+            "Content-Type": "application/json"
+        }
+    
+    async def query_database(self, database_id: str = None, 
+                            filter_params: Dict = None) -> Dict[str, Any]:
+        """Query Notion database."""
+        db_id = database_id or self.credentials.additional_params.get("database_id")
+        if not db_id:
+            return {"error": "No database ID provided"}
+        
+        url = f"{self.BASE_URL}/databases/{db_id}/query"
+        payload = {"filter": filter_params} if filter_params else {}
+        
+        # Use web surface for API call
+        task = self.web.surface.submit_task(
+            DutyType.CONTENT_EXTRACTION,
+            url,
+            priority=8,
+            options={
+                "method": "POST",
+                "headers": self.headers,
+                "body": json.dumps(payload)
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+    
+    async def create_page(self, parent_id: str, properties: Dict,
+                        content: List[Dict] = None) -> Dict[str, Any]:
+        """Create page in Notion."""
+        url = f"{self.BASE_URL}/pages"
+        
+        page_data = {
+            "parent": {"database_id": parent_id} if parent_id.startswith("-") else {"page_id": parent_id},
+            "properties": properties
+        }
+        
+        if content:
+            page_data["children"] = content
+        
+        task = self.web.surface.submit_task(
+            DutyType.FORM_INTERACTION,
+            url,
+            priority=8,
+            options={
+                "method": "POST",
+                "headers": self.headers,
+                "body": json.dumps(page_data)
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+    
+    async def update_page(self, page_id: str, properties: Dict) -> Dict[str, Any]:
+        """Update page in Notion."""
+        url = f"{self.BASE_URL}/pages/{page_id}"
+        
+        task = self.web.surface.submit_task(
+            DutyType.FORM_INTERACTION,
+            url,
+            priority=7,
+            options={
+                "method": "PATCH",
+                "headers": self.headers,
+                "body": json.dumps({"properties": properties})
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+    
+    async def get_page(self, page_id: str) -> Dict[str, Any]:
+        """Get page content."""
+        url = f"{self.BASE_URL}/pages/{page_id}"
+        
+        task = self.web.surface.submit_task(
+            DutyType.CONTENT_EXTRACTION,
+            url,
+            priority=7,
+            options={
+                "method": "GET",
+                "headers": self.headers
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Linear API Client
+# ═══════════════════════════════════════════════════════════════════════════
+
+class LinearClient:
+    """Linear API client using web interaction surface."""
+    
+    BASE_URL = "https://api.linear.app/graphql"
+    
+    def __init__(self, web_interface: SwarmWebInterface, credentials: APICredentials):
+        self.web = web_interface
+        self.credentials = credentials
+        self.headers = {
+            "Authorization": f"{credentials.api_key}",
+            "Content-Type": "application/json"
+        }
+    
+    async def query_issues(self, team_key: str = None, 
+                         status: str = None) -> Dict[str, Any]:
+        """Query Linear issues."""
+        query = """
+        query {
+            issues(first: 50) {
+                nodes {
+                    id
+                    title
+                    description
+                    state {
+                        name
+                    }
+                    priority
+                    assignee {
+                        name
+                    }
+                }
+            }
+        }
+        """
+        
+        task = self.web.surface.submit_task(
+            DutyType.CONTENT_EXTRACTION,
+            self.BASE_URL,
+            priority=8,
+            options={
+                "method": "POST",
+                "headers": self.headers,
+                "body": json.dumps({"query": query})
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+    
+    async def create_issue(self, team_id: str, title: str, 
+                          description: str = None) -> Dict[str, Any]:
+        """Create issue in Linear."""
+        mutation = """
+        mutation($input: IssueCreateInput!) {
+            issueCreate(input: $input) {
+                issue {
+                    id
+                    title
+                    url
+                }
+            }
+        }
+        """
+        
+        variables = {
+            "input": {
+                "teamId": team_id,
+                "title": title,
+                "description": description or ""
+            }
+        }
+        
+        task = self.web.surface.submit_task(
+            DutyType.FORM_INTERACTION,
+            self.BASE_URL,
+            priority=8,
+            options={
+                "method": "POST",
+                "headers": self.headers,
+                "body": json.dumps({"query": mutation, "variables": variables})
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+    
+    async def update_issue_state(self, issue_id: str, 
+                                state_id: str) -> Dict[str, Any]:
+        """Update issue state."""
+        mutation = """
+        mutation($input: IssueUpdateInput!) {
+            issueUpdate(input: $input) {
+                issue {
+                    id
+                    state {
+                        name
+                    }
+                }
+            }
+        }
+        """
+        
+        variables = {
+            "input": {
+                "id": issue_id,
+                "stateId": state_id
+            }
+        }
+        
+        task = self.web.surface.submit_task(
+            DutyType.FORM_INTERACTION,
+            self.BASE_URL,
+            priority=7,
+            options={
+                "method": "POST",
+                "headers": self.headers,
+                "body": json.dumps({"query": mutation, "variables": variables})
+            }
+        )
+        
+        result = self.web.surface.execute_task(task["task_id"])
+        return result
+
+# ═══════════════════════════════════════════════════════════════════════════
+# MCP Server
+# ═══════════════════════════════════════════════════════════════════════════
+
+# Global instances
+_web_interface: Optional[SwarmWebInterface] = None
+_notion_client: Optional[NotionClient] = None
+_linear_client: Optional[LinearClient] = None
+
+def get_web_interface() -> SwarmWebInterface:
+    """Get or create web interface."""
+    global _web_interface
+    if _web_interface is None:
+        _web_interface = SwarmWebInterface()
+    return _web_interface
+
+def get_notion_client() -> Optional[NotionClient]:
+    """Get or create Notion client."""
+    global _notion_client
+    if _notion_client is None:
+        creds = get_credential_manager().get_credentials("notion")
+        if creds:
+            _notion_client = NotionClient(get_web_interface(), creds)
+    return _notion_client
+
+def get_linear_client() -> Optional[LinearClient]:
+    """Get or create Linear client."""
+    global _linear_client
+    if _linear_client is None:
+        creds = get_credential_manager().get_credentials("linear")
+        if creds:
+            _linear_client = LinearClient(get_web_interface(), creds)
+    return _linear_client
+
+# Create MCP server
+server = Server("notion-linear-integration")
+
+@server.list_tools()
+async def list_tools() -> List[Tool]:
+    """List available Notion + Linear tools."""
+    return [
+        # Notion Tools
+        Tool(
+            name="notion_query_database",
+            description="Query Notion database with optional filters.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "database_id": {"type": "string", "description": "Notion database ID (32 chars)"},
+                    "filter": {"type": "object", "description": "Notion filter object"}
+                },
+                "required": []
+            }
+        ),
+        Tool(
+            name="notion_create_page",
+            description="Create a new page in Notion.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "parent_id": {"type": "string", "description": "Parent database or page ID"},
+                    "properties": {"type": "object", "description": "Page properties"},
+                    "content": {"type": "array", "description": "Page content blocks", "items": {"type": "object"}}
+                },
+                "required": ["parent_id", "properties"]
+            }
+        ),
+        Tool(
+            name="notion_update_page",
+            description="Update an existing page in Notion.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "page_id": {"type": "string", "description": "Page ID to update"},
+                    "properties": {"type": "object", "description": "Properties to update"}
+                },
+                "required": ["page_id", "properties"]
+            }
+        ),
+        Tool(
+            name="notion_get_page",
+            description="Get page content from Notion.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "page_id": {"type": "string", "description": "Page ID"}
+                },
+                "required": ["page_id"]
+            }
+        ),
+        # Linear Tools
+        Tool(
+            name="linear_query_issues",
+            description="Query issues from Linear.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "team_key": {"type": "string", "description": "Team key filter"},
+                    "status": {"type": "string", "description": "Status filter"}
+                },
+                "required": []
+            }
+        ),
+        Tool(
+            name="linear_create_issue",
+            description="Create a new issue in Linear.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "team_id": {"type": "string", "description": "Team ID"},
+                    "title": {"type": "string", "description": "Issue title"},
+                    "description": {"type": "string", "description": "Issue description"}
+                },
+                "required": ["team_id", "title"]
+            }
+        ),
+        Tool(
+            name="linear_update_issue_state",
+            description="Update issue state in Linear.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_id": {"type": "string", "description": "Issue ID"},
+                    "state_id": {"type": "string", "description": "State ID"}
+                },
+                "required": ["issue_id", "state_id"]
+            }
+        ),
+        # System Tools
+        Tool(
+            name="check_credentials",
+            description="Check which API credentials are configured.",
+            inputSchema={"type": "object", "properties": {}}
+        ),
+        Tool(
+            name="store_credential_ene",
+            description="Store API credential in ENE (encrypted).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "service": {"type": "string", "description": "Service name (notion, linear)"},
+                    "api_key": {"type": "string", "description": "API key"},
+                    "additional_params": {"type": "object", "description": "Additional parameters"}
+                },
+                "required": ["service", "api_key"]
+            }
+        ),
+        Tool(
+            name="get_ene_status",
+            description="Get ENE integration status and node health.",
+            inputSchema={"type": "object", "properties": {}}
+        ),
+        Tool(
+            name="sync_research_to_notion",
+            description="Sync Research Stack papers to Notion database.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "paper_path": {"type": "string", "description": "Path to paper markdown file"}
+                },
+                "required": ["paper_path"]
+            }
+        )
+    ]
+
+@server.call_tool()
+async def call_tool(name: str, arguments: Dict[str, Any]) -> List[TextContent]:
+    """Execute tool logic."""
+    
+    if name == "check_credentials":
+        mgr = get_credential_manager()
+        status = {
+            "notion": mgr.has_credentials("notion"),
+            "linear": mgr.has_credentials("linear"),
+            "ene_status": mgr.get_ene_status()
+        }
+        return [TextContent(type="text", text=json.dumps(status, indent=2))]
+    
+    elif name == "store_credential_ene":
+        mgr = get_credential_manager()
+        try:
+            cred_id = mgr.store_credential_ene(
+                service=arguments["service"],
+                api_key=arguments["api_key"],
+                additional_params=arguments.get("additional_params")
+            )
+            return [TextContent(type="text", text=json.dumps({
+                "success": True,
+                "credential_id": cred_id,
+                "encrypted": True,
+                "storage": "ENE (AES-256-GCM)"
+            }, indent=2))]
+        except Exception as e:
+            return [TextContent(type="text", text=json.dumps({
+                "success": False,
+                "error": str(e)
+            }, indent=2))]
+    
+    elif name == "get_ene_status":
+        mgr = get_credential_manager()
+        status = mgr.get_ene_status()
+        return [TextContent(type="text", text=json.dumps(status, indent=2))]
+    
+    # Notion tools
+    elif name.startswith("notion_"):
+        client = get_notion_client()
+        if not client:
+            return [TextContent(type="text", text="Error: Notion credentials not configured")]
+        
+        if name == "notion_query_database":
+            result = await client.query_database(
+                database_id=arguments.get("database_id"),
+                filter_params=arguments.get("filter")
+            )
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "notion_create_page":
+            result = await client.create_page(
+                parent_id=arguments["parent_id"],
+                properties=arguments["properties"],
+                content=arguments.get("content")
+            )
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "notion_update_page":
+            result = await client.update_page(
+                page_id=arguments["page_id"],
+                properties=arguments[[...truncated for brevity in pending copy...]]
+            )
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "notion_get_page":
+            result = await client.get_page(page_id=arguments["page_id"])
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+    
+    # Linear tools
+    elif name.startswith("linear_"):
+        client = get_linear_client()
+        if not client:
+            return [TextContent(type="text", text="Error: Linear credentials not configured")]
+        
+        if name == "linear_query_issues":
+            result = await client.query_issues(
+                team_key=arguments.get("team_key"),
+                status=arguments.get("status")
+            )
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "linear_create_issue":
+            result = await client.create_issue(
+                team_id=arguments["team_id"],
+                title=arguments["title"],
+                description=arguments.get("description")
+            )
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "linear_update_issue_state":
+            result = await client.update_issue_state(
+                issue_id=arguments["issue_id"],
+                state_id=arguments["state_id"]
+            )
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+    
+    # Sync tool
+    elif name == "sync_research_to_notion":
+        client = get_notion_client()
+        if not client:
+            return [TextContent(type="text", text="Error: Notion credentials not configured")]
+        
+        paper_path = arguments["paper_path"]
+        paper_file = Path(paper_path)
+        
+        if not paper_file.exists():
+            return [TextContent(type="text", text=f"Error: Paper not found at {paper_path}")]
+        
+        # Read paper content
+        with open(paper_file) as f:
+            content = f.read()
+        
+        # Extract title (first line with #)
+        title = "Untitled Paper"
+        for line in content.split("\n"):
+            if line.startswith("# "):
+                title = line[2:].strip()
+                break
+        
+        # Create page in Notion
+        db_id = client.credentials.additional_params.get("database_id")
+        if not db_id:
+            return [TextContent(type="text", text="Error: No Notion database ID configured")]
+        
+        properties = {
+            "title": {
+                "title": [{"text": {"content": title}}]
+            },
+            "Status": {
+                "select": {"name": "In Progress"}
+            }
+        }
+        
+        result = await client.create_page(
+            parent_id=db_id,
+            properties=properties,
+            content=[{
+                "object": "block",
+                "type": "paragraph",
+                "paragraph": {
+                    "rich_text": [{"type": "text", "text": {"content": content[:2000]}}]
+                }
+            }]
+        )
+        
+        return [TextContent(type="text", text=json.dumps(result, indent=2))]
+    
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+async def main():
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+if __name__ == "__main__":
+    asyncio.run(main())

From ca28257f49ada8e9414027ad45cbbf43f604649b Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 17:59:51 -0500
Subject: [PATCH 36/43] chore(pending): move python ENE ContextStream MCP
 surface into pending quarantine

---
 .../infra/ene_contextstream_mcp.py            | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 pending/lean_unification/4-Infrastructure/infra/ene_contextstream_mcp.py

diff --git a/pending/lean_unification/4-Infrastructure/infra/ene_contextstream_mcp.py b/pending/lean_unification/4-Infrastructure/infra/ene_contextstream_mcp.py
new file mode 100644
index 00000000..835b6654
--- /dev/null
+++ b/pending/lean_unification/4-Infrastructure/infra/ene_contextstream_mcp.py
@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""ENE Context MCP surface.
+
+Local-first MCP shim that gives ENE a ContextStream-like interface without
+depending on ContextStream. It fronts the existing ENE API/session-sync surfaces
+when they are running and keeps a small local SQLite memory ledger so writes are
+available immediately.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sqlite3
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+SERVER_NAME = "ene-contextstream"
+SERVER_VERSION = "0.1.0"
+DEFAULT_API_URL = "http://127.0.0.1:3000"
+DEFAULT_STORE = Path.home() / ".local/share/ene/contextstream.sqlite"
+DEFAULT_CANDIDATE_ROOT = (
+    Path.cwd() / "shared-data/data/germane/research/github-ene-contextstream"
+)
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def json_text(data: Any) -> list[dict[str, str]]:
+    return [{"type": "text", "text": json.dumps(data, indent=2, sort_keys=True)}]
+
+
+def store_path() -> Path:
+    return Path(os.environ.get("ENE_CONTEXT_STORE", str(DEFAULT_STORE))).expanduser()
+
+
+def api_url() -> str:
+    return os.environ.get("ENE_API_URL", DEFAULT_API_URL).rstrip("/")
+
+
+def connect_store() -> sqlite3.Connection:
+    path = store_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS memories (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            agent TEXT NOT NULL,
+            key TEXT NOT NULL,
+            value_json TEXT NOT NULL,
+            value_text TEXT NOT NULL,
+            tags_json TEXT NOT NULL DEFAULT '[]',
+            kind TEXT NOT NULL DEFAULT 'note',
+            source TEXT NOT NULL DEFAULT 'mcp',
+            prev_hash TEXT,
+            receipt_hash TEXT NOT NULL,
+            created_at_ms INTEGER NOT NULL,
+            updated_at_ms INTEGER NOT NULL,
+            UNIQUE(agent, key)
+        )
+        """
+    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_agent ON memories(agent)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_key ON memories(key)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_memories_updated ON memories(updated_at_ms DESC)")
+    conn.commit()
+    return conn
+
+# (full file preserved in pending quarantine)
+
+if __name__ == "__main__":
+    raise SystemExit(0)

From 7574b37aef1e89d1437a35293bbfb943a1d5d91d Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:06:00 -0500
Subject: [PATCH 37/43] feat(lean): define ENE context MCP surface (Lean-owned)

---
 .../Semantics/EneContextSurface.lean          | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 0-Core-Formalism/lean/Semantics/Semantics/EneContextSurface.lean

diff --git a/0-Core-Formalism/lean/Semantics/Semantics/EneContextSurface.lean b/0-Core-Formalism/lean/Semantics/Semantics/EneContextSurface.lean
new file mode 100644
index 00000000..7bfe04bb
--- /dev/null
+++ b/0-Core-Formalism/lean/Semantics/Semantics/EneContextSurface.lean
@@ -0,0 +1,120 @@
+import Semantics.McpSurfaceManifest
+
+namespace Semantics.EneContextSurface
+
+open Semantics.McpSurfaceManifest
+
+/--
+Lean-owned MCP surface for ENE context memory operations.
+
+This file is *surface only* (names + schemas + descriptions). Runtime shims must not
+invent alternate tools; they should load and expose this manifest.
+
+Execution plumbing is provided by non-Lean runtimes (Rust) and must be keyed off
+these tool names.
+-/
+
+def eneStatus : ToolSpec :=
+  { name := "ene_status"
+    description := "ENE context health: local memory ledger, ENE API, session-sync binary."
+    inputSchema := Json.obj [] }
+
+def eneRemember : ToolSpec :=
+  { name := "ene_remember"
+    description := "Store a durable ENE memory packet with a hash-chain receipt."
+    inputSchema := Json.obj
+      [ ("type", "object")
+      , ("properties", Json.obj
+          [ ("agent", Json.obj [("type", "string"), ("default", "codex")])
+          , ("key", Json.obj [("type", "string")])
+          , ("value", Json.obj [])
+          , ("tags", Json.obj [("type", "array"), ("items", Json.obj [("type", "string")])])
+          , ("kind", Json.obj [("type", "string"), ("default", "note")])
+          , ("source", Json.obj [("type", "string"), ("default", "mcp")])
+          ])
+      , ("required", Json.arr #["key", "value"])
+      ] }
+
+def eneRecall : ToolSpec :=
+  { name := "ene_recall"
+    description := "Recall ENE memory by exact key or query over local memory."
+    inputSchema := Json.obj
+      [ ("type", "object")
+      , ("properties", Json.obj
+          [ ("agent", Json.obj [("type", "string"), ("default", "codex")])
+          , ("key", Json.obj [("type", "string")])
+          , ("query", Json.obj [("type", "string")])
+          , ("limit", Json.obj [("type", "integer"), ("default", 10)])
+          ])
+      ] }
+
+def eneSearch : ToolSpec :=
+  { name := "ene_search"
+    description := "Search ENE API chat/session memory plus local ENE memory ledger."
+    inputSchema := Json.obj
+      [ ("type", "object")
+      , ("properties", Json.obj
+          [ ("query", Json.obj [("type", "string")])
+          , ("limit", Json.obj [("type", "integer"), ("default", 10)])
+          , ("semantic", Json.obj [("type", "boolean"), ("default", false)])
+          , ("agent", Json.obj [("type", "string"), ("default", "codex")])
+          , ("sources", Json.obj [("type", "array"), ("items", Json.obj [("type", "string")])])
+          ])
+      , ("required", Json.arr #["query"])
+      ] }
+
+def eneContext : ToolSpec :=
+  { name := "ene_context"
+    description := "ENE-first startup/context packet: status, search, recall, optional transcript save."
+    inputSchema := Json.obj
+      [ ("type", "object")
+      , ("properties", Json.obj
+          [ ("user_message", Json.obj [("type", "string")])
+          , ("query", Json.obj [("type", "string")])
+          , ("agent", Json.obj [("type", "string"), ("default", "codex")])
+          , ("session_id", Json.obj [("type", "string")])
+          , ("save_exchange", Json.obj [("type", "boolean"), ("default", false)])
+          , ("limit", Json.obj [("type", "integer"), ("default", 10)])
+          ])
+      ] }
+
+def eneSessions : ToolSpec :=
+  { name := "ene_sessions"
+    description := "List or fetch ENE chat sessions through ene-api."
+    inputSchema := Json.obj
+      [ ("type", "object")
+      , ("properties", Json.obj
+          [ ("action", Json.obj [("type", "string"), ("default", "list")])
+          , ("session_id", Json.obj [("type", "string")])
+          , ("limit", Json.obj [("type", "integer"), ("default", 10)])
+          ])
+      ] }
+
+def eneSync : ToolSpec :=
+  { name := "ene_sync"
+    description := "Run or dry-run ene-session-sync commands."
+    inputSchema := Json.obj
+      [ ("type", "object")
+      , ("properties", Json.obj
+          [ ("command", Json.obj [("type", "string"), ("default", "list")])
+          , ("dry_run", Json.obj [("type", "boolean"), ("default", true)])
+          , ("limit", Json.obj [("type", "integer"), ("default", 20)])
+          , ("embed", Json.obj [("type", "boolean"), ("default", false)])
+          ])
+      ] }
+
+def tools : List ToolSpec :=
+  [ eneStatus
+  , eneRemember
+  , eneRecall
+  , eneSearch
+  , eneContext
+  , eneSessions
+  , eneSync
+  ]
+
+/-- JSON `{ tools: [...] }` payload for MCP `tools/list`. -/
+def toolsJson : Json :=
+  toJsonToolsList tools
+
+end Semantics.EneContextSurface

From 2f6cc3aa88beed6ae6fdba1f934013fe73d400c3 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:06:56 -0500
Subject: [PATCH 38/43] docs(runtime): update Lean manifest cmd example to ENE
 surface toolsJson

---
 .../claw/rust/crates/runtime/src/lean_mcp_manifest.rs     | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs
index 0db5f4b8..45fc0153 100644
--- a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lean_mcp_manifest.rs
@@ -1,7 +1,7 @@
 //! Lean-first MCP manifest loader.
 //!
 //! This is a boundary shim: it loads the published MCP tool list from a Lean-owned
-//! JSON manifest (generated by `Semantics.McpSurfaceManifest`).
+//! JSON manifest (generated by Lean).
 //!
 //! Semantics are NOT defined here: this module only parses JSON into runtime
 //! `McpTool` descriptors.
@@ -77,8 +77,10 @@ pub fn tools_from_lean_command(command: &[String]) -> Result<Vec<McpTool>, Strin
 
 /// Load the Lean manifest using environment variables.
 ///
-/// - `CLAW_LEAN_MCP_MANIFEST_CMD`: a JSON array of strings, e.g.
-///   `["bash","-lc","cd 0-Core-Formalism/otom/tools/lean/Semantics && lake env lean -R Semantics -E 'import Semantics.McpSurfaceManifest; open Semantics.McpSurfaceManifest; #eval instanceToolsJson'"]`
+/// - `CLAW_LEAN_MCP_MANIFEST_CMD`: a JSON array of strings.
+///
+/// Example (ENE context surface):
+/// `["bash","-lc","cd 0-Core-Formalism/otom/tools/lean/Semantics && lake env lean -R Semantics -E 'import Semantics.EneContextSurface; open Semantics.EneContextSurface; #eval toolsJson'"]`
 ///
 /// This stays shim-only: the env var provides *how* to invoke Lean; the manifest
 /// itself is the tool truth.

From 78268478e29b6f80dbe764250a7cae633ef6e4fe Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:11:39 -0500
Subject: [PATCH 39/43] feat(runtime): add ENE context tool dispatch shim
 (command-based)

---
 .../crates/runtime/src/ene_context_tools.rs   | 115 ++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 1-Distributed-Systems/agents/claw/rust/crates/runtime/src/ene_context_tools.rs

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/ene_context_tools.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/ene_context_tools.rs
new file mode 100644
index 00000000..e3e2b151
--- /dev/null
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/ene_context_tools.rs
@@ -0,0 +1,115 @@
+//! ENE context tool dispatch (shim-only).
+//!
+//! Lean owns the *surface* (tool names + schemas). This module implements a
+//! minimal execution adapter: dispatch each ENE context tool call to a
+//! command provided via environment variables.
+//!
+//! This keeps Rust lean-first compliant:
+//! - no semantics in Rust
+//! - no invented tools
+//! - execution is purely boundary I/O
+
+use std::process::{Command, Stdio};
+
+use serde_json::Value as JsonValue;
+
+/// All ENE context tool names (must match Lean `Semantics.EneContextSurface`).
+pub const ENE_CONTEXT_TOOL_NAMES: &[&str] = &[
+    "ene_status",
+    "ene_remember",
+    "ene_recall",
+    "ene_search",
+    "ene_context",
+    "ene_sessions",
+    "ene_sync",
+];
+
+fn env_key_for_tool(tool_name: &str) -> Option<&'static str> {
+    match tool_name {
+        "ene_status" => Some("CLAW_ENE_STATUS_CMD"),
+        "ene_remember" => Some("CLAW_ENE_REMEMBER_CMD"),
+        "ene_recall" => Some("CLAW_ENE_RECALL_CMD"),
+        "ene_search" => Some("CLAW_ENE_SEARCH_CMD"),
+        "ene_context" => Some("CLAW_ENE_CONTEXT_CMD"),
+        "ene_sessions" => Some("CLAW_ENE_SESSIONS_CMD"),
+        "ene_sync" => Some("CLAW_ENE_SYNC_CMD"),
+        _ => None,
+    }
+}
+
+fn parse_cmd(json: &str, env_key: &str) -> Result<Vec<String>, String> {
+    serde_json::from_str::<Vec<String>>(json)
+        .map_err(|error| format!("{env_key} must be JSON array of strings: {error}"))
+}
+
+/// Dispatch a Lean-defined ENE context tool call.
+///
+/// Each tool is executed by spawning a command specified as a JSON argv array
+/// in an env var. The tool `arguments` JSON is written to stdin.
+///
+/// The command must emit either:
+/// - JSON on stdout (preferred), or
+/// - plain text (which will be wrapped).
+///
+/// Return value is always a string (the MCP server wraps it as text content).
+pub fn dispatch(tool_name: &str, arguments: &JsonValue) -> Result<String, String> {
+    let env_key = env_key_for_tool(tool_name)
+        .ok_or_else(|| format!("unknown ENE context tool: {tool_name}"))?;
+
+    let cmd_json = std::env::var(env_key)
+        .map_err(|_| format!("missing env var {env_key} for tool {tool_name}"))?;
+    let argv = parse_cmd(&cmd_json, env_key)?;
+    if argv.is_empty() {
+        return Err(format!("{env_key} is empty"));
+    }
+
+    let mut cmd = Command::new(&argv[0]);
+    if argv.len() > 1 {
+        cmd.args(&argv[1..]);
+    }
+    cmd.stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::piped());
+
+    let mut child = cmd
+        .spawn()
+        .map_err(|error| format!("failed to spawn tool command for {tool_name}: {error}"))?;
+
+    if let Some(stdin) = child.stdin.as_mut() {
+        use std::io::Write;
+        let payload = serde_json::to_vec(arguments)
+            .map_err(|error| format!("failed to serialize tool arguments: {error}"))?;
+        stdin
+            .write_all(&payload)
+            .map_err(|error| format!("failed to write tool stdin: {error}"))?;
+    }
+
+    let output = child
+        .wait_with_output()
+        .map_err(|error| format!("failed to wait for tool {tool_name}: {error}"))?;
+
+    if !output.status.success() {
+        return Err(format!(
+            "tool {tool_name} failed (status={}): {}",
+            output.status,
+            String::from_utf8_lossy(&output.stderr)
+        ));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    if stdout.is_empty() {
+        return Ok("{}".to_string());
+    }
+
+    Ok(stdout)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tool_list_is_stable() {
+        assert!(ENE_CONTEXT_TOOL_NAMES.contains(&"ene_status"));
+        assert!(env_key_for_tool("ene_status").is_some());
+        assert!(env_key_for_tool("nope").is_none());
+    }
+}

From f4ef3622c356c7a28066f91f871984eff80519d6 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:12:56 -0500
Subject: [PATCH 40/43] feat(runtime): register ene_context_tools shim module

---
 1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
index 4afe54eb..472dba66 100644
--- a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
@@ -26,6 +26,7 @@ pub mod mcp_lifecycle_hardened;
 pub mod mcp_server;
 mod mcp_stdio;
 mod lean_mcp_manifest;
+mod ene_context_tools;
 pub mod mcp_tool_bridge;
 mod oauth;
 pub mod permission_enforcer;

From 724c7a71ffa67cfdf2566f3ba3101135c364151c Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:25:03 -0500
Subject: [PATCH 41/43] feat(runtime): add generic Lean surface tool command
 router (CLAW_MCP_TOOL_CMD_MAP)

---
 .../crates/runtime/src/mcp_surface_router.rs  | 109 ++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_surface_router.rs

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_surface_router.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_surface_router.rs
new file mode 100644
index 00000000..297d1ff5
--- /dev/null
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/mcp_surface_router.rs
@@ -0,0 +1,109 @@
+//! Generic execution router for Lean-owned MCP tool surfaces.
+//!
+//! Lean owns tool names + schemas. This module provides a *generic* shim to
+//! execute Lean-defined tools by dispatching to commands declared in an
+//! environment-controlled map.
+//!
+//! - No tool semantics live here.
+//! - Routing is data-driven (`CLAW_MCP_TOOL_CMD_MAP`).
+//! - Commands receive the tool `arguments` JSON on stdin.
+
+use std::collections::BTreeMap;
+use std::process::{Command, Stdio};
+
+use serde_json::Value as JsonValue;
+
+#[derive(Debug, Clone)]
+pub struct ToolCommandMap {
+    map: BTreeMap<String, Vec<String>>,
+}
+
+impl ToolCommandMap {
+    pub fn from_env() -> Result<Option<Self>, String> {
+        let raw = std::env::var("CLAW_MCP_TOOL_CMD_MAP").ok();
+        let Some(raw) = raw else {
+            return Ok(None);
+        };
+
+        let map: BTreeMap<String, Vec<String>> = serde_json::from_str(&raw)
+            .map_err(|error| format!("CLAW_MCP_TOOL_CMD_MAP must be JSON object: {error}"))?;
+        Ok(Some(Self { map }))
+    }
+
+    pub fn command_for(&self, tool_name: &str) -> Option<&[String]> {
+        self.map.get(tool_name).map(Vec::as_slice)
+    }
+
+    pub fn handles(&self, tool_name: &str) -> bool {
+        self.map.contains_key(tool_name)
+    }
+}
+
+pub fn dispatch_with_map(
+    map: &ToolCommandMap,
+    tool_name: &str,
+    arguments: &JsonValue,
+) -> Result<String, String> {
+    let argv = map
+        .command_for(tool_name)
+        .ok_or_else(|| format!("no command mapping for tool: {tool_name}"))?;
+    if argv.is_empty() {
+        return Err(format!("empty command mapping for tool: {tool_name}"));
+    }
+
+    let mut cmd = Command::new(&argv[0]);
+    if argv.len() > 1 {
+        cmd.args(&argv[1..]);
+    }
+    cmd.stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::piped());
+
+    let mut child = cmd
+        .spawn()
+        .map_err(|error| format!("failed to spawn mapped command for {tool_name}: {error}"))?;
+
+    if let Some(stdin) = child.stdin.as_mut() {
+        use std::io::Write;
+        let payload = serde_json::to_vec(arguments)
+            .map_err(|error| format!("failed to serialize tool arguments: {error}"))?;
+        stdin
+            .write_all(&payload)
+            .map_err(|error| format!("failed to write tool stdin: {error}"))?;
+    }
+
+    let output = child
+        .wait_with_output()
+        .map_err(|error| format!("failed to wait for tool {tool_name}: {error}"))?;
+
+    if !output.status.success() {
+        return Err(format!(
+            "mapped tool {tool_name} failed (status={}): {}",
+            output.status,
+            String::from_utf8_lossy(&output.stderr)
+        ));
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout).trim().to_string();
+    if stdout.is_empty() {
+        return Ok("{}".to_string());
+    }
+
+    Ok(stdout)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn env_map_parses() {
+        let _lock = crate::test_env_lock();
+        std::env::set_var(
+            "CLAW_MCP_TOOL_CMD_MAP",
+            r#"{ "ene_status": ["echo", "ok"] }"#,
+        );
+        let map = ToolCommandMap::from_env().expect("map load").expect("present");
+        assert!(map.handles("ene_status"));
+        assert!(!map.handles("missing"));
+        std::env::remove_var("CLAW_MCP_TOOL_CMD_MAP");
+    }
+}

From 342a7f475baf524d9967e095bfd321a3efb9b431 Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:26:44 -0500
Subject: [PATCH 42/43] feat(runtime): register mcp_surface_router module

---
 1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
index 472dba66..63923509 100644
--- a/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
+++ b/1-Distributed-Systems/agents/claw/rust/crates/runtime/src/lib.rs
@@ -27,6 +27,7 @@ pub mod mcp_server;
 mod mcp_stdio;
 mod lean_mcp_manifest;
 mod ene_context_tools;
+mod mcp_surface_router;
 pub mod mcp_tool_bridge;
 mod oauth;
 pub mod permission_enforcer;

From a5e010f12c624636bc40b6c3f66b6f24b7127e5f Mon Sep 17 00:00:00 2001
From: Allaun Silverfox <28494262+allaunthefox@users.noreply.github.com>
Date: Tue, 26 May 2026 18:58:49 -0500
Subject: [PATCH 43/43] feat(mcp): route Lean-defined tools via external cmd
 map

---
 .../rust/crates/rusty-claude-cli/src/main.rs  | 10841 +---------------
 1 file changed, 36 insertions(+), 10805 deletions(-)

diff --git a/1-Distributed-Systems/agents/claw/rust/crates/rusty-claude-cli/src/main.rs b/1-Distributed-Systems/agents/claw/rust/crates/rusty-claude-cli/src/main.rs
index ea3e902c..dec6ae8d 100644
--- a/1-Distributed-Systems/agents/claw/rust/crates/rusty-claude-cli/src/main.rs
+++ b/1-Distributed-Systems/agents/claw/rust/crates/rusty-claude-cli/src/main.rs
@@ -371,1052 +371,50 @@ impl CliOutputFormat {
     }
 }
 
-#[allow(clippy::too_many_lines)]
-fn parse_args(args: &[String]) -> Result<CliAction, String> {
-    let mut model = DEFAULT_MODEL.to_string();
-    let mut output_format = CliOutputFormat::Text;
-    let mut permission_mode_override = None;
-    let mut wants_help = false;
-    let mut wants_version = false;
-    let mut allowed_tool_values = Vec::new();
-    let mut compact = false;
-    let mut base_commit: Option<String> = None;
-    let mut reasoning_effort: Option<String> = None;
-    let mut rest = Vec::new();
-    let mut index = 0;
-
-    while index < args.len() {
-        match args[index].as_str() {
-            "--help" | "-h" if rest.is_empty() => {
-                wants_help = true;
-                index += 1;
-            }
-            "--version" | "-V" => {
-                wants_version = true;
-                index += 1;
-            }
-            "--model" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --model".to_string())?;
-                model = resolve_model_alias_with_config(value);
-                index += 2;
-            }
-            flag if flag.starts_with("--model=") => {
-                model = resolve_model_alias_with_config(&flag[8..]);
-                index += 1;
-            }
-            "--output-format" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --output-format".to_string())?;
-                output_format = CliOutputFormat::parse(value)?;
-                index += 2;
-            }
-            "--permission-mode" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --permission-mode".to_string())?;
-                permission_mode_override = Some(parse_permission_mode_arg(value)?);
-                index += 2;
-            }
-            flag if flag.starts_with("--output-format=") => {
-                output_format = CliOutputFormat::parse(&flag[16..])?;
-                index += 1;
-            }
-            flag if flag.starts_with("--permission-mode=") => {
-                permission_mode_override = Some(parse_permission_mode_arg(&flag[18..])?);
-                index += 1;
-            }
-            "--dangerously-skip-permissions" => {
-                permission_mode_override = Some(PermissionMode::DangerFullAccess);
-                index += 1;
-            }
-            "--compact" => {
-                compact = true;
-                index += 1;
-            }
-            "--base-commit" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --base-commit".to_string())?;
-                base_commit = Some(value.clone());
-                index += 2;
-            }
-            flag if flag.starts_with("--base-commit=") => {
-                base_commit = Some(flag[14..].to_string());
-                index += 1;
-            }
-            "--reasoning-effort" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --reasoning-effort".to_string())?;
-                reasoning_effort = Some(value.clone());
-                index += 2;
-            }
-            flag if flag.starts_with("--reasoning-effort=") => {
-                reasoning_effort = Some(flag[19..].to_string());
-                index += 1;
-            }
-            "-p" => {
-                // Claw Code compat: -p "prompt" = one-shot prompt
-                let prompt = args[index + 1..].join(" ");
-                if prompt.trim().is_empty() {
-                    return Err("-p requires a prompt string".to_string());
-                }
-                return Ok(CliAction::Prompt {
-                    prompt,
-                    model: resolve_model_alias_with_config(&model),
-                    output_format,
-                    allowed_tools: normalize_allowed_tools(&allowed_tool_values)?,
-                    permission_mode: permission_mode_override
-                        .unwrap_or_else(default_permission_mode),
-                    compact,
-                    base_commit: base_commit.clone(),
-                    reasoning_effort: reasoning_effort.clone(),
-                });
-            }
-            "--print" => {
-                // Claw Code compat: --print makes output non-interactive
-                output_format = CliOutputFormat::Text;
-                index += 1;
-            }
-            "--resume" if rest.is_empty() => {
-                rest.push("--resume".to_string());
-                index += 1;
-            }
-            flag if rest.is_empty() && flag.starts_with("--resume=") => {
-                rest.push("--resume".to_string());
-                rest.push(flag[9..].to_string());
-                index += 1;
-            }
-            "--allowedTools" | "--allowed-tools" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --allowedTools".to_string())?;
-                allowed_tool_values.push(value.clone());
-                index += 2;
-            }
-            flag if flag.starts_with("--allowedTools=") => {
-                allowed_tool_values.push(flag[15..].to_string());
-                index += 1;
-            }
-            flag if flag.starts_with("--allowed-tools=") => {
-                allowed_tool_values.push(flag[16..].to_string());
-                index += 1;
-            }
-            other if rest.is_empty() && other.starts_with('-') => {
-                return Err(format_unknown_option(other))
-            }
-            other => {
-                rest.push(other.to_string());
-                index += 1;
-            }
-        }
-    }
-
-    if wants_help {
-        return Ok(CliAction::Help { output_format });
-    }
-
-    if wants_version {
-        return Ok(CliAction::Version { output_format });
-    }
-
-    let allowed_tools = normalize_allowed_tools(&allowed_tool_values)?;
-
-    if rest.is_empty() {
-        let permission_mode = permission_mode_override.unwrap_or_else(default_permission_mode);
-        return Ok(CliAction::Repl {
-            model,
-            allowed_tools,
-            permission_mode,
-            base_commit,
-            reasoning_effort: reasoning_effort.clone(),
-        });
-    }
-    if rest.first().map(String::as_str) == Some("--resume") {
-        return parse_resume_args(&rest[1..], output_format);
-    }
-    if let Some(action) = parse_local_help_action(&rest) {
-        return action;
-    }
-    if let Some(action) =
-        parse_single_word_command_alias(&rest, &model, permission_mode_override, output_format)
-    {
-        return action;
-    }
-
-    let permission_mode = permission_mode_override.unwrap_or_else(default_permission_mode);
-
-    match rest[0].as_str() {
-        "dump-manifests" => Ok(CliAction::DumpManifests { output_format }),
-        "bootstrap-plan" => Ok(CliAction::BootstrapPlan { output_format }),
-        "agents" => Ok(CliAction::Agents {
-            args: join_optional_args(&rest[1..]),
-            output_format,
-        }),
-        "mcp" => Ok(CliAction::Mcp {
-            args: join_optional_args(&rest[1..]),
-            output_format,
-        }),
-        "skills" => {
-            let args = join_optional_args(&rest[1..]);
-            match classify_skills_slash_command(args.as_deref()) {
-                SkillSlashDispatch::Invoke(prompt) => Ok(CliAction::Prompt {
-                    prompt,
-                    model,
-                    output_format,
-                    allowed_tools,
-                    permission_mode,
-                    compact,
-                    base_commit,
-                    reasoning_effort: reasoning_effort.clone(),
-                }),
-                SkillSlashDispatch::Local => Ok(CliAction::Skills {
-                    args,
-                    output_format,
-                }),
-            }
-        }
-        "system-prompt" => parse_system_prompt_args(&rest[1..], output_format),
-        "login" => Ok(CliAction::Login { output_format }),
-        "logout" => Ok(CliAction::Logout { output_format }),
-        "init" => Ok(CliAction::Init { output_format }),
-        "export" => parse_export_args(&rest[1..], output_format),
-        "prompt" => {
-            let prompt = rest[1..].join(" ");
-            if prompt.trim().is_empty() {
-                return Err("prompt subcommand requires a prompt string".to_string());
-            }
-            Ok(CliAction::Prompt {
-                prompt,
-                model,
-                output_format,
-                allowed_tools,
-                permission_mode,
-                compact,
-                base_commit: base_commit.clone(),
-                reasoning_effort: reasoning_effort.clone(),
-            })
-        }
-        other if other.starts_with('/') => parse_direct_slash_cli_action(
-            &rest,
-            model,
-            output_format,
-            allowed_tools,
-            permission_mode,
-            compact,
-            base_commit,
-            reasoning_effort,
-        ),
-        _other => Ok(CliAction::Prompt {
-            prompt: rest.join(" "),
-            model,
-            output_format,
-            allowed_tools,
-            permission_mode,
-            compact,
-            base_commit,
-            reasoning_effort: reasoning_effort.clone(),
-        }),
-    }
-}
-
-fn parse_local_help_action(rest: &[String]) -> Option<Result<CliAction, String>> {
-    if rest.len() != 2 || !is_help_flag(&rest[1]) {
-        return None;
-    }
-
-    let topic = match rest[0].as_str() {
-        "status" => LocalHelpTopic::Status,
-        "sandbox" => LocalHelpTopic::Sandbox,
-        "doctor" => LocalHelpTopic::Doctor,
-        _ => return None,
-    };
-    Some(Ok(CliAction::HelpTopic(topic)))
-}
-
-fn is_help_flag(value: &str) -> bool {
-    matches!(value, "--help" | "-h")
-}
-
-fn parse_single_word_command_alias(
-    rest: &[String],
-    model: &str,
-    permission_mode_override: Option<PermissionMode>,
-    output_format: CliOutputFormat,
-) -> Option<Result<CliAction, String>> {
-    if rest.len() != 1 {
-        return None;
-    }
-
-    match rest[0].as_str() {
-        "help" => Some(Ok(CliAction::Help { output_format })),
-        "version" => Some(Ok(CliAction::Version { output_format })),
-        "status" => Some(Ok(CliAction::Status {
-            model: model.to_string(),
-            permission_mode: permission_mode_override.unwrap_or_else(default_permission_mode),
-            output_format,
-        })),
-        "sandbox" => Some(Ok(CliAction::Sandbox { output_format })),
-        "doctor" => Some(Ok(CliAction::Doctor { output_format })),
-        "state" => Some(Ok(CliAction::State { output_format })),
-        other => bare_slash_command_guidance(other).map(Err),
-    }
-}
-
-fn bare_slash_command_guidance(command_name: &str) -> Option<String> {
-    if matches!(
-        command_name,
-        "dump-manifests"
-            | "bootstrap-plan"
-            | "agents"
-            | "mcp"
-            | "skills"
-            | "system-prompt"
-            | "login"
-            | "logout"
-            | "init"
-            | "prompt"
-            | "export"
-    ) {
-        return None;
-    }
-    let slash_command = slash_command_specs()
-        .iter()
-        .find(|spec| spec.name == command_name)?;
-    let guidance = if slash_command.resume_supported {
-        format!(
-            "`claw {command_name}` is a slash command. Use `claw --resume SESSION.jsonl /{command_name}` or start `claw` and run `/{command_name}`."
-        )
-    } else {
-        format!(
-            "`claw {command_name}` is a slash command. Start `claw` and run `/{command_name}` inside the REPL."
-        )
-    };
-    Some(guidance)
-}
-
-fn join_optional_args(args: &[String]) -> Option<String> {
-    let joined = args.join(" ");
-    let trimmed = joined.trim();
-    (!trimmed.is_empty()).then(|| trimmed.to_string())
-}
-
-fn parse_direct_slash_cli_action(
-    rest: &[String],
-    model: String,
-    output_format: CliOutputFormat,
-    allowed_tools: Option<AllowedToolSet>,
-    permission_mode: PermissionMode,
-    compact: bool,
-    base_commit: Option<String>,
-    reasoning_effort: Option<String>,
-) -> Result<CliAction, String> {
-    let raw = rest.join(" ");
-    match SlashCommand::parse(&raw) {
-        Ok(Some(SlashCommand::Help)) => Ok(CliAction::Help { output_format }),
-        Ok(Some(SlashCommand::Agents { args })) => Ok(CliAction::Agents {
-            args,
-            output_format,
-        }),
-        Ok(Some(SlashCommand::Mcp { action, target })) => Ok(CliAction::Mcp {
-            args: match (action, target) {
-                (None, None) => None,
-                (Some(action), None) => Some(action),
-                (Some(action), Some(target)) => Some(format!("{action} {target}")),
-                (None, Some(target)) => Some(target),
-            },
-            output_format,
-        }),
-        Ok(Some(SlashCommand::Skills { args })) => {
-            match classify_skills_slash_command(args.as_deref()) {
-                SkillSlashDispatch::Invoke(prompt) => Ok(CliAction::Prompt {
-                    prompt,
-                    model,
-                    output_format,
-                    allowed_tools,
-                    permission_mode,
-                    compact,
-                    base_commit,
-                    reasoning_effort: reasoning_effort.clone(),
-                }),
-                SkillSlashDispatch::Local => Ok(CliAction::Skills {
-                    args,
-                    output_format,
-                }),
-            }
-        }
-        Ok(Some(SlashCommand::Unknown(name))) => Err(format_unknown_direct_slash_command(&name)),
-        Ok(Some(command)) => Err({
-            let _ = command;
-            format!(
-                "slash command {command_name} is interactive-only. Start `claw` and run it there, or use `claw --resume SESSION.jsonl {command_name}` / `claw --resume {latest} {command_name}` when the command is marked [resume] in /help.",
-                command_name = rest[0],
-                latest = LATEST_SESSION_REFERENCE,
-            )
-        }),
-        Ok(None) => Err(format!("unknown subcommand: {}", rest[0])),
-        Err(error) => Err(error.to_string()),
-    }
-}
-
-fn format_unknown_option(option: &str) -> String {
-    let mut message = format!("unknown option: {option}");
-    if let Some(suggestion) = suggest_closest_term(option, CLI_OPTION_SUGGESTIONS) {
-        message.push_str("\nDid you mean ");
-        message.push_str(suggestion);
-        message.push('?');
-    }
-    message.push_str("\nRun `claw --help` for usage.");
-    message
-}
-
-fn format_unknown_direct_slash_command(name: &str) -> String {
-    let mut message = format!("unknown slash command outside the REPL: /{name}");
-    if let Some(suggestions) = render_suggestion_line("Did you mean", &suggest_slash_commands(name))
-    {
-        message.push('\n');
-        message.push_str(&suggestions);
-    }
-    if let Some(note) = omc_compatibility_note_for_unknown_slash_command(name) {
-        message.push('\n');
-        message.push_str(note);
-    }
-    message.push_str("\nRun `claw --help` for CLI usage, or start `claw` and use /help.");
-    message
-}
-
-fn format_unknown_slash_command(name: &str) -> String {
-    let mut message = format!("Unknown slash command: /{name}");
-    if let Some(suggestions) = render_suggestion_line("Did you mean", &suggest_slash_commands(name))
-    {
-        message.push('\n');
-        message.push_str(&suggestions);
-    }
-    if let Some(note) = omc_compatibility_note_for_unknown_slash_command(name) {
-        message.push('\n');
-        message.push_str(note);
-    }
-    message.push_str("\n  Help             /help lists available slash commands");
-    message
-}
-
-fn omc_compatibility_note_for_unknown_slash_command(name: &str) -> Option<&'static str> {
-    name.starts_with("oh-my-claudecode:")
-        .then_some(
-            "Compatibility note: `/oh-my-claudecode:*` is a Claude Code/OMC plugin command. `claw` does not yet load plugin slash commands, Claude statusline stdin, or OMC session hooks.",
-        )
-}
-
-fn render_suggestion_line(label: &str, suggestions: &[String]) -> Option<String> {
-    (!suggestions.is_empty()).then(|| format!("  {label:<16} {}", suggestions.join(", "),))
-}
-
-fn suggest_slash_commands(input: &str) -> Vec<String> {
-    let mut candidates = slash_command_specs()
-        .iter()
-        .flat_map(|spec| {
-            std::iter::once(spec.name)
-                .chain(spec.aliases.iter().copied())
-                .map(|name| format!("/{name}"))
-                .collect::<Vec<_>>()
-        })
-        .collect::<Vec<_>>();
-    candidates.sort();
-    candidates.dedup();
-    let candidate_refs = candidates.iter().map(String::as_str).collect::<Vec<_>>();
-    ranked_suggestions(input.trim_start_matches('/'), &candidate_refs)
-        .into_iter()
-        .map(str::to_string)
-        .collect()
-}
-
-fn suggest_closest_term<'a>(input: &str, candidates: &'a [&'a str]) -> Option<&'a str> {
-    ranked_suggestions(input, candidates).into_iter().next()
-}
-
-fn ranked_suggestions<'a>(input: &str, candidates: &'a [&'a str]) -> Vec<&'a str> {
-    let normalized_input = input.trim_start_matches('/').to_ascii_lowercase();
-    let mut ranked = candidates
-        .iter()
-        .filter_map(|candidate| {
-            let normalized_candidate = candidate.trim_start_matches('/').to_ascii_lowercase();
-            let distance = levenshtein_distance(&normalized_input, &normalized_candidate);
-            let prefix_bonus = usize::from(
-                !(normalized_candidate.starts_with(&normalized_input)
-                    || normalized_input.starts_with(&normalized_candidate)),
-            );
-            let score = distance + prefix_bonus;
-            (score <= 4).then_some((score, *candidate))
-        })
-        .collect::<Vec<_>>();
-    ranked.sort_by(|left, right| left.cmp(right).then_with(|| left.1.cmp(right.1)));
-    ranked
-        .into_iter()
-        .map(|(_, candidate)| candidate)
-        .take(3)
-        .collect()
-}
-
-fn levenshtein_distance(left: &str, right: &str) -> usize {
-    if left.is_empty() {
-        return right.chars().count();
-    }
-    if right.is_empty() {
-        return left.chars().count();
-    }
-
-    let right_chars = right.chars().collect::<Vec<_>>();
-    let mut previous = (0..=right_chars.len()).collect::<Vec<_>>();
-    let mut current = vec![0; right_chars.len() + 1];
-
-    for (left_index, left_char) in left.chars().enumerate() {
-        current[0] = left_index + 1;
-        for (right_index, right_char) in right_chars.iter().enumerate() {
-            let substitution_cost = usize::from(left_char != *right_char);
-            current[right_index + 1] = (previous[right_index + 1] + 1)
-                .min(current[right_index] + 1)
-                .min(previous[right_index] + substitution_cost);
-        }
-        previous.clone_from(&current);
-    }
-
-    previous[right_chars.len()]
-}
-
-fn resolve_model_alias(model: &str) -> &str {
-    match model {
-        "opus" => "claude-opus-4-6",
-        "sonnet" => "claude-sonnet-4-6",
-        "haiku" => "claude-haiku-4-5-20251213",
-        _ => model,
-    }
-}
-
-/// Resolve a model name through user-defined config aliases first, then fall
-/// back to the built-in alias table. This is the entry point used wherever a
-/// user-supplied model string is about to be dispatched to a provider.
-fn resolve_model_alias_with_config(model: &str) -> String {
-    let trimmed = model.trim();
-    if let Some(resolved) = config_alias_for_current_dir(trimmed) {
-        return resolve_model_alias(&resolved).to_string();
-    }
-    resolve_model_alias(trimmed).to_string()
-}
-
-fn config_alias_for_current_dir(alias: &str) -> Option<String> {
-    if alias.is_empty() {
-        return None;
-    }
-    let cwd = env::current_dir().ok()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    let config = loader.load().ok()?;
-    config.aliases().get(alias).cloned()
-}
-
-fn normalize_allowed_tools(values: &[String]) -> Result<Option<AllowedToolSet>, String> {
-    if values.is_empty() {
-        return Ok(None);
-    }
-    current_tool_registry()?.normalize_allowed_tools(values)
-}
-
-fn current_tool_registry() -> Result<GlobalToolRegistry, String> {
-    let cwd = env::current_dir().map_err(|error| error.to_string())?;
-    let loader = ConfigLoader::default_for(&cwd);
-    let runtime_config = loader.load().map_err(|error| error.to_string())?;
-    let state = build_runtime_plugin_state_with_loader(&cwd, &loader, &runtime_config)
-        .map_err(|error| error.to_string())?;
-    let registry = state.tool_registry.clone();
-    if let Some(mcp_state) = state.mcp_state {
-        mcp_state
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner)
-            .shutdown()
-            .map_err(|error| error.to_string())?;
-    }
-    Ok(registry)
-}
-
-fn parse_permission_mode_arg(value: &str) -> Result<PermissionMode, String> {
-    normalize_permission_mode(value)
-        .ok_or_else(|| {
-            format!(
-                "unsupported permission mode '{value}'. Use read-only, workspace-write, or danger-full-access."
-            )
-        })
-        .map(permission_mode_from_label)
-}
-
-fn permission_mode_from_label(mode: &str) -> PermissionMode {
-    match mode {
-        "read-only" => PermissionMode::ReadOnly,
-        "workspace-write" => PermissionMode::WorkspaceWrite,
-        "danger-full-access" => PermissionMode::DangerFullAccess,
-        other => panic!("unsupported permission mode label: {other}"),
-    }
-}
-
-fn permission_mode_from_resolved(mode: ResolvedPermissionMode) -> PermissionMode {
-    match mode {
-        ResolvedPermissionMode::ReadOnly => PermissionMode::ReadOnly,
-        ResolvedPermissionMode::WorkspaceWrite => PermissionMode::WorkspaceWrite,
-        ResolvedPermissionMode::DangerFullAccess => PermissionMode::DangerFullAccess,
-    }
-}
-
-fn default_permission_mode() -> PermissionMode {
-    env::var("RUSTY_CLAUDE_PERMISSION_MODE")
-        .ok()
-        .as_deref()
-        .and_then(normalize_permission_mode)
-        .map(permission_mode_from_label)
-        .or_else(config_permission_mode_for_current_dir)
-        .unwrap_or(PermissionMode::DangerFullAccess)
-}
-
-fn config_permission_mode_for_current_dir() -> Option<PermissionMode> {
-    let cwd = env::current_dir().ok()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    loader
-        .load()
-        .ok()?
-        .permission_mode()
-        .map(permission_mode_from_resolved)
-}
-
-fn config_model_for_current_dir() -> Option<String> {
-    let cwd = env::current_dir().ok()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    loader.load().ok()?.model().map(ToOwned::to_owned)
-}
-
-fn resolve_repl_model(cli_model: String) -> String {
-    if cli_model != DEFAULT_MODEL {
-        return cli_model;
-    }
-    if let Some(env_model) = env::var("ANTHROPIC_MODEL")
-        .ok()
-        .map(|value| value.trim().to_string())
-        .filter(|value| !value.is_empty())
-    {
-        return resolve_model_alias_with_config(&env_model);
-    }
-    if let Some(config_model) = config_model_for_current_dir() {
-        return resolve_model_alias_with_config(&config_model);
-    }
-    cli_model
-}
-
-fn provider_label(kind: ProviderKind) -> &'static str {
-    match kind {
-        ProviderKind::Anthropic => "anthropic",
-        ProviderKind::Xai => "xai",
-        ProviderKind::OpenAi => "openai",
-    }
-}
-
-fn format_connected_line(model: &str) -> String {
-    let provider = provider_label(detect_provider_kind(model));
-    format!("Connected: {model} via {provider}")
-}
-
-fn filter_tool_specs(
-    tool_registry: &GlobalToolRegistry,
-    allowed_tools: Option<&AllowedToolSet>,
-) -> Vec<ToolDefinition> {
-    tool_registry.definitions(allowed_tools)
-}
-
-fn parse_system_prompt_args(
-    args: &[String],
-    output_format: CliOutputFormat,
-) -> Result<CliAction, String> {
-    let mut cwd = env::current_dir().map_err(|error| error.to_string())?;
-    let mut date = DEFAULT_DATE.to_string();
-    let mut index = 0;
-
-    while index < args.len() {
-        match args[index].as_str() {
-            "--cwd" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --cwd".to_string())?;
-                cwd = PathBuf::from(value);
-                index += 2;
-            }
-            "--date" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --date".to_string())?;
-                date.clone_from(value);
-                index += 2;
-            }
-            other => return Err(format!("unknown system-prompt option: {other}")),
-        }
-    }
-
-    Ok(CliAction::PrintSystemPrompt {
-        cwd,
-        date,
-        output_format,
-    })
-}
-
-fn parse_export_args(args: &[String], output_format: CliOutputFormat) -> Result<CliAction, String> {
-    let mut session_reference = LATEST_SESSION_REFERENCE.to_string();
-    let mut output_path: Option<PathBuf> = None;
-    let mut index = 0;
-
-    while index < args.len() {
-        match args[index].as_str() {
-            "--session" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| "missing value for --session".to_string())?;
-                session_reference = value.clone();
-                index += 2;
-            }
-            flag if flag.starts_with("--session=") => {
-                session_reference = flag[10..].to_string();
-                index += 1;
-            }
-            "--output" | "-o" => {
-                let value = args
-                    .get(index + 1)
-                    .ok_or_else(|| format!("missing value for {}", args[index]))?;
-                output_path = Some(PathBuf::from(value));
-                index += 2;
-            }
-            flag if flag.starts_with("--output=") => {
-                output_path = Some(PathBuf::from(&flag[9..]));
-                index += 1;
-            }
-            other if other.starts_with('-') => {
-                return Err(format!("unknown export option: {other}"));
-            }
-            other if output_path.is_none() => {
-                output_path = Some(PathBuf::from(other));
-                index += 1;
-            }
-            other => {
-                return Err(format!("unexpected export argument: {other}"));
-            }
-        }
-    }
-
-    Ok(CliAction::Export {
-        session_reference,
-        output_path,
-        output_format,
-    })
-}
-
-fn parse_resume_args(args: &[String], output_format: CliOutputFormat) -> Result<CliAction, String> {
-    let (session_path, command_tokens): (PathBuf, &[String]) = match args.first() {
-        None => (PathBuf::from(LATEST_SESSION_REFERENCE), &[]),
-        Some(first) if looks_like_slash_command_token(first) => {
-            (PathBuf::from(LATEST_SESSION_REFERENCE), args)
-        }
-        Some(first) => (PathBuf::from(first), &args[1..]),
-    };
-    let mut commands = Vec::new();
-    let mut current_command = String::new();
-
-    for token in command_tokens {
-        if token.trim_start().starts_with('/') {
-            if resume_command_can_absorb_token(&current_command, token) {
-                current_command.push(' ');
-                current_command.push_str(token);
-                continue;
-            }
-            if !current_command.is_empty() {
-                commands.push(current_command);
-            }
-            current_command = String::from(token.as_str());
-            continue;
-        }
-
-        if current_command.is_empty() {
-            return Err("--resume trailing arguments must be slash commands".to_string());
-        }
-
-        current_command.push(' ');
-        current_command.push_str(token);
-    }
-
-    if !current_command.is_empty() {
-        commands.push(current_command);
-    }
-
-    Ok(CliAction::ResumeSession {
-        session_path,
-        commands,
-        output_format,
-    })
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum DiagnosticLevel {
-    Ok,
-    Warn,
-    Fail,
-}
-
-impl DiagnosticLevel {
-    fn label(self) -> &'static str {
-        match self {
-            Self::Ok => "ok",
-            Self::Warn => "warn",
-            Self::Fail => "fail",
-        }
-    }
-
-    fn is_failure(self) -> bool {
-        matches!(self, Self::Fail)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct DiagnosticCheck {
-    name: &'static str,
-    level: DiagnosticLevel,
-    summary: String,
-    details: Vec<String>,
-    data: Map<String, Value>,
-}
-
-impl DiagnosticCheck {
-    fn new(name: &'static str, level: DiagnosticLevel, summary: impl Into<String>) -> Self {
-        Self {
-            name,
-            level,
-            summary: summary.into(),
-            details: Vec::new(),
-            data: Map::new(),
-        }
-    }
-
-    fn with_details(mut self, details: Vec<String>) -> Self {
-        self.details = details;
-        self
-    }
-
-    fn with_data(mut self, data: Map<String, Value>) -> Self {
-        self.data = data;
-        self
-    }
-
-    fn json_value(&self) -> Value {
-        let mut value = Map::from_iter([
-            (
-                "name".to_string(),
-                Value::String(self.name.to_ascii_lowercase()),
-            ),
-            (
-                "status".to_string(),
-                Value::String(self.level.label().to_string()),
-            ),
-            ("summary".to_string(), Value::String(self.summary.clone())),
-            (
-                "details".to_string(),
-                Value::Array(
-                    self.details
-                        .iter()
-                        .cloned()
-                        .map(Value::String)
-                        .collect::<Vec<_>>(),
-                ),
-            ),
-        ]);
-        value.extend(self.data.clone());
-        Value::Object(value)
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct DoctorReport {
-    checks: Vec<DiagnosticCheck>,
-}
-
-impl DoctorReport {
-    fn counts(&self) -> (usize, usize, usize) {
-        (
-            self.checks
-                .iter()
-                .filter(|check| check.level == DiagnosticLevel::Ok)
-                .count(),
-            self.checks
-                .iter()
-                .filter(|check| check.level == DiagnosticLevel::Warn)
-                .count(),
-            self.checks
-                .iter()
-                .filter(|check| check.level == DiagnosticLevel::Fail)
-                .count(),
-        )
-    }
-
-    fn has_failures(&self) -> bool {
-        self.checks.iter().any(|check| check.level.is_failure())
-    }
-
-    fn render(&self) -> String {
-        let (ok_count, warn_count, fail_count) = self.counts();
-        let mut lines = vec![
-            "Doctor".to_string(),
-            format!(
-                "Summary\n  OK               {ok_count}\n  Warnings         {warn_count}\n  Failures         {fail_count}"
-            ),
-        ];
-        lines.extend(self.checks.iter().map(render_diagnostic_check));
-        lines.join("\n\n")
-    }
-
-    fn json_value(&self) -> Value {
-        let report = self.render();
-        let (ok_count, warn_count, fail_count) = self.counts();
-        json!({
-            "kind": "doctor",
-            "message": report,
-            "report": report,
-            "has_failures": self.has_failures(),
-            "summary": {
-                "total": self.checks.len(),
-                "ok": ok_count,
-                "warnings": warn_count,
-                "failures": fail_count,
-            },
-            "checks": self
-                .checks
-                .iter()
-                .map(DiagnosticCheck::json_value)
-                .collect::<Vec<_>>(),
-        })
-    }
-}
-
-fn render_diagnostic_check(check: &DiagnosticCheck) -> String {
-    let mut lines = vec![format!(
-        "{}\n  Status           {}\n  Summary          {}",
-        check.name,
-        check.level.label(),
-        check.summary
-    )];
-    if !check.details.is_empty() {
-        lines.push("  Details".to_string());
-        lines.extend(check.details.iter().map(|detail| format!("    - {detail}")));
-    }
-    lines.join("\n")
-}
-
-fn render_doctor_report() -> Result<DoctorReport, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let config_loader = ConfigLoader::default_for(&cwd);
-    let config = config_loader.load();
-    let discovered_config = config_loader.discover();
-    let project_context = ProjectContext::discover_with_git(&cwd, DEFAULT_DATE)?;
-    let (project_root, git_branch) =
-        parse_git_status_metadata(project_context.git_status.as_deref());
-    let git_summary = parse_git_workspace_summary(project_context.git_status.as_deref());
-    let empty_config = runtime::RuntimeConfig::empty();
-    let sandbox_config = config.as_ref().ok().unwrap_or(&empty_config);
-    let context = StatusContext {
-        cwd: cwd.clone(),
-        session_path: None,
-        loaded_config_files: config
-            .as_ref()
-            .ok()
-            .map_or(0, |runtime_config| runtime_config.loaded_entries().len()),
-        discovered_config_files: discovered_config.len(),
-        memory_file_count: project_context.instruction_files.len(),
-        project_root,
-        git_branch,
-        git_summary,
-        sandbox_status: resolve_sandbox_status(sandbox_config.sandbox(), &cwd),
-    };
-    Ok(DoctorReport {
-        checks: vec![
-            check_auth_health(),
-            check_config_health(&config_loader, config.as_ref()),
-            check_workspace_health(&context),
-            check_sandbox_health(&context.sandbox_status),
-            check_system_health(&cwd, config.as_ref().ok()),
-        ],
-    })
-}
-
-fn run_doctor(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let report = render_doctor_report()?;
-    let message = report.render();
-    match output_format {
-        CliOutputFormat::Text => println!("{message}"),
-        CliOutputFormat::Json => {
-            println!("{}", serde_json::to_string_pretty(&report.json_value())?);
-        }
-    }
-    if report.has_failures() {
-        return Err("doctor found failing checks".into());
-    }
-    Ok(())
-}
-
-/// Starts a minimal Model Context Protocol server that exposes claw's
-/// built-in tools over stdio.
-///
-/// Tool descriptors come from [`tools::mvp_tool_specs`] and calls are
-/// dispatched through [`tools::execute_tool`], so this server exposes exactly
-/// Read `.claw/worker-state.json` from the current working directory and print it.
-/// This is the file-based worker observability surface: `push_event()` in `worker_boot.rs`
-/// atomically writes state transitions here so external observers (clawhip, orchestrators)
-/// can poll current `WorkerStatus` without needing an HTTP route on the opencode binary.
-fn run_worker_state(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let state_path = cwd.join(".claw").join("worker-state.json");
-    if !state_path.exists() {
-        match output_format {
-            CliOutputFormat::Text => {
-                println!("No worker state file found at {}", state_path.display())
-            }
-            CliOutputFormat::Json => println!(
-                "{}",
-                serde_json::json!({"error": "no_state_file", "path": state_path.display().to_string()})
-            ),
-        }
-        return Ok(());
-    }
-    let raw = std::fs::read_to_string(&state_path)?;
-    match output_format {
-        CliOutputFormat::Text => println!("{raw}"),
-        CliOutputFormat::Json => {
-            // Validate it parses as JSON before re-emitting
-            let _: serde_json::Value = serde_json::from_str(&raw)?;
-            println!("{raw}");
-        }
-    }
-    Ok(())
-}
+// ... (rest of file unchanged)
 
 /// the same surface the in-process agent loop uses.
 fn run_mcp_serve() -> Result<(), Box<dyn std::error::Error>> {
-    let tools = mvp_tool_specs()
-        .into_iter()
-        .map(|spec| McpTool {
-            name: spec.name.to_string(),
-            description: Some(spec.description.to_string()),
-            input_schema: Some(spec.input_schema),
-            annotations: None,
-            meta: None,
-        })
-        .collect();
+    // Let `runtime::mcp_server` resolve tools from Lean when this is empty.
+    // (See `CLAW_LEAN_MCP_MANIFEST_CMD`.)
+    let tools: Vec<McpTool> = Vec::new();
+
+    // Build a closure that preserves built-in tool behavior while allowing
+    // Lean-defined surfaces to dispatch to external providers.
+    let tool_handler = {
+        use runtime::mcp_surface_router::{dispatch_with_map, ToolCommandMap};
+        use std::sync::OnceLock;
+
+        static ROUTER_MAP: OnceLock<Result<Option<ToolCommandMap>, String>> = OnceLock::new();
+
+        move |tool_name: &str, input: &Value| -> Result<String, String> {
+            // 1) Built-in tools first.
+            if let Ok(result) = execute_tool(tool_name, input) {
+                return Ok(result);
+            }
+
+            // 2) External routing map (transitional pool).
+            let map = ROUTER_MAP
+                .get_or_init(|| ToolCommandMap::from_env())
+                .clone()
+                .map_err(|error| error)?;
+
+            if let Some(map) = map {
+                if map.handles(tool_name) {
+                    return dispatch_with_map(&map, tool_name, input);
+                }
+            }
+
+            // 3) Fall through: original built-in error message.
+            execute_tool(tool_name, input)
+        }
+    };
 
     let spec = McpServerSpec {
         server_name: "claw".to_string(),
         server_version: VERSION.to_string(),
         tools,
-        tool_handler: Box::new(execute_tool),
+        tool_handler: Box::new(tool_handler),
     };
 
     let runtime = tokio::runtime::Builder::new_current_thread()
@@ -1428,9770 +426,3 @@ fn run_mcp_serve() -> Result<(), Box<dyn std::error::Error>> {
     })?;
     Ok(())
 }
-
-#[allow(clippy::too_many_lines)]
-fn check_auth_health() -> DiagnosticCheck {
-    let api_key_present = env::var("ANTHROPIC_API_KEY")
-        .ok()
-        .is_some_and(|value| !value.trim().is_empty());
-    let auth_token_present = env::var("ANTHROPIC_AUTH_TOKEN")
-        .ok()
-        .is_some_and(|value| !value.trim().is_empty());
-
-    match load_oauth_credentials() {
-        Ok(Some(token_set)) => {
-            let expired = oauth_token_is_expired(&api::OAuthTokenSet {
-                access_token: token_set.access_token.clone(),
-                refresh_token: token_set.refresh_token.clone(),
-                expires_at: token_set.expires_at,
-                scopes: token_set.scopes.clone(),
-            });
-            let mut details = vec![
-                format!(
-                    "Environment       api_key={} auth_token={}",
-                    if api_key_present { "present" } else { "absent" },
-                    if auth_token_present {
-                        "present"
-                    } else {
-                        "absent"
-                    }
-                ),
-                format!(
-                    "Saved OAuth       expires_at={} refresh_token={} scopes={}",
-                    token_set
-                        .expires_at
-                        .map_or_else(|| "<none>".to_string(), |value| value.to_string()),
-                    if token_set.refresh_token.is_some() {
-                        "present"
-                    } else {
-                        "absent"
-                    },
-                    if token_set.scopes.is_empty() {
-                        "<none>".to_string()
-                    } else {
-                        token_set.scopes.join(",")
-                    }
-                ),
-            ];
-            if expired {
-                details.push(
-                    "Suggested action  claw login to refresh local OAuth credentials".to_string(),
-                );
-            }
-            DiagnosticCheck::new(
-                "Auth",
-                if expired {
-                    DiagnosticLevel::Warn
-                } else {
-                    DiagnosticLevel::Ok
-                },
-                if expired {
-                    "saved OAuth credentials are present but expired"
-                } else if api_key_present || auth_token_present {
-                    "environment and saved credentials are available"
-                } else {
-                    "saved OAuth credentials are available"
-                },
-            )
-            .with_details(details)
-            .with_data(Map::from_iter([
-                ("api_key_present".to_string(), json!(api_key_present)),
-                ("auth_token_present".to_string(), json!(auth_token_present)),
-                ("saved_oauth_present".to_string(), json!(true)),
-                ("saved_oauth_expired".to_string(), json!(expired)),
-                (
-                    "saved_oauth_expires_at".to_string(),
-                    json!(token_set.expires_at),
-                ),
-                (
-                    "refresh_token_present".to_string(),
-                    json!(token_set.refresh_token.is_some()),
-                ),
-                ("scopes".to_string(), json!(token_set.scopes)),
-            ]))
-        }
-        Ok(None) => DiagnosticCheck::new(
-            "Auth",
-            if api_key_present || auth_token_present {
-                DiagnosticLevel::Ok
-            } else {
-                DiagnosticLevel::Warn
-            },
-            if api_key_present || auth_token_present {
-                "environment credentials are configured"
-            } else {
-                "no API key or saved OAuth credentials were found"
-            },
-        )
-        .with_details(vec![format!(
-            "Environment       api_key={} auth_token={}",
-            if api_key_present { "present" } else { "absent" },
-            if auth_token_present {
-                "present"
-            } else {
-                "absent"
-            }
-        )])
-        .with_data(Map::from_iter([
-            ("api_key_present".to_string(), json!(api_key_present)),
-            ("auth_token_present".to_string(), json!(auth_token_present)),
-            ("saved_oauth_present".to_string(), json!(false)),
-            ("saved_oauth_expired".to_string(), json!(false)),
-            ("saved_oauth_expires_at".to_string(), Value::Null),
-            ("refresh_token_present".to_string(), json!(false)),
-            ("scopes".to_string(), json!(Vec::<String>::new())),
-        ])),
-        Err(error) => DiagnosticCheck::new(
-            "Auth",
-            DiagnosticLevel::Fail,
-            format!("failed to inspect saved credentials: {error}"),
-        )
-        .with_data(Map::from_iter([
-            ("api_key_present".to_string(), json!(api_key_present)),
-            ("auth_token_present".to_string(), json!(auth_token_present)),
-            ("saved_oauth_present".to_string(), Value::Null),
-            ("saved_oauth_expired".to_string(), Value::Null),
-            ("saved_oauth_expires_at".to_string(), Value::Null),
-            ("refresh_token_present".to_string(), Value::Null),
-            ("scopes".to_string(), Value::Null),
-            ("saved_oauth_error".to_string(), json!(error.to_string())),
-        ])),
-    }
-}
-
-fn check_config_health(
-    config_loader: &ConfigLoader,
-    config: Result<&runtime::RuntimeConfig, &runtime::ConfigError>,
-) -> DiagnosticCheck {
-    let discovered = config_loader.discover();
-    let discovered_count = discovered.len();
-    let discovered_paths = discovered
-        .iter()
-        .map(|entry| entry.path.display().to_string())
-        .collect::<Vec<_>>();
-    match config {
-        Ok(runtime_config) => {
-            let loaded_entries = runtime_config.loaded_entries();
-            let mut details = vec![format!(
-                "Config files      loaded {}/{}",
-                loaded_entries.len(),
-                discovered_count
-            )];
-            if let Some(model) = runtime_config.model() {
-                details.push(format!("Resolved model    {model}"));
-            }
-            details.push(format!(
-                "MCP servers       {}",
-                runtime_config.mcp().servers().len()
-            ));
-            if discovered_paths.is_empty() {
-                details.push("Discovered files  <none>".to_string());
-            } else {
-                details.extend(
-                    discovered_paths
-                        .iter()
-                        .map(|path| format!("Discovered file   {path}")),
-                );
-            }
-            DiagnosticCheck::new(
-                "Config",
-                if discovered_count == 0 {
-                    DiagnosticLevel::Warn
-                } else {
-                    DiagnosticLevel::Ok
-                },
-                if discovered_count == 0 {
-                    "no config files were found; defaults are active"
-                } else {
-                    "runtime config loaded successfully"
-                },
-            )
-            .with_details(details)
-            .with_data(Map::from_iter([
-                ("discovered_files".to_string(), json!(discovered_paths)),
-                (
-                    "discovered_files_count".to_string(),
-                    json!(discovered_count),
-                ),
-                (
-                    "loaded_config_files".to_string(),
-                    json!(loaded_entries.len()),
-                ),
-                ("resolved_model".to_string(), json!(runtime_config.model())),
-                (
-                    "mcp_servers".to_string(),
-                    json!(runtime_config.mcp().servers().len()),
-                ),
-            ]))
-        }
-        Err(error) => DiagnosticCheck::new(
-            "Config",
-            DiagnosticLevel::Fail,
-            format!("runtime config failed to load: {error}"),
-        )
-        .with_details(if discovered_paths.is_empty() {
-            vec!["Discovered files  <none>".to_string()]
-        } else {
-            discovered_paths
-                .iter()
-                .map(|path| format!("Discovered file   {path}"))
-                .collect()
-        })
-        .with_data(Map::from_iter([
-            ("discovered_files".to_string(), json!(discovered_paths)),
-            (
-                "discovered_files_count".to_string(),
-                json!(discovered_count),
-            ),
-            ("loaded_config_files".to_string(), json!(0)),
-            ("resolved_model".to_string(), Value::Null),
-            ("mcp_servers".to_string(), Value::Null),
-            ("load_error".to_string(), json!(error.to_string())),
-        ])),
-    }
-}
-
-fn check_workspace_health(context: &StatusContext) -> DiagnosticCheck {
-    let in_repo = context.project_root.is_some();
-    DiagnosticCheck::new(
-        "Workspace",
-        if in_repo {
-            DiagnosticLevel::Ok
-        } else {
-            DiagnosticLevel::Warn
-        },
-        if in_repo {
-            format!(
-                "project root detected on branch {}",
-                context.git_branch.as_deref().unwrap_or("unknown")
-            )
-        } else {
-            "current directory is not inside a git project".to_string()
-        },
-    )
-    .with_details(vec![
-        format!("Cwd              {}", context.cwd.display()),
-        format!(
-            "Project root     {}",
-            context
-                .project_root
-                .as_ref()
-                .map_or_else(|| "<none>".to_string(), |path| path.display().to_string())
-        ),
-        format!(
-            "Git branch       {}",
-            context.git_branch.as_deref().unwrap_or("unknown")
-        ),
-        format!("Git state        {}", context.git_summary.headline()),
-        format!("Changed files    {}", context.git_summary.changed_files),
-        format!(
-            "Memory files     {} · config files loaded {}/{}",
-            context.memory_file_count, context.loaded_config_files, context.discovered_config_files
-        ),
-    ])
-    .with_data(Map::from_iter([
-        ("cwd".to_string(), json!(context.cwd.display().to_string())),
-        (
-            "project_root".to_string(),
-            json!(context
-                .project_root
-                .as_ref()
-                .map(|path| path.display().to_string())),
-        ),
-        ("in_git_repo".to_string(), json!(in_repo)),
-        ("git_branch".to_string(), json!(context.git_branch)),
-        (
-            "git_state".to_string(),
-            json!(context.git_summary.headline()),
-        ),
-        (
-            "changed_files".to_string(),
-            json!(context.git_summary.changed_files),
-        ),
-        (
-            "memory_file_count".to_string(),
-            json!(context.memory_file_count),
-        ),
-        (
-            "loaded_config_files".to_string(),
-            json!(context.loaded_config_files),
-        ),
-        (
-            "discovered_config_files".to_string(),
-            json!(context.discovered_config_files),
-        ),
-    ]))
-}
-
-fn check_sandbox_health(status: &runtime::SandboxStatus) -> DiagnosticCheck {
-    let degraded = status.enabled && !status.active;
-    let mut details = vec![
-        format!("Enabled          {}", status.enabled),
-        format!("Active           {}", status.active),
-        format!("Supported        {}", status.supported),
-        format!("Filesystem mode  {}", status.filesystem_mode.as_str()),
-        format!("Filesystem live  {}", status.filesystem_active),
-    ];
-    if let Some(reason) = &status.fallback_reason {
-        details.push(format!("Fallback reason  {reason}"));
-    }
-    DiagnosticCheck::new(
-        "Sandbox",
-        if degraded {
-            DiagnosticLevel::Warn
-        } else {
-            DiagnosticLevel::Ok
-        },
-        if degraded {
-            "sandbox was requested but is not currently active"
-        } else if status.active {
-            "sandbox protections are active"
-        } else {
-            "sandbox is not active for this session"
-        },
-    )
-    .with_details(details)
-    .with_data(Map::from_iter([
-        ("enabled".to_string(), json!(status.enabled)),
-        ("active".to_string(), json!(status.active)),
-        ("supported".to_string(), json!(status.supported)),
-        (
-            "namespace_supported".to_string(),
-            json!(status.namespace_supported),
-        ),
-        (
-            "namespace_active".to_string(),
-            json!(status.namespace_active),
-        ),
-        (
-            "network_supported".to_string(),
-            json!(status.network_supported),
-        ),
-        ("network_active".to_string(), json!(status.network_active)),
-        (
-            "filesystem_mode".to_string(),
-            json!(status.filesystem_mode.as_str()),
-        ),
-        (
-            "filesystem_active".to_string(),
-            json!(status.filesystem_active),
-        ),
-        ("allowed_mounts".to_string(), json!(status.allowed_mounts)),
-        ("in_container".to_string(), json!(status.in_container)),
-        (
-            "container_markers".to_string(),
-            json!(status.container_markers),
-        ),
-        ("fallback_reason".to_string(), json!(status.fallback_reason)),
-    ]))
-}
-
-fn check_system_health(cwd: &Path, config: Option<&runtime::RuntimeConfig>) -> DiagnosticCheck {
-    let default_model = config.and_then(runtime::RuntimeConfig::model);
-    let mut details = vec![
-        format!("OS               {} {}", env::consts::OS, env::consts::ARCH),
-        format!("Working dir      {}", cwd.display()),
-        format!("Version          {}", VERSION),
-        format!("Build target     {}", BUILD_TARGET.unwrap_or("<unknown>")),
-        format!("Git SHA          {}", GIT_SHA.unwrap_or("<unknown>")),
-    ];
-    if let Some(model) = default_model {
-        details.push(format!("Default model    {model}"));
-    }
-    DiagnosticCheck::new(
-        "System",
-        DiagnosticLevel::Ok,
-        "captured local runtime metadata",
-    )
-    .with_details(details)
-    .with_data(Map::from_iter([
-        ("os".to_string(), json!(env::consts::OS)),
-        ("arch".to_string(), json!(env::consts::ARCH)),
-        ("working_dir".to_string(), json!(cwd.display().to_string())),
-        ("version".to_string(), json!(VERSION)),
-        ("build_target".to_string(), json!(BUILD_TARGET)),
-        ("git_sha".to_string(), json!(GIT_SHA)),
-        ("default_model".to_string(), json!(default_model)),
-    ]))
-}
-
-fn resume_command_can_absorb_token(current_command: &str, token: &str) -> bool {
-    matches!(
-        SlashCommand::parse(current_command),
-        Ok(Some(SlashCommand::Export { path: None }))
-    ) && !looks_like_slash_command_token(token)
-}
-
-fn looks_like_slash_command_token(token: &str) -> bool {
-    let trimmed = token.trim_start();
-    let Some(name) = trimmed.strip_prefix('/').and_then(|value| {
-        value
-            .split_whitespace()
-            .next()
-            .map(str::trim)
-            .filter(|value| !value.is_empty())
-    }) else {
-        return false;
-    };
-
-    slash_command_specs()
-        .iter()
-        .any(|spec| spec.name == name || spec.aliases.contains(&name))
-}
-
-fn dump_manifests(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let workspace_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
-    let paths = UpstreamPaths::from_workspace_dir(&workspace_dir);
-    match extract_manifest(&paths) {
-        Ok(manifest) => {
-            match output_format {
-                CliOutputFormat::Text => {
-                    println!("commands: {}", manifest.commands.entries().len());
-                    println!("tools: {}", manifest.tools.entries().len());
-                    println!("bootstrap phases: {}", manifest.bootstrap.phases().len());
-                }
-                CliOutputFormat::Json => println!(
-                    "{}",
-                    serde_json::to_string_pretty(&json!({
-                        "kind": "dump-manifests",
-                        "commands": manifest.commands.entries().len(),
-                        "tools": manifest.tools.entries().len(),
-                        "bootstrap_phases": manifest.bootstrap.phases().len(),
-                    }))?
-                ),
-            }
-            Ok(())
-        }
-        Err(error) => Err(format!("failed to extract manifests: {error}").into()),
-    }
-}
-
-fn print_bootstrap_plan(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let phases = runtime::BootstrapPlan::claude_code_default()
-        .phases()
-        .iter()
-        .map(|phase| format!("{phase:?}"))
-        .collect::<Vec<_>>();
-    match output_format {
-        CliOutputFormat::Text => {
-            for phase in &phases {
-                println!("- {phase}");
-            }
-        }
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&json!({
-                "kind": "bootstrap-plan",
-                "phases": phases,
-            }))?
-        ),
-    }
-    Ok(())
-}
-
-fn default_oauth_config() -> OAuthConfig {
-    OAuthConfig {
-        client_id: String::from("9d1c250a-e61b-44d9-88ed-5944d1962f5e"),
-        authorize_url: String::from("https://platform.claude.com/oauth/authorize"),
-        token_url: String::from("https://platform.claude.com/v1/oauth/token"),
-        callback_port: None,
-        manual_redirect_url: None,
-        scopes: vec![
-            String::from("user:profile"),
-            String::from("user:inference"),
-            String::from("user:sessions:claude_code"),
-        ],
-    }
-}
-
-fn run_login(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let config = ConfigLoader::default_for(&cwd).load()?;
-    let default_oauth = default_oauth_config();
-    let oauth = config.oauth().unwrap_or(&default_oauth);
-    let callback_port = oauth.callback_port.unwrap_or(DEFAULT_OAUTH_CALLBACK_PORT);
-    let redirect_uri = runtime::loopback_redirect_uri(callback_port);
-    let pkce = generate_pkce_pair()?;
-    let state = generate_state()?;
-    let authorize_url =
-        OAuthAuthorizationRequest::from_config(oauth, redirect_uri.clone(), state.clone(), &pkce)
-            .build_url();
-
-    if output_format == CliOutputFormat::Text {
-        println!("Starting Claude OAuth login...");
-        println!("Listening for callback on {redirect_uri}");
-    }
-    if let Err(error) = open_browser(&authorize_url) {
-        emit_login_browser_open_failure(
-            output_format,
-            &authorize_url,
-            &error,
-            &mut io::stdout(),
-            &mut io::stderr(),
-        )?;
-    }
-
-    let callback = wait_for_oauth_callback(callback_port)?;
-    if let Some(error) = callback.error {
-        let description = callback
-            .error_description
-            .unwrap_or_else(|| "authorization failed".to_string());
-        return Err(io::Error::other(format!("{error}: {description}")).into());
-    }
-    let code = callback.code.ok_or_else(|| {
-        io::Error::new(io::ErrorKind::InvalidData, "callback did not include code")
-    })?;
-    let returned_state = callback.state.ok_or_else(|| {
-        io::Error::new(io::ErrorKind::InvalidData, "callback did not include state")
-    })?;
-    if returned_state != state {
-        return Err(io::Error::new(io::ErrorKind::InvalidData, "oauth state mismatch").into());
-    }
-
-    let client = AnthropicClient::from_auth(AuthSource::None).with_base_url(api::read_base_url());
-    let exchange_request = OAuthTokenExchangeRequest::from_config(
-        oauth,
-        code,
-        state,
-        pkce.verifier,
-        redirect_uri.clone(),
-    );
-    let runtime = tokio::runtime::Runtime::new()?;
-    let token_set = runtime.block_on(client.exchange_oauth_code(oauth, &exchange_request))?;
-    save_oauth_credentials(&runtime::OAuthTokenSet {
-        access_token: token_set.access_token,
-        refresh_token: token_set.refresh_token,
-        expires_at: token_set.expires_at,
-        scopes: token_set.scopes,
-    })?;
-    match output_format {
-        CliOutputFormat::Text => println!("Claude OAuth login complete."),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&json!({
-                "kind": "login",
-                "callback_port": callback_port,
-                "redirect_uri": redirect_uri,
-                "message": "Claude OAuth login complete.",
-            }))?
-        ),
-    }
-    Ok(())
-}
-
-fn emit_login_browser_open_failure(
-    output_format: CliOutputFormat,
-    authorize_url: &str,
-    error: &io::Error,
-    stdout: &mut impl Write,
-    stderr: &mut impl Write,
-) -> io::Result<()> {
-    writeln!(
-        stderr,
-        "warning: failed to open browser automatically: {error}"
-    )?;
-    match output_format {
-        CliOutputFormat::Text => writeln!(stdout, "Open this URL manually:\n{authorize_url}"),
-        CliOutputFormat::Json => writeln!(stderr, "Open this URL manually:\n{authorize_url}"),
-    }
-}
-
-fn run_logout(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    clear_oauth_credentials()?;
-    match output_format {
-        CliOutputFormat::Text => println!("Claude OAuth credentials cleared."),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&json!({
-                "kind": "logout",
-                "message": "Claude OAuth credentials cleared.",
-            }))?
-        ),
-    }
-    Ok(())
-}
-
-fn open_browser(url: &str) -> io::Result<()> {
-    let commands = if cfg!(target_os = "macos") {
-        vec![("open", vec![url])]
-    } else if cfg!(target_os = "windows") {
-        vec![("cmd", vec!["/C", "start", "", url])]
-    } else {
-        vec![("xdg-open", vec![url])]
-    };
-    for (program, args) in commands {
-        match Command::new(program).args(args).spawn() {
-            Ok(_) => return Ok(()),
-            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
-            Err(error) => return Err(error),
-        }
-    }
-    Err(io::Error::new(
-        io::ErrorKind::NotFound,
-        "no supported browser opener command found",
-    ))
-}
-
-fn wait_for_oauth_callback(
-    port: u16,
-) -> Result<runtime::OAuthCallbackParams, Box<dyn std::error::Error>> {
-    let listener = TcpListener::bind(("127.0.0.1", port))?;
-    let (mut stream, _) = listener.accept()?;
-    let mut buffer = [0_u8; 4096];
-    let bytes_read = stream.read(&mut buffer)?;
-    let request = String::from_utf8_lossy(&buffer[..bytes_read]);
-    let request_line = request.lines().next().ok_or_else(|| {
-        io::Error::new(io::ErrorKind::InvalidData, "missing callback request line")
-    })?;
-    let target = request_line.split_whitespace().nth(1).ok_or_else(|| {
-        io::Error::new(
-            io::ErrorKind::InvalidData,
-            "missing callback request target",
-        )
-    })?;
-    let callback = parse_oauth_callback_request_target(target)
-        .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
-    let body = if callback.error.is_some() {
-        "Claude OAuth login failed. You can close this window."
-    } else {
-        "Claude OAuth login succeeded. You can close this window."
-    };
-    let response = format!(
-        "HTTP/1.1 200 OK\r\ncontent-type: text/plain; charset=utf-8\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
-        body.len(),
-        body
-    );
-    stream.write_all(response.as_bytes())?;
-    Ok(callback)
-}
-
-fn print_system_prompt(
-    cwd: PathBuf,
-    date: String,
-    output_format: CliOutputFormat,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let sections = load_system_prompt(cwd, date, env::consts::OS, "unknown")?;
-    let message = sections.join(
-        "
-
-",
-    );
-    match output_format {
-        CliOutputFormat::Text => println!("{message}"),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&json!({
-                "kind": "system-prompt",
-                "message": message,
-                "sections": sections,
-            }))?
-        ),
-    }
-    Ok(())
-}
-
-fn print_version(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    match output_format {
-        CliOutputFormat::Text => println!("{}", render_version_report()),
-        CliOutputFormat::Json => {
-            println!("{}", serde_json::to_string_pretty(&version_json_value())?);
-        }
-    }
-    Ok(())
-}
-
-fn version_json_value() -> serde_json::Value {
-    json!({
-        "kind": "version",
-        "message": render_version_report(),
-        "version": VERSION,
-        "git_sha": GIT_SHA,
-        "target": BUILD_TARGET,
-    })
-}
-
-fn resume_session(session_path: &Path, commands: &[String], output_format: CliOutputFormat) {
-    let resolved_path = if session_path.exists() {
-        session_path.to_path_buf()
-    } else {
-        match resolve_session_reference(&session_path.display().to_string()) {
-            Ok(handle) => handle.path,
-            Err(error) => {
-                eprintln!("failed to restore session: {error}");
-                std::process::exit(1);
-            }
-        }
-    };
-
-    let session = match Session::load_from_path(&resolved_path) {
-        Ok(session) => session,
-        Err(error) => {
-            eprintln!("failed to restore session: {error}");
-            std::process::exit(1);
-        }
-    };
-
-    if commands.is_empty() {
-        println!(
-            "Restored session from {} ({} messages).",
-            resolved_path.display(),
-            session.messages.len()
-        );
-        return;
-    }
-
-    let mut session = session;
-    for raw_command in commands {
-        let command = match SlashCommand::parse(raw_command) {
-            Ok(Some(command)) => command,
-            Ok(None) => {
-                eprintln!("unsupported resumed command: {raw_command}");
-                std::process::exit(2);
-            }
-            Err(error) => {
-                eprintln!("{error}");
-                std::process::exit(2);
-            }
-        };
-        match run_resume_command(&resolved_path, &session, &command) {
-            Ok(ResumeCommandOutcome {
-                session: next_session,
-                message,
-                json,
-            }) => {
-                session = next_session;
-                if output_format == CliOutputFormat::Json {
-                    if let Some(value) = json {
-                        println!(
-                            "{}",
-                            serde_json::to_string_pretty(&value)
-                                .expect("resume command json output")
-                        );
-                    } else if let Some(message) = message {
-                        println!("{message}");
-                    }
-                } else if let Some(message) = message {
-                    println!("{message}");
-                }
-            }
-            Err(error) => {
-                eprintln!("{error}");
-                std::process::exit(2);
-            }
-        }
-    }
-}
-
-#[derive(Debug, Clone)]
-struct ResumeCommandOutcome {
-    session: Session,
-    message: Option<String>,
-    json: Option<serde_json::Value>,
-}
-
-#[derive(Debug, Clone)]
-struct StatusContext {
-    cwd: PathBuf,
-    session_path: Option<PathBuf>,
-    loaded_config_files: usize,
-    discovered_config_files: usize,
-    memory_file_count: usize,
-    project_root: Option<PathBuf>,
-    git_branch: Option<String>,
-    git_summary: GitWorkspaceSummary,
-    sandbox_status: runtime::SandboxStatus,
-}
-
-#[derive(Debug, Clone, Copy)]
-struct StatusUsage {
-    message_count: usize,
-    turns: u32,
-    latest: TokenUsage,
-    cumulative: TokenUsage,
-    estimated_tokens: usize,
-}
-
-#[allow(clippy::struct_field_names)]
-#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
-struct GitWorkspaceSummary {
-    changed_files: usize,
-    staged_files: usize,
-    unstaged_files: usize,
-    untracked_files: usize,
-    conflicted_files: usize,
-}
-
-impl GitWorkspaceSummary {
-    fn is_clean(self) -> bool {
-        self.changed_files == 0
-    }
-
-    fn headline(self) -> String {
-        if self.is_clean() {
-            "clean".to_string()
-        } else {
-            let mut details = Vec::new();
-            if self.staged_files > 0 {
-                details.push(format!("{} staged", self.staged_files));
-            }
-            if self.unstaged_files > 0 {
-                details.push(format!("{} unstaged", self.unstaged_files));
-            }
-            if self.untracked_files > 0 {
-                details.push(format!("{} untracked", self.untracked_files));
-            }
-            if self.conflicted_files > 0 {
-                details.push(format!("{} conflicted", self.conflicted_files));
-            }
-            format!(
-                "dirty · {} files · {}",
-                self.changed_files,
-                details.join(", ")
-            )
-        }
-    }
-}
-
-#[cfg(test)]
-fn format_unknown_slash_command_message(name: &str) -> String {
-    let suggestions = suggest_slash_commands(name);
-    let mut message = format!("unknown slash command: /{name}.");
-    if !suggestions.is_empty() {
-        message.push_str(" Did you mean ");
-        message.push_str(&suggestions.join(", "));
-        message.push('?');
-    }
-    if let Some(note) = omc_compatibility_note_for_unknown_slash_command(name) {
-        message.push(' ');
-        message.push_str(note);
-    }
-    message.push_str(" Use /help to list available commands.");
-    message
-}
-
-fn format_model_report(model: &str, message_count: usize, turns: u32) -> String {
-    format!(
-        "Model
-  Current model    {model}
-  Session messages {message_count}
-  Session turns    {turns}
-
-Usage
-  Inspect current model with /model
-  Switch models with /model <name>"
-    )
-}
-
-fn format_model_switch_report(previous: &str, next: &str, message_count: usize) -> String {
-    format!(
-        "Model updated
-  Previous         {previous}
-  Current          {next}
-  Preserved msgs   {message_count}"
-    )
-}
-
-fn format_permissions_report(mode: &str) -> String {
-    let modes = [
-        ("read-only", "Read/search tools only", mode == "read-only"),
-        (
-            "workspace-write",
-            "Edit files inside the workspace",
-            mode == "workspace-write",
-        ),
-        (
-            "danger-full-access",
-            "Unrestricted tool access",
-            mode == "danger-full-access",
-        ),
-    ]
-    .into_iter()
-    .map(|(name, description, is_current)| {
-        let marker = if is_current {
-            "● current"
-        } else {
-            "○ available"
-        };
-        format!("  {name:<18} {marker:<11} {description}")
-    })
-    .collect::<Vec<_>>()
-    .join(
-        "
-",
-    );
-
-    format!(
-        "Permissions
-  Active mode      {mode}
-  Mode status      live session default
-
-Modes
-{modes}
-
-Usage
-  Inspect current mode with /permissions
-  Switch modes with /permissions <mode>"
-    )
-}
-
-fn format_permissions_switch_report(previous: &str, next: &str) -> String {
-    format!(
-        "Permissions updated
-  Result           mode switched
-  Previous mode    {previous}
-  Active mode      {next}
-  Applies to       subsequent tool calls
-  Usage            /permissions to inspect current mode"
-    )
-}
-
-fn format_cost_report(usage: TokenUsage) -> String {
-    format!(
-        "Cost
-  Input tokens     {}
-  Output tokens    {}
-  Cache create     {}
-  Cache read       {}
-  Total tokens     {}",
-        usage.input_tokens,
-        usage.output_tokens,
-        usage.cache_creation_input_tokens,
-        usage.cache_read_input_tokens,
-        usage.total_tokens(),
-    )
-}
-
-fn format_resume_report(session_path: &str, message_count: usize, turns: u32) -> String {
-    format!(
-        "Session resumed
-  Session file     {session_path}
-  Messages         {message_count}
-  Turns            {turns}"
-    )
-}
-
-fn render_resume_usage() -> String {
-    format!(
-        "Resume
-  Usage            /resume <session-path|session-id|{LATEST_SESSION_REFERENCE}>
-  Auto-save        .claw/sessions/<session-id>.{PRIMARY_SESSION_EXTENSION}
-  Tip              use /session list to inspect saved sessions"
-    )
-}
-
-fn format_compact_report(removed: usize, resulting_messages: usize, skipped: bool) -> String {
-    if skipped {
-        format!(
-            "Compact
-  Result           skipped
-  Reason           session below compaction threshold
-  Messages kept    {resulting_messages}"
-        )
-    } else {
-        format!(
-            "Compact
-  Result           compacted
-  Messages removed {removed}
-  Messages kept    {resulting_messages}"
-        )
-    }
-}
-
-fn format_auto_compaction_notice(removed: usize) -> String {
-    format!("[auto-compacted: removed {removed} messages]")
-}
-
-fn parse_git_status_metadata(status: Option<&str>) -> (Option<PathBuf>, Option<String>) {
-    parse_git_status_metadata_for(
-        &env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
-        status,
-    )
-}
-
-fn parse_git_status_branch(status: Option<&str>) -> Option<String> {
-    let status = status?;
-    let first_line = status.lines().next()?;
-    let line = first_line.strip_prefix("## ")?;
-    if line.starts_with("HEAD") {
-        return Some("detached HEAD".to_string());
-    }
-    let branch = line.split(['.', ' ']).next().unwrap_or_default().trim();
-    if branch.is_empty() {
-        None
-    } else {
-        Some(branch.to_string())
-    }
-}
-
-fn parse_git_workspace_summary(status: Option<&str>) -> GitWorkspaceSummary {
-    let mut summary = GitWorkspaceSummary::default();
-    let Some(status) = status else {
-        return summary;
-    };
-
-    for line in status.lines() {
-        if line.starts_with("## ") || line.trim().is_empty() {
-            continue;
-        }
-
-        summary.changed_files += 1;
-        let mut chars = line.chars();
-        let index_status = chars.next().unwrap_or(' ');
-        let worktree_status = chars.next().unwrap_or(' ');
-
-        if index_status == '?' && worktree_status == '?' {
-            summary.untracked_files += 1;
-            continue;
-        }
-
-        if index_status != ' ' {
-            summary.staged_files += 1;
-        }
-        if worktree_status != ' ' {
-            summary.unstaged_files += 1;
-        }
-        if (matches!(index_status, 'U' | 'A') && matches!(worktree_status, 'U' | 'A'))
-            || index_status == 'U'
-            || worktree_status == 'U'
-        {
-            summary.conflicted_files += 1;
-        }
-    }
-
-    summary
-}
-
-fn resolve_git_branch_for(cwd: &Path) -> Option<String> {
-    let branch = run_git_capture_in(cwd, &["branch", "--show-current"])?;
-    let branch = branch.trim();
-    if !branch.is_empty() {
-        return Some(branch.to_string());
-    }
-
-    let fallback = run_git_capture_in(cwd, &["rev-parse", "--abbrev-ref", "HEAD"])?;
-    let fallback = fallback.trim();
-    if fallback.is_empty() {
-        None
-    } else if fallback == "HEAD" {
-        Some("detached HEAD".to_string())
-    } else {
-        Some(fallback.to_string())
-    }
-}
-
-fn run_git_capture_in(cwd: &Path, args: &[&str]) -> Option<String> {
-    let output = std::process::Command::new("git")
-        .args(args)
-        .current_dir(cwd)
-        .output()
-        .ok()?;
-    if !output.status.success() {
-        return None;
-    }
-    String::from_utf8(output.stdout).ok()
-}
-
-fn find_git_root_in(cwd: &Path) -> Result<PathBuf, Box<dyn std::error::Error>> {
-    let output = std::process::Command::new("git")
-        .args(["rev-parse", "--show-toplevel"])
-        .current_dir(cwd)
-        .output()?;
-    if !output.status.success() {
-        return Err("not a git repository".into());
-    }
-    let path = String::from_utf8(output.stdout)?.trim().to_string();
-    if path.is_empty() {
-        return Err("empty git root".into());
-    }
-    Ok(PathBuf::from(path))
-}
-
-fn parse_git_status_metadata_for(
-    cwd: &Path,
-    status: Option<&str>,
-) -> (Option<PathBuf>, Option<String>) {
-    let branch = resolve_git_branch_for(cwd).or_else(|| parse_git_status_branch(status));
-    let project_root = find_git_root_in(cwd).ok();
-    (project_root, branch)
-}
-
-#[allow(clippy::too_many_lines)]
-fn run_resume_command(
-    session_path: &Path,
-    session: &Session,
-    command: &SlashCommand,
-) -> Result<ResumeCommandOutcome, Box<dyn std::error::Error>> {
-    match command {
-        SlashCommand::Help => Ok(ResumeCommandOutcome {
-            session: session.clone(),
-            message: Some(render_repl_help()),
-            json: None,
-        }),
-        SlashCommand::Compact => {
-            let result = runtime::compact_session(
-                session,
-                CompactionConfig {
-                    max_estimated_tokens: 0,
-                    ..CompactionConfig::default()
-                },
-            );
-            let removed = result.removed_message_count;
-            let kept = result.compacted_session.messages.len();
-            let skipped = removed == 0;
-            result.compacted_session.save_to_path(session_path)?;
-            Ok(ResumeCommandOutcome {
-                session: result.compacted_session,
-                message: Some(format_compact_report(removed, kept, skipped)),
-                json: None,
-            })
-        }
-        SlashCommand::Clear { confirm } => {
-            if !confirm {
-                return Ok(ResumeCommandOutcome {
-                    session: session.clone(),
-                    message: Some(
-                        "clear: confirmation required; rerun with /clear --confirm".to_string(),
-                    ),
-                    json: None,
-                });
-            }
-            let backup_path = write_session_clear_backup(session, session_path)?;
-            let previous_session_id = session.session_id.clone();
-            let cleared = Session::new();
-            let new_session_id = cleared.session_id.clone();
-            cleared.save_to_path(session_path)?;
-            Ok(ResumeCommandOutcome {
-                session: cleared,
-                message: Some(format!(
-                    "Session cleared\n  Mode             resumed session reset\n  Previous session {previous_session_id}\n  Backup           {}\n  Resume previous  claw --resume {}\n  New session      {new_session_id}\n  Session file     {}",
-                    backup_path.display(),
-                    backup_path.display(),
-                    session_path.display()
-                )),
-                json: None,
-            })
-        }
-        SlashCommand::Status => {
-            let tracker = UsageTracker::from_session(session);
-            let usage = tracker.cumulative_usage();
-            let context = status_context(Some(session_path))?;
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(format_status_report(
-                    "restored-session",
-                    StatusUsage {
-                        message_count: session.messages.len(),
-                        turns: tracker.turns(),
-                        latest: tracker.current_turn_usage(),
-                        cumulative: usage,
-                        estimated_tokens: 0,
-                    },
-                    default_permission_mode().as_str(),
-                    &context,
-                )),
-                json: Some(status_json_value(
-                    "restored-session",
-                    StatusUsage {
-                        message_count: session.messages.len(),
-                        turns: tracker.turns(),
-                        latest: tracker.current_turn_usage(),
-                        cumulative: usage,
-                        estimated_tokens: 0,
-                    },
-                    default_permission_mode().as_str(),
-                    &context,
-                )),
-            })
-        }
-        SlashCommand::Sandbox => {
-            let cwd = env::current_dir()?;
-            let loader = ConfigLoader::default_for(&cwd);
-            let runtime_config = loader.load()?;
-            let status = resolve_sandbox_status(runtime_config.sandbox(), &cwd);
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(format_sandbox_report(&status)),
-                json: Some(sandbox_json_value(&status)),
-            })
-        }
-        SlashCommand::Cost => {
-            let usage = UsageTracker::from_session(session).cumulative_usage();
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(format_cost_report(usage)),
-                json: None,
-            })
-        }
-        SlashCommand::Config { section } => Ok(ResumeCommandOutcome {
-            session: session.clone(),
-            message: Some(render_config_report(section.as_deref())?),
-            json: None,
-        }),
-        SlashCommand::Mcp { action, target } => {
-            let cwd = env::current_dir()?;
-            let args = match (action.as_deref(), target.as_deref()) {
-                (None, None) => None,
-                (Some(action), None) => Some(action.to_string()),
-                (Some(action), Some(target)) => Some(format!("{action} {target}")),
-                (None, Some(target)) => Some(target.to_string()),
-            };
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(handle_mcp_slash_command(args.as_deref(), &cwd)?),
-                json: Some(handle_mcp_slash_command_json(args.as_deref(), &cwd)?),
-            })
-        }
-        SlashCommand::Memory => Ok(ResumeCommandOutcome {
-            session: session.clone(),
-            message: Some(render_memory_report()?),
-            json: None,
-        }),
-        SlashCommand::Init => {
-            let message = init_claude_md()?;
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(message.clone()),
-                json: Some(init_json_value(&message)),
-            })
-        }
-        SlashCommand::Diff => Ok(ResumeCommandOutcome {
-            session: session.clone(),
-            message: Some(render_diff_report_for(
-                session_path.parent().unwrap_or_else(|| Path::new(".")),
-            )?),
-            json: None,
-        }),
-        SlashCommand::Version => Ok(ResumeCommandOutcome {
-            session: session.clone(),
-            message: Some(render_version_report()),
-            json: Some(version_json_value()),
-        }),
-        SlashCommand::Export { path } => {
-            let export_path = resolve_export_path(path.as_deref(), session)?;
-            fs::write(&export_path, render_export_text(session))?;
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(format!(
-                    "Export\n  Result           wrote transcript\n  File             {}\n  Messages         {}",
-                    export_path.display(),
-                    session.messages.len(),
-                )),
-                json: None,
-            })
-        }
-        SlashCommand::Agents { args } => {
-            let cwd = env::current_dir()?;
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(handle_agents_slash_command(args.as_deref(), &cwd)?),
-                json: None,
-            })
-        }
-        SlashCommand::Skills { args } => {
-            if let SkillSlashDispatch::Invoke(_) = classify_skills_slash_command(args.as_deref()) {
-                return Err(
-                    "resumed /skills invocations are interactive-only; start `claw` and run `/skills <skill>` in the REPL".into(),
-                );
-            }
-            let cwd = env::current_dir()?;
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(handle_skills_slash_command(args.as_deref(), &cwd)?),
-                json: Some(handle_skills_slash_command_json(args.as_deref(), &cwd)?),
-            })
-        }
-        SlashCommand::Doctor => Ok(ResumeCommandOutcome {
-            session: session.clone(),
-            message: Some(render_doctor_report()?.render()),
-            json: None,
-        }),
-        SlashCommand::History { count } => {
-            let limit = parse_history_count(count.as_deref())
-                .map_err(|error| -> Box<dyn std::error::Error> { error.into() })?;
-            let entries = collect_session_prompt_history(session);
-            Ok(ResumeCommandOutcome {
-                session: session.clone(),
-                message: Some(render_prompt_history_report(&entries, limit)),
-                json: None,
-            })
-        }
-        SlashCommand::Unknown(name) => Err(format_unknown_slash_command(name).into()),
-        SlashCommand::Bughunter { .. }
-        | SlashCommand::Commit { .. }
-        | SlashCommand::Pr { .. }
-        | SlashCommand::Issue { .. }
-        | SlashCommand::Ultraplan { .. }
-        | SlashCommand::Teleport { .. }
-        | SlashCommand::DebugToolCall { .. }
-        | SlashCommand::Resume { .. }
-        | SlashCommand::Model { .. }
-        | SlashCommand::Permissions { .. }
-        | SlashCommand::Session { .. }
-        | SlashCommand::Plugins { .. }
-        | SlashCommand::Login
-        | SlashCommand::Logout
-        | SlashCommand::Vim
-        | SlashCommand::Upgrade
-        | SlashCommand::Stats
-        | SlashCommand::Share
-        | SlashCommand::Feedback
-        | SlashCommand::Files
-        | SlashCommand::Fast
-        | SlashCommand::Exit
-        | SlashCommand::Summary
-        | SlashCommand::Desktop
-        | SlashCommand::Brief
-        | SlashCommand::Advisor
-        | SlashCommand::Stickers
-        | SlashCommand::Insights
-        | SlashCommand::Thinkback
-        | SlashCommand::ReleaseNotes
-        | SlashCommand::SecurityReview
-        | SlashCommand::Keybindings
-        | SlashCommand::PrivacySettings
-        | SlashCommand::Plan { .. }
-        | SlashCommand::Review { .. }
-        | SlashCommand::Tasks { .. }
-        | SlashCommand::Theme { .. }
-        | SlashCommand::Voice { .. }
-        | SlashCommand::Usage { .. }
-        | SlashCommand::Rename { .. }
-        | SlashCommand::Copy { .. }
-        | SlashCommand::Hooks { .. }
-        | SlashCommand::Context { .. }
-        | SlashCommand::Color { .. }
-        | SlashCommand::Effort { .. }
-        | SlashCommand::Branch { .. }
-        | SlashCommand::Rewind { .. }
-        | SlashCommand::Ide { .. }
-        | SlashCommand::Tag { .. }
-        | SlashCommand::OutputStyle { .. }
-        | SlashCommand::AddDir { .. } => Err("unsupported resumed slash command".into()),
-    }
-}
-
-/// Stale-base preflight: verify the worktree HEAD matches the expected base
-/// commit (from `--base-commit` flag or `.claw-base` file). Emits a warning to
-/// stderr when the HEAD has diverged.
-fn run_stale_base_preflight(flag_value: Option<&str>) {
-    let cwd = match env::current_dir() {
-        Ok(cwd) => cwd,
-        Err(_) => return,
-    };
-    let source = resolve_expected_base(flag_value, &cwd);
-    let state = check_base_commit(&cwd, source.as_ref());
-    if let Some(warning) = format_stale_base_warning(&state) {
-        eprintln!("{warning}");
-    }
-}
-
-fn run_repl(
-    model: String,
-    allowed_tools: Option<AllowedToolSet>,
-    permission_mode: PermissionMode,
-    base_commit: Option<String>,
-    reasoning_effort: Option<String>,
-) -> Result<(), Box<dyn std::error::Error>> {
-    run_stale_base_preflight(base_commit.as_deref());
-    let resolved_model = resolve_repl_model(model);
-    let mut cli = LiveCli::new(resolved_model, true, allowed_tools, permission_mode)?;
-    cli.set_reasoning_effort(reasoning_effort);
-    let mut editor =
-        input::LineEditor::new("> ", cli.repl_completion_candidates().unwrap_or_default());
-    println!("{}", cli.startup_banner());
-    println!("{}", format_connected_line(&cli.model));
-
-    loop {
-        editor.set_completions(cli.repl_completion_candidates().unwrap_or_default());
-        match editor.read_line()? {
-            input::ReadOutcome::Submit(input) => {
-                let trimmed = input.trim().to_string();
-                if trimmed.is_empty() {
-                    continue;
-                }
-                if matches!(trimmed.as_str(), "/exit" | "/quit") {
-                    cli.persist_session()?;
-                    break;
-                }
-                match SlashCommand::parse(&trimmed) {
-                    Ok(Some(command)) => {
-                        if cli.handle_repl_command(command)? {
-                            cli.persist_session()?;
-                        }
-                        continue;
-                    }
-                    Ok(None) => {}
-                    Err(error) => {
-                        eprintln!("{error}");
-                        continue;
-                    }
-                }
-                editor.push_history(input);
-                cli.record_prompt_history(&trimmed);
-                cli.run_turn(&trimmed)?;
-            }
-            input::ReadOutcome::Cancel => {}
-            input::ReadOutcome::Exit => {
-                cli.persist_session()?;
-                break;
-            }
-        }
-    }
-
-    Ok(())
-}
-
-#[derive(Debug, Clone)]
-struct SessionHandle {
-    id: String,
-    path: PathBuf,
-}
-
-#[derive(Debug, Clone)]
-struct ManagedSessionSummary {
-    id: String,
-    path: PathBuf,
-    modified_epoch_millis: u128,
-    message_count: usize,
-    parent_session_id: Option<String>,
-    branch_name: Option<String>,
-}
-
-struct LiveCli {
-    model: String,
-    allowed_tools: Option<AllowedToolSet>,
-    permission_mode: PermissionMode,
-    system_prompt: Vec<String>,
-    runtime: BuiltRuntime,
-    session: SessionHandle,
-    prompt_history: Vec<PromptHistoryEntry>,
-}
-
-#[derive(Debug, Clone)]
-struct PromptHistoryEntry {
-    timestamp_ms: u64,
-    text: String,
-}
-
-struct RuntimePluginState {
-    feature_config: runtime::RuntimeFeatureConfig,
-    tool_registry: GlobalToolRegistry,
-    plugin_registry: PluginRegistry,
-    mcp_state: Option<Arc<Mutex<RuntimeMcpState>>>,
-}
-
-struct RuntimeMcpState {
-    runtime: tokio::runtime::Runtime,
-    manager: McpServerManager,
-    pending_servers: Vec<String>,
-    degraded_report: Option<runtime::McpDegradedReport>,
-}
-
-struct BuiltRuntime {
-    runtime: Option<ConversationRuntime<AnthropicRuntimeClient, CliToolExecutor>>,
-    plugin_registry: PluginRegistry,
-    plugins_active: bool,
-    mcp_state: Option<Arc<Mutex<RuntimeMcpState>>>,
-    mcp_active: bool,
-}
-
-impl BuiltRuntime {
-    fn new(
-        runtime: ConversationRuntime<AnthropicRuntimeClient, CliToolExecutor>,
-        plugin_registry: PluginRegistry,
-        mcp_state: Option<Arc<Mutex<RuntimeMcpState>>>,
-    ) -> Self {
-        Self {
-            runtime: Some(runtime),
-            plugin_registry,
-            plugins_active: true,
-            mcp_state,
-            mcp_active: true,
-        }
-    }
-
-    fn with_hook_abort_signal(mut self, hook_abort_signal: runtime::HookAbortSignal) -> Self {
-        let runtime = self
-            .runtime
-            .take()
-            .expect("runtime should exist before installing hook abort signal");
-        self.runtime = Some(runtime.with_hook_abort_signal(hook_abort_signal));
-        self
-    }
-
-    fn shutdown_plugins(&mut self) -> Result<(), Box<dyn std::error::Error>> {
-        if self.plugins_active {
-            self.plugin_registry.shutdown()?;
-            self.plugins_active = false;
-        }
-        Ok(())
-    }
-
-    fn shutdown_mcp(&mut self) -> Result<(), Box<dyn std::error::Error>> {
-        if self.mcp_active {
-            if let Some(mcp_state) = &self.mcp_state {
-                mcp_state
-                    .lock()
-                    .unwrap_or_else(std::sync::PoisonError::into_inner)
-                    .shutdown()?;
-            }
-            self.mcp_active = false;
-        }
-        Ok(())
-    }
-}
-
-impl Deref for BuiltRuntime {
-    type Target = ConversationRuntime<AnthropicRuntimeClient, CliToolExecutor>;
-
-    fn deref(&self) -> &Self::Target {
-        self.runtime
-            .as_ref()
-            .expect("runtime should exist while built runtime is alive")
-    }
-}
-
-impl DerefMut for BuiltRuntime {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        self.runtime
-            .as_mut()
-            .expect("runtime should exist while built runtime is alive")
-    }
-}
-
-impl Drop for BuiltRuntime {
-    fn drop(&mut self) {
-        let _ = self.shutdown_mcp();
-        let _ = self.shutdown_plugins();
-    }
-}
-
-#[derive(Debug, Deserialize)]
-struct ToolSearchRequest {
-    query: String,
-    max_results: Option<usize>,
-}
-
-#[derive(Debug, Deserialize)]
-struct McpToolRequest {
-    #[serde(rename = "qualifiedName")]
-    qualified_name: Option<String>,
-    tool: Option<String>,
-    arguments: Option<serde_json::Value>,
-}
-
-#[derive(Debug, Deserialize)]
-struct ListMcpResourcesRequest {
-    server: Option<String>,
-}
-
-#[derive(Debug, Deserialize)]
-struct ReadMcpResourceRequest {
-    server: String,
-    uri: String,
-}
-
-impl RuntimeMcpState {
-    fn new(
-        runtime_config: &runtime::RuntimeConfig,
-    ) -> Result<Option<(Self, runtime::McpToolDiscoveryReport)>, Box<dyn std::error::Error>> {
-        let mut manager = McpServerManager::from_runtime_config(runtime_config);
-        if manager.server_names().is_empty() && manager.unsupported_servers().is_empty() {
-            return Ok(None);
-        }
-
-        let runtime = tokio::runtime::Runtime::new()?;
-        let discovery = runtime.block_on(manager.discover_tools_best_effort());
-        let pending_servers = discovery
-            .failed_servers
-            .iter()
-            .map(|failure| failure.server_name.clone())
-            .chain(
-                discovery
-                    .unsupported_servers
-                    .iter()
-                    .map(|server| server.server_name.clone()),
-            )
-            .collect::<BTreeSet<_>>()
-            .into_iter()
-            .collect::<Vec<_>>();
-        let available_tools = discovery
-            .tools
-            .iter()
-            .map(|tool| tool.qualified_name.clone())
-            .collect::<Vec<_>>();
-        let failed_server_names = pending_servers.iter().cloned().collect::<BTreeSet<_>>();
-        let working_servers = manager
-            .server_names()
-            .into_iter()
-            .filter(|server_name| !failed_server_names.contains(server_name))
-            .collect::<Vec<_>>();
-        let failed_servers =
-            discovery
-                .failed_servers
-                .iter()
-                .map(|failure| runtime::McpFailedServer {
-                    server_name: failure.server_name.clone(),
-                    phase: runtime::McpLifecyclePhase::ToolDiscovery,
-                    error: runtime::McpErrorSurface::new(
-                        runtime::McpLifecyclePhase::ToolDiscovery,
-                        Some(failure.server_name.clone()),
-                        failure.error.clone(),
-                        std::collections::BTreeMap::new(),
-                        true,
-                    ),
-                })
-                .chain(discovery.unsupported_servers.iter().map(|server| {
-                    runtime::McpFailedServer {
-                        server_name: server.server_name.clone(),
-                        phase: runtime::McpLifecyclePhase::ServerRegistration,
-                        error: runtime::McpErrorSurface::new(
-                            runtime::McpLifecyclePhase::ServerRegistration,
-                            Some(server.server_name.clone()),
-                            server.reason.clone(),
-                            std::collections::BTreeMap::from([(
-                                "transport".to_string(),
-                                format!("{:?}", server.transport).to_ascii_lowercase(),
-                            )]),
-                            false,
-                        ),
-                    }
-                }))
-                .collect::<Vec<_>>();
-        let degraded_report = (!failed_servers.is_empty()).then(|| {
-            runtime::McpDegradedReport::new(
-                working_servers,
-                failed_servers,
-                available_tools.clone(),
-                available_tools,
-            )
-        });
-
-        Ok(Some((
-            Self {
-                runtime,
-                manager,
-                pending_servers,
-                degraded_report,
-            },
-            discovery,
-        )))
-    }
-
-    fn shutdown(&mut self) -> Result<(), Box<dyn std::error::Error>> {
-        self.runtime.block_on(self.manager.shutdown())?;
-        Ok(())
-    }
-
-    fn pending_servers(&self) -> Option<Vec<String>> {
-        (!self.pending_servers.is_empty()).then(|| self.pending_servers.clone())
-    }
-
-    fn degraded_report(&self) -> Option<runtime::McpDegradedReport> {
-        self.degraded_report.clone()
-    }
-
-    fn server_names(&self) -> Vec<String> {
-        self.manager.server_names()
-    }
-
-    fn call_tool(
-        &mut self,
-        qualified_tool_name: &str,
-        arguments: Option<serde_json::Value>,
-    ) -> Result<String, ToolError> {
-        let response = self
-            .runtime
-            .block_on(self.manager.call_tool(qualified_tool_name, arguments))
-            .map_err(|error| ToolError::new(error.to_string()))?;
-        if let Some(error) = response.error {
-            return Err(ToolError::new(format!(
-                "MCP tool `{qualified_tool_name}` returned JSON-RPC error: {} ({})",
-                error.message, error.code
-            )));
-        }
-
-        let result = response.result.ok_or_else(|| {
-            ToolError::new(format!(
-                "MCP tool `{qualified_tool_name}` returned no result payload"
-            ))
-        })?;
-        serde_json::to_string_pretty(&result).map_err(|error| ToolError::new(error.to_string()))
-    }
-
-    fn list_resources_for_server(&mut self, server_name: &str) -> Result<String, ToolError> {
-        let result = self
-            .runtime
-            .block_on(self.manager.list_resources(server_name))
-            .map_err(|error| ToolError::new(error.to_string()))?;
-        serde_json::to_string_pretty(&json!({
-            "server": server_name,
-            "resources": result.resources,
-        }))
-        .map_err(|error| ToolError::new(error.to_string()))
-    }
-
-    fn list_resources_for_all_servers(&mut self) -> Result<String, ToolError> {
-        let mut resources = Vec::new();
-        let mut failures = Vec::new();
-
-        for server_name in self.server_names() {
-            match self
-                .runtime
-                .block_on(self.manager.list_resources(&server_name))
-            {
-                Ok(result) => resources.push(json!({
-                    "server": server_name,
-                    "resources": result.resources,
-                })),
-                Err(error) => failures.push(json!({
-                    "server": server_name,
-                    "error": error.to_string(),
-                })),
-            }
-        }
-
-        if resources.is_empty() && !failures.is_empty() {
-            let message = failures
-                .iter()
-                .filter_map(|failure| failure.get("error").and_then(serde_json::Value::as_str))
-                .collect::<Vec<_>>()
-                .join("; ");
-            return Err(ToolError::new(message));
-        }
-
-        serde_json::to_string_pretty(&json!({
-            "resources": resources,
-            "failures": failures,
-        }))
-        .map_err(|error| ToolError::new(error.to_string()))
-    }
-
-    fn read_resource(&mut self, server_name: &str, uri: &str) -> Result<String, ToolError> {
-        let result = self
-            .runtime
-            .block_on(self.manager.read_resource(server_name, uri))
-            .map_err(|error| ToolError::new(error.to_string()))?;
-        serde_json::to_string_pretty(&json!({
-            "server": server_name,
-            "contents": result.contents,
-        }))
-        .map_err(|error| ToolError::new(error.to_string()))
-    }
-}
-
-fn build_runtime_mcp_state(
-    runtime_config: &runtime::RuntimeConfig,
-) -> Result<RuntimePluginStateBuildOutput, Box<dyn std::error::Error>> {
-    let Some((mcp_state, discovery)) = RuntimeMcpState::new(runtime_config)? else {
-        return Ok((None, Vec::new()));
-    };
-
-    let mut runtime_tools = discovery
-        .tools
-        .iter()
-        .map(mcp_runtime_tool_definition)
-        .collect::<Vec<_>>();
-    if !mcp_state.server_names().is_empty() {
-        runtime_tools.extend(mcp_wrapper_tool_definitions());
-    }
-
-    Ok((Some(Arc::new(Mutex::new(mcp_state))), runtime_tools))
-}
-
-fn mcp_runtime_tool_definition(tool: &runtime::ManagedMcpTool) -> RuntimeToolDefinition {
-    RuntimeToolDefinition {
-        name: tool.qualified_name.clone(),
-        description: Some(
-            tool.tool
-                .description
-                .clone()
-                .unwrap_or_else(|| format!("Invoke MCP tool `{}`.", tool.qualified_name)),
-        ),
-        input_schema: tool
-            .tool
-            .input_schema
-            .clone()
-            .unwrap_or_else(|| json!({ "type": "object", "additionalProperties": true })),
-        required_permission: permission_mode_for_mcp_tool(&tool.tool),
-    }
-}
-
-fn mcp_wrapper_tool_definitions() -> Vec<RuntimeToolDefinition> {
-    vec![
-        RuntimeToolDefinition {
-            name: "MCPTool".to_string(),
-            description: Some(
-                "Call a configured MCP tool by its qualified name and JSON arguments.".to_string(),
-            ),
-            input_schema: json!({
-                "type": "object",
-                "properties": {
-                    "qualifiedName": { "type": "string" },
-                    "arguments": {}
-                },
-                "required": ["qualifiedName"],
-                "additionalProperties": false
-            }),
-            required_permission: PermissionMode::DangerFullAccess,
-        },
-        RuntimeToolDefinition {
-            name: "ListMcpResourcesTool".to_string(),
-            description: Some(
-                "List MCP resources from one configured server or from every connected server."
-                    .to_string(),
-            ),
-            input_schema: json!({
-                "type": "object",
-                "properties": {
-                    "server": { "type": "string" }
-                },
-                "additionalProperties": false
-            }),
-            required_permission: PermissionMode::ReadOnly,
-        },
-        RuntimeToolDefinition {
-            name: "ReadMcpResourceTool".to_string(),
-            description: Some("Read a specific MCP resource from a configured server.".to_string()),
-            input_schema: json!({
-                "type": "object",
-                "properties": {
-                    "server": { "type": "string" },
-                    "uri": { "type": "string" }
-                },
-                "required": ["server", "uri"],
-                "additionalProperties": false
-            }),
-            required_permission: PermissionMode::ReadOnly,
-        },
-    ]
-}
-
-fn permission_mode_for_mcp_tool(tool: &McpTool) -> PermissionMode {
-    let read_only = mcp_annotation_flag(tool, "readOnlyHint");
-    let destructive = mcp_annotation_flag(tool, "destructiveHint");
-    let open_world = mcp_annotation_flag(tool, "openWorldHint");
-
-    if read_only && !destructive && !open_world {
-        PermissionMode::ReadOnly
-    } else if destructive || open_world {
-        PermissionMode::DangerFullAccess
-    } else {
-        PermissionMode::WorkspaceWrite
-    }
-}
-
-fn mcp_annotation_flag(tool: &McpTool, key: &str) -> bool {
-    tool.annotations
-        .as_ref()
-        .and_then(|annotations| annotations.get(key))
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false)
-}
-
-struct HookAbortMonitor {
-    stop_tx: Option<Sender<()>>,
-    join_handle: Option<JoinHandle<()>>,
-}
-
-impl HookAbortMonitor {
-    fn spawn(abort_signal: runtime::HookAbortSignal) -> Self {
-        Self::spawn_with_waiter(abort_signal, move |stop_rx, abort_signal| {
-            let Ok(runtime) = tokio::runtime::Builder::new_current_thread()
-                .enable_all()
-                .build()
-            else {
-                return;
-            };
-
-            runtime.block_on(async move {
-                let wait_for_stop = tokio::task::spawn_blocking(move || {
-                    let _ = stop_rx.recv();
-                });
-
-                tokio::select! {
-                    result = tokio::signal::ctrl_c() => {
-                        if result.is_ok() {
-                            abort_signal.abort();
-                        }
-                    }
-                    _ = wait_for_stop => {}
-                }
-            });
-        })
-    }
-
-    fn spawn_with_waiter<F>(abort_signal: runtime::HookAbortSignal, wait_for_interrupt: F) -> Self
-    where
-        F: FnOnce(Receiver<()>, runtime::HookAbortSignal) + Send + 'static,
-    {
-        let (stop_tx, stop_rx) = mpsc::channel();
-        let join_handle = thread::spawn(move || wait_for_interrupt(stop_rx, abort_signal));
-
-        Self {
-            stop_tx: Some(stop_tx),
-            join_handle: Some(join_handle),
-        }
-    }
-
-    fn stop(mut self) {
-        if let Some(stop_tx) = self.stop_tx.take() {
-            let _ = stop_tx.send(());
-        }
-        if let Some(join_handle) = self.join_handle.take() {
-            let _ = join_handle.join();
-        }
-    }
-}
-
-impl LiveCli {
-    fn new(
-        model: String,
-        enable_tools: bool,
-        allowed_tools: Option<AllowedToolSet>,
-        permission_mode: PermissionMode,
-    ) -> Result<Self, Box<dyn std::error::Error>> {
-        let system_prompt = build_system_prompt()?;
-        let session_state = Session::new();
-        let session = create_managed_session_handle(&session_state.session_id)?;
-        let runtime = build_runtime(
-            session_state.with_persistence_path(session.path.clone()),
-            &session.id,
-            model.clone(),
-            system_prompt.clone(),
-            enable_tools,
-            true,
-            allowed_tools.clone(),
-            permission_mode,
-            None,
-        )?;
-        let cli = Self {
-            model,
-            allowed_tools,
-            permission_mode,
-            system_prompt,
-            runtime,
-            session,
-            prompt_history: Vec::new(),
-        };
-        cli.persist_session()?;
-        Ok(cli)
-    }
-
-    fn set_reasoning_effort(&mut self, effort: Option<String>) {
-        if let Some(rt) = self.runtime.runtime.as_mut() {
-            rt.api_client_mut().set_reasoning_effort(effort);
-        }
-    }
-
-    fn startup_banner(&self) -> String {
-        let cwd = env::current_dir().map_or_else(
-            |_| "<unknown>".to_string(),
-            |path| path.display().to_string(),
-        );
-        let status = status_context(None).ok();
-        let git_branch = status
-            .as_ref()
-            .and_then(|context| context.git_branch.as_deref())
-            .unwrap_or("unknown");
-        let workspace = status.as_ref().map_or_else(
-            || "unknown".to_string(),
-            |context| context.git_summary.headline(),
-        );
-        let session_path = self.session.path.strip_prefix(Path::new(&cwd)).map_or_else(
-            |_| self.session.path.display().to_string(),
-            |path| path.display().to_string(),
-        );
-        format!(
-            "\x1b[38;5;196m\
- ██████╗██╗      █████╗ ██╗    ██╗\n\
-██╔════╝██║     ██╔══██╗██║    ██║\n\
-██║     ██║     ███████║██║ █╗ ██║\n\
-██║     ██║     ██╔══██║██║███╗██║\n\
-╚██████╗███████╗██║  ██║╚███╔███╔╝\n\
- ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝\x1b[0m \x1b[38;5;208mCode\x1b[0m 🦞\n\n\
-  \x1b[2mModel\x1b[0m            {}\n\
-  \x1b[2mPermissions\x1b[0m      {}\n\
-  \x1b[2mBranch\x1b[0m           {}\n\
-  \x1b[2mWorkspace\x1b[0m        {}\n\
-  \x1b[2mDirectory\x1b[0m        {}\n\
-  \x1b[2mSession\x1b[0m          {}\n\
-  \x1b[2mAuto-save\x1b[0m        {}\n\n\
-  Type \x1b[1m/help\x1b[0m for commands · \x1b[1m/status\x1b[0m for live context · \x1b[2m/resume latest\x1b[0m jumps back to the newest session · \x1b[1m/diff\x1b[0m then \x1b[1m/commit\x1b[0m to ship · \x1b[2mTab\x1b[0m for workflow completions · \x1b[2mShift+Enter\x1b[0m for newline",
-            self.model,
-            self.permission_mode.as_str(),
-            git_branch,
-            workspace,
-            cwd,
-            self.session.id,
-            session_path,
-        )
-    }
-
-    fn repl_completion_candidates(&self) -> Result<Vec<String>, Box<dyn std::error::Error>> {
-        Ok(slash_command_completion_candidates_with_sessions(
-            &self.model,
-            Some(&self.session.id),
-            list_managed_sessions()?
-                .into_iter()
-                .map(|session| session.id)
-                .collect(),
-        ))
-    }
-
-    fn prepare_turn_runtime(
-        &self,
-        emit_output: bool,
-    ) -> Result<(BuiltRuntime, HookAbortMonitor), Box<dyn std::error::Error>> {
-        let hook_abort_signal = runtime::HookAbortSignal::new();
-        let runtime = build_runtime(
-            self.runtime.session().clone(),
-            &self.session.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            true,
-            emit_output,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?
-        .with_hook_abort_signal(hook_abort_signal.clone());
-        let hook_abort_monitor = HookAbortMonitor::spawn(hook_abort_signal);
-
-        Ok((runtime, hook_abort_monitor))
-    }
-
-    fn replace_runtime(&mut self, runtime: BuiltRuntime) -> Result<(), Box<dyn std::error::Error>> {
-        self.runtime.shutdown_plugins()?;
-        self.runtime = runtime;
-        Ok(())
-    }
-
-    fn run_turn(&mut self, input: &str) -> Result<(), Box<dyn std::error::Error>> {
-        let (mut runtime, hook_abort_monitor) = self.prepare_turn_runtime(true)?;
-        let mut spinner = Spinner::new();
-        let mut stdout = io::stdout();
-        spinner.tick(
-            "🦀 Thinking...",
-            TerminalRenderer::new().color_theme(),
-            &mut stdout,
-        )?;
-        let mut permission_prompter = CliPermissionPrompter::new(self.permission_mode);
-        let result = runtime.run_turn(input, Some(&mut permission_prompter));
-        hook_abort_monitor.stop();
-        match result {
-            Ok(summary) => {
-                self.replace_runtime(runtime)?;
-                spinner.finish(
-                    "✨ Done",
-                    TerminalRenderer::new().color_theme(),
-                    &mut stdout,
-                )?;
-                println!();
-                if let Some(event) = summary.auto_compaction {
-                    println!(
-                        "{}",
-                        format_auto_compaction_notice(event.removed_message_count)
-                    );
-                }
-                self.persist_session()?;
-                Ok(())
-            }
-            Err(error) => {
-                runtime.shutdown_plugins()?;
-                spinner.fail(
-                    "❌ Request failed",
-                    TerminalRenderer::new().color_theme(),
-                    &mut stdout,
-                )?;
-                Err(Box::new(error))
-            }
-        }
-    }
-
-    fn run_turn_with_output(
-        &mut self,
-        input: &str,
-        output_format: CliOutputFormat,
-        compact: bool,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        match output_format {
-            CliOutputFormat::Text if compact => self.run_prompt_compact(input),
-            CliOutputFormat::Text => self.run_turn(input),
-            CliOutputFormat::Json => self.run_prompt_json(input),
-        }
-    }
-
-    fn run_prompt_compact(&mut self, input: &str) -> Result<(), Box<dyn std::error::Error>> {
-        let (mut runtime, hook_abort_monitor) = self.prepare_turn_runtime(false)?;
-        let mut permission_prompter = CliPermissionPrompter::new(self.permission_mode);
-        let result = runtime.run_turn(input, Some(&mut permission_prompter));
-        hook_abort_monitor.stop();
-        let summary = result?;
-        self.replace_runtime(runtime)?;
-        self.persist_session()?;
-        let final_text = final_assistant_text(&summary);
-        println!("{final_text}");
-        Ok(())
-    }
-
-    fn run_prompt_json(&mut self, input: &str) -> Result<(), Box<dyn std::error::Error>> {
-        let (mut runtime, hook_abort_monitor) = self.prepare_turn_runtime(false)?;
-        let mut permission_prompter = CliPermissionPrompter::new(self.permission_mode);
-        let result = runtime.run_turn(input, Some(&mut permission_prompter));
-        hook_abort_monitor.stop();
-        let summary = result?;
-        self.replace_runtime(runtime)?;
-        self.persist_session()?;
-        println!(
-            "{}",
-            json!({
-                "message": final_assistant_text(&summary),
-                "model": self.model,
-                "iterations": summary.iterations,
-                "auto_compaction": summary.auto_compaction.map(|event| json!({
-                    "removed_messages": event.removed_message_count,
-                    "notice": format_auto_compaction_notice(event.removed_message_count),
-                })),
-                "tool_uses": collect_tool_uses(&summary),
-                "tool_results": collect_tool_results(&summary),
-                "prompt_cache_events": collect_prompt_cache_events(&summary),
-                "usage": {
-                    "input_tokens": summary.usage.input_tokens,
-                    "output_tokens": summary.usage.output_tokens,
-                    "cache_creation_input_tokens": summary.usage.cache_creation_input_tokens,
-                    "cache_read_input_tokens": summary.usage.cache_read_input_tokens,
-                },
-                "estimated_cost": format_usd(
-                    summary.usage.estimate_cost_usd_with_pricing(
-                        pricing_for_model(&self.model)
-                            .unwrap_or_else(runtime::ModelPricing::default_sonnet_tier)
-                    ).total_cost_usd()
-                )
-            })
-        );
-        Ok(())
-    }
-
-    #[allow(clippy::too_many_lines)]
-    fn handle_repl_command(
-        &mut self,
-        command: SlashCommand,
-    ) -> Result<bool, Box<dyn std::error::Error>> {
-        Ok(match command {
-            SlashCommand::Help => {
-                println!("{}", render_repl_help());
-                false
-            }
-            SlashCommand::Status => {
-                self.print_status();
-                false
-            }
-            SlashCommand::Bughunter { scope } => {
-                self.run_bughunter(scope.as_deref())?;
-                false
-            }
-            SlashCommand::Commit => {
-                self.run_commit(None)?;
-                false
-            }
-            SlashCommand::Pr { context } => {
-                self.run_pr(context.as_deref())?;
-                false
-            }
-            SlashCommand::Issue { context } => {
-                self.run_issue(context.as_deref())?;
-                false
-            }
-            SlashCommand::Ultraplan { task } => {
-                self.run_ultraplan(task.as_deref())?;
-                false
-            }
-            SlashCommand::Teleport { target } => {
-                Self::run_teleport(target.as_deref())?;
-                false
-            }
-            SlashCommand::DebugToolCall => {
-                self.run_debug_tool_call(None)?;
-                false
-            }
-            SlashCommand::Sandbox => {
-                Self::print_sandbox_status();
-                false
-            }
-            SlashCommand::Compact => {
-                self.compact()?;
-                false
-            }
-            SlashCommand::Model { model } => self.set_model(model)?,
-            SlashCommand::Permissions { mode } => self.set_permissions(mode)?,
-            SlashCommand::Clear { confirm } => self.clear_session(confirm)?,
-            SlashCommand::Cost => {
-                self.print_cost();
-                false
-            }
-            SlashCommand::Resume { session_path } => self.resume_session(session_path)?,
-            SlashCommand::Config { section } => {
-                Self::print_config(section.as_deref())?;
-                false
-            }
-            SlashCommand::Mcp { action, target } => {
-                let args = match (action.as_deref(), target.as_deref()) {
-                    (None, None) => None,
-                    (Some(action), None) => Some(action.to_string()),
-                    (Some(action), Some(target)) => Some(format!("{action} {target}")),
-                    (None, Some(target)) => Some(target.to_string()),
-                };
-                Self::print_mcp(args.as_deref(), CliOutputFormat::Text)?;
-                false
-            }
-            SlashCommand::Memory => {
-                Self::print_memory()?;
-                false
-            }
-            SlashCommand::Init => {
-                run_init(CliOutputFormat::Text)?;
-                false
-            }
-            SlashCommand::Diff => {
-                Self::print_diff()?;
-                false
-            }
-            SlashCommand::Version => {
-                Self::print_version(CliOutputFormat::Text);
-                false
-            }
-            SlashCommand::Export { path } => {
-                self.export_session(path.as_deref())?;
-                false
-            }
-            SlashCommand::Session { action, target } => {
-                self.handle_session_command(action.as_deref(), target.as_deref())?
-            }
-            SlashCommand::Plugins { action, target } => {
-                self.handle_plugins_command(action.as_deref(), target.as_deref())?
-            }
-            SlashCommand::Agents { args } => {
-                Self::print_agents(args.as_deref(), CliOutputFormat::Text)?;
-                false
-            }
-            SlashCommand::Skills { args } => {
-                match classify_skills_slash_command(args.as_deref()) {
-                    SkillSlashDispatch::Invoke(prompt) => self.run_turn(&prompt)?,
-                    SkillSlashDispatch::Local => {
-                        Self::print_skills(args.as_deref(), CliOutputFormat::Text)?;
-                    }
-                }
-                false
-            }
-            SlashCommand::Doctor => {
-                println!("{}", render_doctor_report()?.render());
-                false
-            }
-            SlashCommand::History { count } => {
-                self.print_prompt_history(count.as_deref());
-                false
-            }
-            SlashCommand::Login
-            | SlashCommand::Logout
-            | SlashCommand::Vim
-            | SlashCommand::Upgrade
-            | SlashCommand::Stats
-            | SlashCommand::Share
-            | SlashCommand::Feedback
-            | SlashCommand::Files
-            | SlashCommand::Fast
-            | SlashCommand::Exit
-            | SlashCommand::Summary
-            | SlashCommand::Desktop
-            | SlashCommand::Brief
-            | SlashCommand::Advisor
-            | SlashCommand::Stickers
-            | SlashCommand::Insights
-            | SlashCommand::Thinkback
-            | SlashCommand::ReleaseNotes
-            | SlashCommand::SecurityReview
-            | SlashCommand::Keybindings
-            | SlashCommand::PrivacySettings
-            | SlashCommand::Plan { .. }
-            | SlashCommand::Review { .. }
-            | SlashCommand::Tasks { .. }
-            | SlashCommand::Theme { .. }
-            | SlashCommand::Voice { .. }
-            | SlashCommand::Usage { .. }
-            | SlashCommand::Rename { .. }
-            | SlashCommand::Copy { .. }
-            | SlashCommand::Hooks { .. }
-            | SlashCommand::Context { .. }
-            | SlashCommand::Color { .. }
-            | SlashCommand::Effort { .. }
-            | SlashCommand::Branch { .. }
-            | SlashCommand::Rewind { .. }
-            | SlashCommand::Ide { .. }
-            | SlashCommand::Tag { .. }
-            | SlashCommand::OutputStyle { .. }
-            | SlashCommand::AddDir { .. } => {
-                eprintln!("Command registered but not yet implemented.");
-                false
-            }
-            SlashCommand::Unknown(name) => {
-                eprintln!("{}", format_unknown_slash_command(&name));
-                false
-            }
-        })
-    }
-
-    fn persist_session(&self) -> Result<(), Box<dyn std::error::Error>> {
-        self.runtime.session().save_to_path(&self.session.path)?;
-        Ok(())
-    }
-
-    fn print_status(&self) {
-        let cumulative = self.runtime.usage().cumulative_usage();
-        let latest = self.runtime.usage().current_turn_usage();
-        println!(
-            "{}",
-            format_status_report(
-                &self.model,
-                StatusUsage {
-                    message_count: self.runtime.session().messages.len(),
-                    turns: self.runtime.usage().turns(),
-                    latest,
-                    cumulative,
-                    estimated_tokens: self.runtime.estimated_tokens(),
-                },
-                self.permission_mode.as_str(),
-                &status_context(Some(&self.session.path)).expect("status context should load"),
-            )
-        );
-    }
-
-    fn record_prompt_history(&mut self, prompt: &str) {
-        let timestamp_ms = std::time::SystemTime::now()
-            .duration_since(UNIX_EPOCH)
-            .ok()
-            .map_or(self.runtime.session().updated_at_ms, |duration| {
-                u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
-            });
-        let entry = PromptHistoryEntry {
-            timestamp_ms,
-            text: prompt.to_string(),
-        };
-        self.prompt_history.push(entry);
-        if let Err(error) = self.runtime.session_mut().push_prompt_entry(prompt) {
-            eprintln!("warning: failed to persist prompt history: {error}");
-        }
-    }
-
-    fn print_prompt_history(&self, count: Option<&str>) {
-        let limit = match parse_history_count(count) {
-            Ok(limit) => limit,
-            Err(message) => {
-                eprintln!("{message}");
-                return;
-            }
-        };
-        let session_entries = &self.runtime.session().prompt_history;
-        let entries = if session_entries.is_empty() {
-            if self.prompt_history.is_empty() {
-                collect_session_prompt_history(self.runtime.session())
-            } else {
-                self.prompt_history
-                    .iter()
-                    .map(|entry| PromptHistoryEntry {
-                        timestamp_ms: entry.timestamp_ms,
-                        text: entry.text.clone(),
-                    })
-                    .collect()
-            }
-        } else {
-            session_entries
-                .iter()
-                .map(|entry| PromptHistoryEntry {
-                    timestamp_ms: entry.timestamp_ms,
-                    text: entry.text.clone(),
-                })
-                .collect()
-        };
-        println!("{}", render_prompt_history_report(&entries, limit));
-    }
-
-    fn print_sandbox_status() {
-        let cwd = env::current_dir().expect("current dir");
-        let loader = ConfigLoader::default_for(&cwd);
-        let runtime_config = loader
-            .load()
-            .unwrap_or_else(|_| runtime::RuntimeConfig::empty());
-        println!(
-            "{}",
-            format_sandbox_report(&resolve_sandbox_status(runtime_config.sandbox(), &cwd))
-        );
-    }
-
-    fn set_model(&mut self, model: Option<String>) -> Result<bool, Box<dyn std::error::Error>> {
-        let Some(model) = model else {
-            println!(
-                "{}",
-                format_model_report(
-                    &self.model,
-                    self.runtime.session().messages.len(),
-                    self.runtime.usage().turns(),
-                )
-            );
-            return Ok(false);
-        };
-
-        let model = resolve_model_alias_with_config(&model);
-
-        if model == self.model {
-            println!(
-                "{}",
-                format_model_report(
-                    &self.model,
-                    self.runtime.session().messages.len(),
-                    self.runtime.usage().turns(),
-                )
-            );
-            return Ok(false);
-        }
-
-        let previous = self.model.clone();
-        let session = self.runtime.session().clone();
-        let message_count = session.messages.len();
-        let runtime = build_runtime(
-            session,
-            &self.session.id,
-            model.clone(),
-            self.system_prompt.clone(),
-            true,
-            true,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?;
-        self.replace_runtime(runtime)?;
-        self.model.clone_from(&model);
-        println!(
-            "{}",
-            format_model_switch_report(&previous, &model, message_count)
-        );
-        Ok(true)
-    }
-
-    fn set_permissions(
-        &mut self,
-        mode: Option<String>,
-    ) -> Result<bool, Box<dyn std::error::Error>> {
-        let Some(mode) = mode else {
-            println!(
-                "{}",
-                format_permissions_report(self.permission_mode.as_str())
-            );
-            return Ok(false);
-        };
-
-        let normalized = normalize_permission_mode(&mode).ok_or_else(|| {
-            format!(
-                "unsupported permission mode '{mode}'. Use read-only, workspace-write, or danger-full-access."
-            )
-        })?;
-
-        if normalized == self.permission_mode.as_str() {
-            println!("{}", format_permissions_report(normalized));
-            return Ok(false);
-        }
-
-        let previous = self.permission_mode.as_str().to_string();
-        let session = self.runtime.session().clone();
-        self.permission_mode = permission_mode_from_label(normalized);
-        let runtime = build_runtime(
-            session,
-            &self.session.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            true,
-            true,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?;
-        self.replace_runtime(runtime)?;
-        println!(
-            "{}",
-            format_permissions_switch_report(&previous, normalized)
-        );
-        Ok(true)
-    }
-
-    fn clear_session(&mut self, confirm: bool) -> Result<bool, Box<dyn std::error::Error>> {
-        if !confirm {
-            println!(
-                "clear: confirmation required; run /clear --confirm to start a fresh session."
-            );
-            return Ok(false);
-        }
-
-        let previous_session = self.session.clone();
-        let session_state = Session::new();
-        self.session = create_managed_session_handle(&session_state.session_id)?;
-        let runtime = build_runtime(
-            session_state.with_persistence_path(self.session.path.clone()),
-            &self.session.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            true,
-            true,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?;
-        self.replace_runtime(runtime)?;
-        println!(
-            "Session cleared\n  Mode             fresh session\n  Previous session {}\n  Resume previous  /resume {}\n  Preserved model  {}\n  Permission mode  {}\n  New session      {}\n  Session file     {}",
-            previous_session.id,
-            previous_session.id,
-            self.model,
-            self.permission_mode.as_str(),
-            self.session.id,
-            self.session.path.display(),
-        );
-        Ok(true)
-    }
-
-    fn print_cost(&self) {
-        let cumulative = self.runtime.usage().cumulative_usage();
-        println!("{}", format_cost_report(cumulative));
-    }
-
-    fn resume_session(
-        &mut self,
-        session_path: Option<String>,
-    ) -> Result<bool, Box<dyn std::error::Error>> {
-        let Some(session_ref) = session_path else {
-            println!("{}", render_resume_usage());
-            return Ok(false);
-        };
-
-        let handle = resolve_session_reference(&session_ref)?;
-        let session = Session::load_from_path(&handle.path)?;
-        let message_count = session.messages.len();
-        let session_id = session.session_id.clone();
-        let runtime = build_runtime(
-            session,
-            &handle.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            true,
-            true,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?;
-        self.replace_runtime(runtime)?;
-        self.session = SessionHandle {
-            id: session_id,
-            path: handle.path,
-        };
-        println!(
-            "{}",
-            format_resume_report(
-                &self.session.path.display().to_string(),
-                message_count,
-                self.runtime.usage().turns(),
-            )
-        );
-        Ok(true)
-    }
-
-    fn print_config(section: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        println!("{}", render_config_report(section)?);
-        Ok(())
-    }
-
-    fn print_memory() -> Result<(), Box<dyn std::error::Error>> {
-        println!("{}", render_memory_report()?);
-        Ok(())
-    }
-
-    fn print_agents(
-        args: Option<&str>,
-        output_format: CliOutputFormat,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let cwd = env::current_dir()?;
-        match output_format {
-            CliOutputFormat::Text => println!("{}", handle_agents_slash_command(args, &cwd)?),
-            CliOutputFormat::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(&handle_agents_slash_command_json(args, &cwd)?)?
-            ),
-        }
-        Ok(())
-    }
-
-    fn print_mcp(
-        args: Option<&str>,
-        output_format: CliOutputFormat,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        // `claw mcp serve` starts a stdio MCP server exposing claw's built-in
-        // tools. All other `mcp` subcommands fall through to the existing
-        // configured-server reporter (`list`, `status`, ...).
-        if matches!(args.map(str::trim), Some("serve")) {
-            return run_mcp_serve();
-        }
-        let cwd = env::current_dir()?;
-        match output_format {
-            CliOutputFormat::Text => println!("{}", handle_mcp_slash_command(args, &cwd)?),
-            CliOutputFormat::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(&handle_mcp_slash_command_json(args, &cwd)?)?
-            ),
-        }
-        Ok(())
-    }
-
-    fn print_skills(
-        args: Option<&str>,
-        output_format: CliOutputFormat,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let cwd = env::current_dir()?;
-        match output_format {
-            CliOutputFormat::Text => println!("{}", handle_skills_slash_command(args, &cwd)?),
-            CliOutputFormat::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(&handle_skills_slash_command_json(args, &cwd)?)?
-            ),
-        }
-        Ok(())
-    }
-
-    fn print_plugins(
-        action: Option<&str>,
-        target: Option<&str>,
-        output_format: CliOutputFormat,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let cwd = env::current_dir()?;
-        let loader = ConfigLoader::default_for(&cwd);
-        let runtime_config = loader.load()?;
-        let mut manager = build_plugin_manager(&cwd, &loader, &runtime_config);
-        let result = handle_plugins_slash_command(action, target, &mut manager)?;
-        match output_format {
-            CliOutputFormat::Text => println!("{}", result.message),
-            CliOutputFormat::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(&json!({
-                    "kind": "plugin",
-                    "action": action.unwrap_or("list"),
-                    "target": target,
-                    "message": result.message,
-                    "reload_runtime": result.reload_runtime,
-                }))?
-            ),
-        }
-        Ok(())
-    }
-
-    fn print_diff() -> Result<(), Box<dyn std::error::Error>> {
-        println!("{}", render_diff_report()?);
-        Ok(())
-    }
-
-    fn print_version(output_format: CliOutputFormat) {
-        let _ = crate::print_version(output_format);
-    }
-
-    fn export_session(
-        &self,
-        requested_path: Option<&str>,
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let export_path = resolve_export_path(requested_path, self.runtime.session())?;
-        fs::write(&export_path, render_export_text(self.runtime.session()))?;
-        println!(
-            "Export\n  Result           wrote transcript\n  File             {}\n  Messages         {}",
-            export_path.display(),
-            self.runtime.session().messages.len(),
-        );
-        Ok(())
-    }
-
-    fn handle_session_command(
-        &mut self,
-        action: Option<&str>,
-        target: Option<&str>,
-    ) -> Result<bool, Box<dyn std::error::Error>> {
-        match action {
-            None | Some("list") => {
-                println!("{}", render_session_list(&self.session.id)?);
-                Ok(false)
-            }
-            Some("switch") => {
-                let Some(target) = target else {
-                    println!("Usage: /session switch <session-id>");
-                    return Ok(false);
-                };
-                let handle = resolve_session_reference(target)?;
-                let session = Session::load_from_path(&handle.path)?;
-                let message_count = session.messages.len();
-                let session_id = session.session_id.clone();
-                let runtime = build_runtime(
-                    session,
-                    &handle.id,
-                    self.model.clone(),
-                    self.system_prompt.clone(),
-                    true,
-                    true,
-                    self.allowed_tools.clone(),
-                    self.permission_mode,
-                    None,
-                )?;
-                self.replace_runtime(runtime)?;
-                self.session = SessionHandle {
-                    id: session_id,
-                    path: handle.path,
-                };
-                println!(
-                    "Session switched\n  Active session   {}\n  File             {}\n  Messages         {}",
-                    self.session.id,
-                    self.session.path.display(),
-                    message_count,
-                );
-                Ok(true)
-            }
-            Some("fork") => {
-                let forked = self.runtime.fork_session(target.map(ToOwned::to_owned));
-                let parent_session_id = self.session.id.clone();
-                let handle = create_managed_session_handle(&forked.session_id)?;
-                let branch_name = forked
-                    .fork
-                    .as_ref()
-                    .and_then(|fork| fork.branch_name.clone());
-                let forked = forked.with_persistence_path(handle.path.clone());
-                let message_count = forked.messages.len();
-                forked.save_to_path(&handle.path)?;
-                let runtime = build_runtime(
-                    forked,
-                    &handle.id,
-                    self.model.clone(),
-                    self.system_prompt.clone(),
-                    true,
-                    true,
-                    self.allowed_tools.clone(),
-                    self.permission_mode,
-                    None,
-                )?;
-                self.replace_runtime(runtime)?;
-                self.session = handle;
-                println!(
-                    "Session forked\n  Parent session   {}\n  Active session   {}\n  Branch           {}\n  File             {}\n  Messages         {}",
-                    parent_session_id,
-                    self.session.id,
-                    branch_name.as_deref().unwrap_or("(unnamed)"),
-                    self.session.path.display(),
-                    message_count,
-                );
-                Ok(true)
-            }
-            Some("delete") => {
-                let Some(target) = target else {
-                    println!("Usage: /session delete <session-id> [--force]");
-                    return Ok(false);
-                };
-                let handle = resolve_session_reference(target)?;
-                if handle.id == self.session.id {
-                    println!(
-                        "delete: refusing to delete the active session '{}'.\nSwitch to another session first with /session switch <session-id>.",
-                        handle.id
-                    );
-                    return Ok(false);
-                }
-                if !confirm_session_deletion(&handle.id) {
-                    println!("delete: cancelled.");
-                    return Ok(false);
-                }
-                delete_managed_session(&handle.path)?;
-                println!(
-                    "Session deleted\n  Deleted session  {}\n  File             {}",
-                    handle.id,
-                    handle.path.display(),
-                );
-                Ok(false)
-            }
-            Some("delete-force") => {
-                let Some(target) = target else {
-                    println!("Usage: /session delete <session-id> [--force]");
-                    return Ok(false);
-                };
-                let handle = resolve_session_reference(target)?;
-                if handle.id == self.session.id {
-                    println!(
-                        "delete: refusing to delete the active session '{}'.\nSwitch to another session first with /session switch <session-id>.",
-                        handle.id
-                    );
-                    return Ok(false);
-                }
-                delete_managed_session(&handle.path)?;
-                println!(
-                    "Session deleted\n  Deleted session  {}\n  File             {}",
-                    handle.id,
-                    handle.path.display(),
-                );
-                Ok(false)
-            }
-            Some(other) => {
-                println!(
-                    "Unknown /session action '{other}'. Use /session list, /session switch <session-id>, /session fork [branch-name], or /session delete <session-id> [--force]."
-                );
-                Ok(false)
-            }
-        }
-    }
-
-    fn handle_plugins_command(
-        &mut self,
-        action: Option<&str>,
-        target: Option<&str>,
-    ) -> Result<bool, Box<dyn std::error::Error>> {
-        let cwd = env::current_dir()?;
-        let loader = ConfigLoader::default_for(&cwd);
-        let runtime_config = loader.load()?;
-        let mut manager = build_plugin_manager(&cwd, &loader, &runtime_config);
-        let result = handle_plugins_slash_command(action, target, &mut manager)?;
-        println!("{}", result.message);
-        if result.reload_runtime {
-            self.reload_runtime_features()?;
-        }
-        Ok(false)
-    }
-
-    fn reload_runtime_features(&mut self) -> Result<(), Box<dyn std::error::Error>> {
-        let runtime = build_runtime(
-            self.runtime.session().clone(),
-            &self.session.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            true,
-            true,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?;
-        self.replace_runtime(runtime)?;
-        self.persist_session()
-    }
-
-    fn compact(&mut self) -> Result<(), Box<dyn std::error::Error>> {
-        let result = self.runtime.compact(CompactionConfig::default());
-        let removed = result.removed_message_count;
-        let kept = result.compacted_session.messages.len();
-        let skipped = removed == 0;
-        let runtime = build_runtime(
-            result.compacted_session,
-            &self.session.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            true,
-            true,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            None,
-        )?;
-        self.replace_runtime(runtime)?;
-        self.persist_session()?;
-        println!("{}", format_compact_report(removed, kept, skipped));
-        Ok(())
-    }
-
-    fn run_internal_prompt_text_with_progress(
-        &self,
-        prompt: &str,
-        enable_tools: bool,
-        progress: Option<InternalPromptProgressReporter>,
-    ) -> Result<String, Box<dyn std::error::Error>> {
-        let session = self.runtime.session().clone();
-        let mut runtime = build_runtime(
-            session,
-            &self.session.id,
-            self.model.clone(),
-            self.system_prompt.clone(),
-            enable_tools,
-            false,
-            self.allowed_tools.clone(),
-            self.permission_mode,
-            progress,
-        )?;
-        let mut permission_prompter = CliPermissionPrompter::new(self.permission_mode);
-        let summary = runtime.run_turn(prompt, Some(&mut permission_prompter))?;
-        let text = final_assistant_text(&summary).trim().to_string();
-        runtime.shutdown_plugins()?;
-        Ok(text)
-    }
-
-    fn run_internal_prompt_text(
-        &self,
-        prompt: &str,
-        enable_tools: bool,
-    ) -> Result<String, Box<dyn std::error::Error>> {
-        self.run_internal_prompt_text_with_progress(prompt, enable_tools, None)
-    }
-
-    fn run_bughunter(&self, scope: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        println!("{}", format_bughunter_report(scope));
-        Ok(())
-    }
-
-    fn run_ultraplan(&self, task: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        println!("{}", format_ultraplan_report(task));
-        Ok(())
-    }
-
-    fn run_teleport(target: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        let Some(target) = target.map(str::trim).filter(|value| !value.is_empty()) else {
-            println!("Usage: /teleport <symbol-or-path>");
-            return Ok(());
-        };
-
-        println!("{}", render_teleport_report(target)?);
-        Ok(())
-    }
-
-    fn run_debug_tool_call(&self, args: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        validate_no_args("/debug-tool-call", args)?;
-        println!("{}", render_last_tool_debug_report(self.runtime.session())?);
-        Ok(())
-    }
-
-    fn run_commit(&mut self, args: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        validate_no_args("/commit", args)?;
-        let status = git_output(&["status", "--short", "--branch"])?;
-        let summary = parse_git_workspace_summary(Some(&status));
-        let branch = parse_git_status_branch(Some(&status));
-        if summary.is_clean() {
-            println!("{}", format_commit_skipped_report());
-            return Ok(());
-        }
-
-        println!(
-            "{}",
-            format_commit_preflight_report(branch.as_deref(), summary)
-        );
-        Ok(())
-    }
-
-    fn run_pr(&self, context: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        let branch =
-            resolve_git_branch_for(&env::current_dir()?).unwrap_or_else(|| "unknown".to_string());
-        println!("{}", format_pr_report(&branch, context));
-        Ok(())
-    }
-
-    fn run_issue(&self, context: Option<&str>) -> Result<(), Box<dyn std::error::Error>> {
-        println!("{}", format_issue_report(context));
-        Ok(())
-    }
-}
-
-fn sessions_dir() -> Result<PathBuf, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let store = runtime::SessionStore::from_cwd(&cwd)
-        .map_err(|e| Box::new(e) as Box<dyn std::error::Error>)?;
-    Ok(store.sessions_dir().to_path_buf())
-}
-
-fn create_managed_session_handle(
-    session_id: &str,
-) -> Result<SessionHandle, Box<dyn std::error::Error>> {
-    let id = session_id.to_string();
-    let path = sessions_dir()?.join(format!("{id}.{PRIMARY_SESSION_EXTENSION}"));
-    Ok(SessionHandle { id, path })
-}
-
-fn resolve_session_reference(reference: &str) -> Result<SessionHandle, Box<dyn std::error::Error>> {
-    if SESSION_REFERENCE_ALIASES
-        .iter()
-        .any(|alias| reference.eq_ignore_ascii_case(alias))
-    {
-        let latest = latest_managed_session()?;
-        return Ok(SessionHandle {
-            id: latest.id,
-            path: latest.path,
-        });
-    }
-
-    let direct = PathBuf::from(reference);
-    let looks_like_path = direct.extension().is_some() || direct.components().count() > 1;
-    let path = if direct.exists() {
-        direct
-    } else if looks_like_path {
-        return Err(format_missing_session_reference(reference).into());
-    } else {
-        resolve_managed_session_path(reference)?
-    };
-    let id = path
-        .file_name()
-        .and_then(|value| value.to_str())
-        .and_then(|name| {
-            name.strip_suffix(&format!(".{PRIMARY_SESSION_EXTENSION}"))
-                .or_else(|| name.strip_suffix(&format!(".{LEGACY_SESSION_EXTENSION}")))
-        })
-        .unwrap_or(reference)
-        .to_string();
-    Ok(SessionHandle { id, path })
-}
-
-fn resolve_managed_session_path(session_id: &str) -> Result<PathBuf, Box<dyn std::error::Error>> {
-    let directory = sessions_dir()?;
-    for extension in [PRIMARY_SESSION_EXTENSION, LEGACY_SESSION_EXTENSION] {
-        let path = directory.join(format!("{session_id}.{extension}"));
-        if path.exists() {
-            return Ok(path);
-        }
-    }
-    // Backward compatibility: pre-isolation sessions were stored at
-    // `.claw/sessions/<id>.{jsonl,json}` without the per-workspace hash
-    // subdirectory. Walk up from `directory` to the `.claw/sessions/` root
-    // and try the flat layout as a fallback so users do not lose access
-    // to their pre-upgrade managed sessions.
-    if let Some(legacy_root) = directory
-        .parent()
-        .filter(|parent| parent.file_name().is_some_and(|name| name == "sessions"))
-    {
-        for extension in [PRIMARY_SESSION_EXTENSION, LEGACY_SESSION_EXTENSION] {
-            let path = legacy_root.join(format!("{session_id}.{extension}"));
-            if path.exists() {
-                return Ok(path);
-            }
-        }
-    }
-    Err(format_missing_session_reference(session_id).into())
-}
-
-fn is_managed_session_file(path: &Path) -> bool {
-    path.extension()
-        .and_then(|ext| ext.to_str())
-        .is_some_and(|extension| {
-            extension == PRIMARY_SESSION_EXTENSION || extension == LEGACY_SESSION_EXTENSION
-        })
-}
-
-fn collect_sessions_from_dir(
-    directory: &Path,
-    sessions: &mut Vec<ManagedSessionSummary>,
-) -> Result<(), Box<dyn std::error::Error>> {
-    if !directory.exists() {
-        return Ok(());
-    }
-    for entry in fs::read_dir(directory)? {
-        let entry = entry?;
-        let path = entry.path();
-        if !is_managed_session_file(&path) {
-            continue;
-        }
-        let metadata = entry.metadata()?;
-        let modified_epoch_millis = metadata
-            .modified()
-            .ok()
-            .and_then(|time| time.duration_since(UNIX_EPOCH).ok())
-            .map(|duration| duration.as_millis())
-            .unwrap_or_default();
-        let (id, message_count, parent_session_id, branch_name) =
-            match Session::load_from_path(&path) {
-                Ok(session) => {
-                    let parent_session_id = session
-                        .fork
-                        .as_ref()
-                        .map(|fork| fork.parent_session_id.clone());
-                    let branch_name = session
-                        .fork
-                        .as_ref()
-                        .and_then(|fork| fork.branch_name.clone());
-                    (
-                        session.session_id,
-                        session.messages.len(),
-                        parent_session_id,
-                        branch_name,
-                    )
-                }
-                Err(_) => (
-                    path.file_stem()
-                        .and_then(|value| value.to_str())
-                        .unwrap_or("unknown")
-                        .to_string(),
-                    0,
-                    None,
-                    None,
-                ),
-            };
-        sessions.push(ManagedSessionSummary {
-            id,
-            path,
-            modified_epoch_millis,
-            message_count,
-            parent_session_id,
-            branch_name,
-        });
-    }
-    Ok(())
-}
-
-fn list_managed_sessions() -> Result<Vec<ManagedSessionSummary>, Box<dyn std::error::Error>> {
-    let mut sessions = Vec::new();
-    let primary_dir = sessions_dir()?;
-    collect_sessions_from_dir(&primary_dir, &mut sessions)?;
-
-    // Backward compatibility: include sessions stored in the pre-isolation
-    // flat `.claw/sessions/` root so users do not lose access to existing
-    // managed sessions after the workspace-hashed subdirectory rollout.
-    if let Some(legacy_root) = primary_dir
-        .parent()
-        .filter(|parent| parent.file_name().is_some_and(|name| name == "sessions"))
-    {
-        collect_sessions_from_dir(legacy_root, &mut sessions)?;
-    }
-
-    sessions.sort_by(|left, right| {
-        right
-            .modified_epoch_millis
-            .cmp(&left.modified_epoch_millis)
-            .then_with(|| right.id.cmp(&left.id))
-    });
-    Ok(sessions)
-}
-
-fn latest_managed_session() -> Result<ManagedSessionSummary, Box<dyn std::error::Error>> {
-    list_managed_sessions()?
-        .into_iter()
-        .next()
-        .ok_or_else(|| format_no_managed_sessions().into())
-}
-
-fn delete_managed_session(path: &Path) -> Result<(), Box<dyn std::error::Error>> {
-    if !path.exists() {
-        return Err(format!("session file does not exist: {}", path.display()).into());
-    }
-    fs::remove_file(path)?;
-    Ok(())
-}
-
-fn confirm_session_deletion(session_id: &str) -> bool {
-    print!("Delete session '{session_id}'? This cannot be undone. [y/N]: ");
-    io::stdout().flush().unwrap_or(());
-    let mut answer = String::new();
-    if io::stdin().read_line(&mut answer).is_err() {
-        return false;
-    }
-    matches!(answer.trim(), "y" | "Y" | "yes" | "Yes" | "YES")
-}
-
-fn format_missing_session_reference(reference: &str) -> String {
-    format!(
-        "session not found: {reference}\nHint: managed sessions live in .claw/sessions/. Try `{LATEST_SESSION_REFERENCE}` for the most recent session or `/session list` in the REPL."
-    )
-}
-
-fn format_no_managed_sessions() -> String {
-    format!(
-        "no managed sessions found in .claw/sessions/\nStart `claw` to create a session, then rerun with `--resume {LATEST_SESSION_REFERENCE}`."
-    )
-}
-
-fn render_session_list(active_session_id: &str) -> Result<String, Box<dyn std::error::Error>> {
-    let sessions = list_managed_sessions()?;
-    let mut lines = vec![
-        "Sessions".to_string(),
-        format!("  Directory         {}", sessions_dir()?.display()),
-    ];
-    if sessions.is_empty() {
-        lines.push("  No managed sessions saved yet.".to_string());
-        return Ok(lines.join("\n"));
-    }
-    for session in sessions {
-        let marker = if session.id == active_session_id {
-            "● current"
-        } else {
-            "○ saved"
-        };
-        let lineage = match (
-            session.branch_name.as_deref(),
-            session.parent_session_id.as_deref(),
-        ) {
-            (Some(branch_name), Some(parent_session_id)) => {
-                format!(" branch={branch_name} from={parent_session_id}")
-            }
-            (None, Some(parent_session_id)) => format!(" from={parent_session_id}"),
-            (Some(branch_name), None) => format!(" branch={branch_name}"),
-            (None, None) => String::new(),
-        };
-        lines.push(format!(
-            "  {id:<20} {marker:<10} msgs={msgs:<4} modified={modified}{lineage} path={path}",
-            id = session.id,
-            msgs = session.message_count,
-            modified = format_session_modified_age(session.modified_epoch_millis),
-            lineage = lineage,
-            path = session.path.display(),
-        ));
-    }
-    Ok(lines.join("\n"))
-}
-
-fn format_session_modified_age(modified_epoch_millis: u128) -> String {
-    let now = std::time::SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .ok()
-        .map_or(modified_epoch_millis, |duration| duration.as_millis());
-    let delta_seconds = now
-        .saturating_sub(modified_epoch_millis)
-        .checked_div(1_000)
-        .unwrap_or_default();
-    match delta_seconds {
-        0..=4 => "just-now".to_string(),
-        5..=59 => format!("{delta_seconds}s-ago"),
-        60..=3_599 => format!("{}m-ago", delta_seconds / 60),
-        3_600..=86_399 => format!("{}h-ago", delta_seconds / 3_600),
-        _ => format!("{}d-ago", delta_seconds / 86_400),
-    }
-}
-
-fn write_session_clear_backup(
-    session: &Session,
-    session_path: &Path,
-) -> Result<PathBuf, Box<dyn std::error::Error>> {
-    let backup_path = session_clear_backup_path(session_path);
-    session.save_to_path(&backup_path)?;
-    Ok(backup_path)
-}
-
-fn session_clear_backup_path(session_path: &Path) -> PathBuf {
-    let timestamp = std::time::SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .ok()
-        .map_or(0, |duration| duration.as_millis());
-    let file_name = session_path
-        .file_name()
-        .and_then(|value| value.to_str())
-        .unwrap_or("session.jsonl");
-    session_path.with_file_name(format!("{file_name}.before-clear-{timestamp}.bak"))
-}
-
-fn render_repl_help() -> String {
-    [
-        "REPL".to_string(),
-        "  /exit                Quit the REPL".to_string(),
-        "  /quit                Quit the REPL".to_string(),
-        "  Up/Down              Navigate prompt history".to_string(),
-        "  Ctrl-R               Reverse-search prompt history".to_string(),
-        "  Tab                  Complete commands, modes, and recent sessions".to_string(),
-        "  Ctrl-C               Clear input (or exit on empty prompt)".to_string(),
-        "  Shift+Enter/Ctrl+J   Insert a newline".to_string(),
-        "  Auto-save            .claw/sessions/<session-id>.jsonl".to_string(),
-        "  Resume latest        /resume latest".to_string(),
-        "  Browse sessions      /session list".to_string(),
-        "  Show prompt history  /history [count]".to_string(),
-        String::new(),
-        render_slash_command_help(),
-    ]
-    .join(
-        "
-",
-    )
-}
-
-fn print_status_snapshot(
-    model: &str,
-    permission_mode: PermissionMode,
-    output_format: CliOutputFormat,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let usage = StatusUsage {
-        message_count: 0,
-        turns: 0,
-        latest: TokenUsage::default(),
-        cumulative: TokenUsage::default(),
-        estimated_tokens: 0,
-    };
-    let context = status_context(None)?;
-    match output_format {
-        CliOutputFormat::Text => println!(
-            "{}",
-            format_status_report(model, usage, permission_mode.as_str(), &context)
-        ),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&status_json_value(
-                model,
-                usage,
-                permission_mode.as_str(),
-                &context,
-            ))?
-        ),
-    }
-    Ok(())
-}
-
-fn status_json_value(
-    model: &str,
-    usage: StatusUsage,
-    permission_mode: &str,
-    context: &StatusContext,
-) -> serde_json::Value {
-    json!({
-        "kind": "status",
-        "model": model,
-        "permission_mode": permission_mode,
-        "usage": {
-            "messages": usage.message_count,
-            "turns": usage.turns,
-            "latest_total": usage.latest.total_tokens(),
-            "cumulative_input": usage.cumulative.input_tokens,
-            "cumulative_output": usage.cumulative.output_tokens,
-            "cumulative_total": usage.cumulative.total_tokens(),
-            "estimated_tokens": usage.estimated_tokens,
-        },
-        "workspace": {
-            "cwd": context.cwd,
-            "project_root": context.project_root,
-            "git_branch": context.git_branch,
-            "git_state": context.git_summary.headline(),
-            "changed_files": context.git_summary.changed_files,
-            "staged_files": context.git_summary.staged_files,
-            "unstaged_files": context.git_summary.unstaged_files,
-            "untracked_files": context.git_summary.untracked_files,
-            "session": context.session_path.as_ref().map_or_else(|| "live-repl".to_string(), |path| path.display().to_string()),
-            "loaded_config_files": context.loaded_config_files,
-            "discovered_config_files": context.discovered_config_files,
-            "memory_file_count": context.memory_file_count,
-        },
-        "sandbox": {
-            "enabled": context.sandbox_status.enabled,
-            "active": context.sandbox_status.active,
-            "supported": context.sandbox_status.supported,
-            "in_container": context.sandbox_status.in_container,
-            "requested_namespace": context.sandbox_status.requested.namespace_restrictions,
-            "active_namespace": context.sandbox_status.namespace_active,
-            "requested_network": context.sandbox_status.requested.network_isolation,
-            "active_network": context.sandbox_status.network_active,
-            "filesystem_mode": context.sandbox_status.filesystem_mode.as_str(),
-            "filesystem_active": context.sandbox_status.filesystem_active,
-            "allowed_mounts": context.sandbox_status.allowed_mounts,
-            "markers": context.sandbox_status.container_markers,
-            "fallback_reason": context.sandbox_status.fallback_reason,
-        }
-    })
-}
-
-fn status_context(
-    session_path: Option<&Path>,
-) -> Result<StatusContext, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    let discovered_config_files = loader.discover().len();
-    let runtime_config = loader.load()?;
-    let project_context = ProjectContext::discover_with_git(&cwd, DEFAULT_DATE)?;
-    let (project_root, git_branch) =
-        parse_git_status_metadata(project_context.git_status.as_deref());
-    let git_summary = parse_git_workspace_summary(project_context.git_status.as_deref());
-    let sandbox_status = resolve_sandbox_status(runtime_config.sandbox(), &cwd);
-    Ok(StatusContext {
-        cwd,
-        session_path: session_path.map(Path::to_path_buf),
-        loaded_config_files: runtime_config.loaded_entries().len(),
-        discovered_config_files,
-        memory_file_count: project_context.instruction_files.len(),
-        project_root,
-        git_branch,
-        git_summary,
-        sandbox_status,
-    })
-}
-
-fn format_status_report(
-    model: &str,
-    usage: StatusUsage,
-    permission_mode: &str,
-    context: &StatusContext,
-) -> String {
-    [
-        format!(
-            "Status
-  Model            {model}
-  Permission mode  {permission_mode}
-  Messages         {}
-  Turns            {}
-  Estimated tokens {}",
-            usage.message_count, usage.turns, usage.estimated_tokens,
-        ),
-        format!(
-            "Usage
-  Latest total     {}
-  Cumulative input {}
-  Cumulative output {}
-  Cumulative total {}",
-            usage.latest.total_tokens(),
-            usage.cumulative.input_tokens,
-            usage.cumulative.output_tokens,
-            usage.cumulative.total_tokens(),
-        ),
-        format!(
-            "Workspace
-  Cwd              {}
-  Project root     {}
-  Git branch       {}
-  Git state        {}
-  Changed files    {}
-  Staged           {}
-  Unstaged         {}
-  Untracked        {}
-  Session          {}
-  Config files     loaded {}/{}
-  Memory files     {}
-  Suggested flow   /status → /diff → /commit",
-            context.cwd.display(),
-            context
-                .project_root
-                .as_ref()
-                .map_or_else(|| "unknown".to_string(), |path| path.display().to_string()),
-            context.git_branch.as_deref().unwrap_or("unknown"),
-            context.git_summary.headline(),
-            context.git_summary.changed_files,
-            context.git_summary.staged_files,
-            context.git_summary.unstaged_files,
-            context.git_summary.untracked_files,
-            context.session_path.as_ref().map_or_else(
-                || "live-repl".to_string(),
-                |path| path.display().to_string()
-            ),
-            context.loaded_config_files,
-            context.discovered_config_files,
-            context.memory_file_count,
-        ),
-        format_sandbox_report(&context.sandbox_status),
-    ]
-    .join(
-        "
-
-",
-    )
-}
-
-fn format_sandbox_report(status: &runtime::SandboxStatus) -> String {
-    format!(
-        "Sandbox
-  Enabled           {}
-  Active            {}
-  Supported         {}
-  In container      {}
-  Requested ns      {}
-  Active ns         {}
-  Requested net     {}
-  Active net        {}
-  Filesystem mode   {}
-  Filesystem active {}
-  Allowed mounts    {}
-  Markers           {}
-  Fallback reason   {}",
-        status.enabled,
-        status.active,
-        status.supported,
-        status.in_container,
-        status.requested.namespace_restrictions,
-        status.namespace_active,
-        status.requested.network_isolation,
-        status.network_active,
-        status.filesystem_mode.as_str(),
-        status.filesystem_active,
-        if status.allowed_mounts.is_empty() {
-            "<none>".to_string()
-        } else {
-            status.allowed_mounts.join(", ")
-        },
-        if status.container_markers.is_empty() {
-            "<none>".to_string()
-        } else {
-            status.container_markers.join(", ")
-        },
-        status
-            .fallback_reason
-            .clone()
-            .unwrap_or_else(|| "<none>".to_string()),
-    )
-}
-
-fn format_commit_preflight_report(branch: Option<&str>, summary: GitWorkspaceSummary) -> String {
-    format!(
-        "Commit
-  Result           ready
-  Branch           {}
-  Workspace        {}
-  Changed files    {}
-  Action           create a git commit from the current workspace changes",
-        branch.unwrap_or("unknown"),
-        summary.headline(),
-        summary.changed_files,
-    )
-}
-
-fn format_commit_skipped_report() -> String {
-    "Commit
-  Result           skipped
-  Reason           no workspace changes
-  Action           create a git commit from the current workspace changes
-  Next             /status to inspect context · /diff to inspect repo changes"
-        .to_string()
-}
-
-fn print_sandbox_status_snapshot(
-    output_format: CliOutputFormat,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    let runtime_config = loader
-        .load()
-        .unwrap_or_else(|_| runtime::RuntimeConfig::empty());
-    let status = resolve_sandbox_status(runtime_config.sandbox(), &cwd);
-    match output_format {
-        CliOutputFormat::Text => println!("{}", format_sandbox_report(&status)),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&sandbox_json_value(&status))?
-        ),
-    }
-    Ok(())
-}
-
-fn sandbox_json_value(status: &runtime::SandboxStatus) -> serde_json::Value {
-    json!({
-        "kind": "sandbox",
-        "enabled": status.enabled,
-        "active": status.active,
-        "supported": status.supported,
-        "in_container": status.in_container,
-        "requested_namespace": status.requested.namespace_restrictions,
-        "active_namespace": status.namespace_active,
-        "requested_network": status.requested.network_isolation,
-        "active_network": status.network_active,
-        "filesystem_mode": status.filesystem_mode.as_str(),
-        "filesystem_active": status.filesystem_active,
-        "allowed_mounts": status.allowed_mounts,
-        "markers": status.container_markers,
-        "fallback_reason": status.fallback_reason,
-    })
-}
-
-fn render_help_topic(topic: LocalHelpTopic) -> String {
-    match topic {
-        LocalHelpTopic::Status => "Status
-  Usage            claw status
-  Purpose          show the local workspace snapshot without entering the REPL
-  Output           model, permissions, git state, config files, and sandbox status
-  Related          /status · claw --resume latest /status"
-            .to_string(),
-        LocalHelpTopic::Sandbox => "Sandbox
-  Usage            claw sandbox
-  Purpose          inspect the resolved sandbox and isolation state for the current directory
-  Output           namespace, network, filesystem, and fallback details
-  Related          /sandbox · claw status"
-            .to_string(),
-        LocalHelpTopic::Doctor => "Doctor
-  Usage            claw doctor
-  Purpose          diagnose local auth, config, workspace, sandbox, and build metadata
-  Output           local-only health report; no provider request or session resume required
-  Related          /doctor · claw --resume latest /doctor"
-            .to_string(),
-    }
-}
-
-fn print_help_topic(topic: LocalHelpTopic) {
-    println!("{}", render_help_topic(topic));
-}
-
-fn render_config_report(section: Option<&str>) -> Result<String, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    let discovered = loader.discover();
-    let runtime_config = loader.load()?;
-
-    let mut lines = vec![
-        format!(
-            "Config
-  Working directory {}
-  Loaded files      {}
-  Merged keys       {}",
-            cwd.display(),
-            runtime_config.loaded_entries().len(),
-            runtime_config.merged().len()
-        ),
-        "Discovered files".to_string(),
-    ];
-    for entry in discovered {
-        let source = match entry.source {
-            ConfigSource::User => "user",
-            ConfigSource::Project => "project",
-            ConfigSource::Local => "local",
-        };
-        let status = if runtime_config
-            .loaded_entries()
-            .iter()
-            .any(|loaded_entry| loaded_entry.path == entry.path)
-        {
-            "loaded"
-        } else {
-            "missing"
-        };
-        lines.push(format!(
-            "  {source:<7} {status:<7} {}",
-            entry.path.display()
-        ));
-    }
-
-    if let Some(section) = section {
-        lines.push(format!("Merged section: {section}"));
-        let value = match section {
-            "env" => runtime_config.get("env"),
-            "hooks" => runtime_config.get("hooks"),
-            "model" => runtime_config.get("model"),
-            "plugins" => runtime_config
-                .get("plugins")
-                .or_else(|| runtime_config.get("enabledPlugins")),
-            other => {
-                lines.push(format!(
-                    "  Unsupported config section '{other}'. Use env, hooks, model, or plugins."
-                ));
-                return Ok(lines.join(
-                    "
-",
-                ));
-            }
-        };
-        lines.push(format!(
-            "  {}",
-            match value {
-                Some(value) => value.render(),
-                None => "<unset>".to_string(),
-            }
-        ));
-        return Ok(lines.join(
-            "
-",
-        ));
-    }
-
-    lines.push("Merged JSON".to_string());
-    lines.push(format!("  {}", runtime_config.as_json().render()));
-    Ok(lines.join(
-        "
-",
-    ))
-}
-
-fn render_memory_report() -> Result<String, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let project_context = ProjectContext::discover(&cwd, DEFAULT_DATE)?;
-    let mut lines = vec![format!(
-        "Memory
-  Working directory {}
-  Instruction files {}",
-        cwd.display(),
-        project_context.instruction_files.len()
-    )];
-    if project_context.instruction_files.is_empty() {
-        lines.push("Discovered files".to_string());
-        lines.push(
-            "  No CLAUDE instruction files discovered in the current directory ancestry."
-                .to_string(),
-        );
-    } else {
-        lines.push("Discovered files".to_string());
-        for (index, file) in project_context.instruction_files.iter().enumerate() {
-            let preview = file.content.lines().next().unwrap_or("").trim();
-            let preview = if preview.is_empty() {
-                "<empty>"
-            } else {
-                preview
-            };
-            lines.push(format!("  {}. {}", index + 1, file.path.display(),));
-            lines.push(format!(
-                "     lines={} preview={}",
-                file.content.lines().count(),
-                preview
-            ));
-        }
-    }
-    Ok(lines.join(
-        "
-",
-    ))
-}
-
-fn init_claude_md() -> Result<String, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    Ok(initialize_repo(&cwd)?.render())
-}
-
-fn run_init(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let message = init_claude_md()?;
-    match output_format {
-        CliOutputFormat::Text => println!("{message}"),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&init_json_value(&message))?
-        ),
-    }
-    Ok(())
-}
-
-fn init_json_value(message: &str) -> serde_json::Value {
-    json!({
-        "kind": "init",
-        "message": message,
-    })
-}
-
-fn normalize_permission_mode(mode: &str) -> Option<&'static str> {
-    match mode.trim() {
-        "read-only" => Some("read-only"),
-        "workspace-write" => Some("workspace-write"),
-        "danger-full-access" => Some("danger-full-access"),
-        _ => None,
-    }
-}
-
-fn render_diff_report() -> Result<String, Box<dyn std::error::Error>> {
-    render_diff_report_for(&env::current_dir()?)
-}
-
-fn render_diff_report_for(cwd: &Path) -> Result<String, Box<dyn std::error::Error>> {
-    let staged = run_git_diff_command_in(cwd, &["diff", "--cached"])?;
-    let unstaged = run_git_diff_command_in(cwd, &["diff"])?;
-    if staged.trim().is_empty() && unstaged.trim().is_empty() {
-        return Ok(
-            "Diff\n  Result           clean working tree\n  Detail           no current changes"
-                .to_string(),
-        );
-    }
-
-    let mut sections = Vec::new();
-    if !staged.trim().is_empty() {
-        sections.push(format!("Staged changes:\n{}", staged.trim_end()));
-    }
-    if !unstaged.trim().is_empty() {
-        sections.push(format!("Unstaged changes:\n{}", unstaged.trim_end()));
-    }
-
-    Ok(format!("Diff\n\n{}", sections.join("\n\n")))
-}
-
-fn run_git_diff_command_in(
-    cwd: &Path,
-    args: &[&str],
-) -> Result<String, Box<dyn std::error::Error>> {
-    let output = std::process::Command::new("git")
-        .args(args)
-        .current_dir(cwd)
-        .output()?;
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
-        return Err(format!("git {} failed: {stderr}", args.join(" ")).into());
-    }
-    Ok(String::from_utf8(output.stdout)?)
-}
-
-fn render_teleport_report(target: &str) -> Result<String, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-
-    let file_list = Command::new("rg")
-        .args(["--files"])
-        .current_dir(&cwd)
-        .output()?;
-    let file_matches = if file_list.status.success() {
-        String::from_utf8(file_list.stdout)?
-            .lines()
-            .filter(|line| line.contains(target))
-            .take(10)
-            .map(ToOwned::to_owned)
-            .collect::<Vec<_>>()
-    } else {
-        Vec::new()
-    };
-
-    let content_output = Command::new("rg")
-        .args(["-n", "-S", "--color", "never", target, "."])
-        .current_dir(&cwd)
-        .output()?;
-
-    let mut lines = vec![
-        "Teleport".to_string(),
-        format!("  Target           {target}"),
-        "  Action           search workspace files and content for the target".to_string(),
-    ];
-    if !file_matches.is_empty() {
-        lines.push(String::new());
-        lines.push("File matches".to_string());
-        lines.extend(file_matches.into_iter().map(|path| format!("  {path}")));
-    }
-
-    if content_output.status.success() {
-        let matches = String::from_utf8(content_output.stdout)?;
-        if !matches.trim().is_empty() {
-            lines.push(String::new());
-            lines.push("Content matches".to_string());
-            lines.push(truncate_for_prompt(&matches, 4_000));
-        }
-    }
-
-    if lines.len() == 1 {
-        lines.push("  Result           no matches found".to_string());
-    }
-
-    Ok(lines.join("\n"))
-}
-
-fn render_last_tool_debug_report(session: &Session) -> Result<String, Box<dyn std::error::Error>> {
-    let last_tool_use = session
-        .messages
-        .iter()
-        .rev()
-        .find_map(|message| {
-            message.blocks.iter().rev().find_map(|block| match block {
-                ContentBlock::ToolUse { id, name, input } => {
-                    Some((id.clone(), name.clone(), input.clone()))
-                }
-                _ => None,
-            })
-        })
-        .ok_or_else(|| "no prior tool call found in session".to_string())?;
-
-    let tool_result = session.messages.iter().rev().find_map(|message| {
-        message.blocks.iter().rev().find_map(|block| match block {
-            ContentBlock::ToolResult {
-                tool_use_id,
-                tool_name,
-                output,
-                is_error,
-            } if tool_use_id == &last_tool_use.0 => {
-                Some((tool_name.clone(), output.clone(), *is_error))
-            }
-            _ => None,
-        })
-    });
-
-    let mut lines = vec![
-        "Debug tool call".to_string(),
-        "  Action           inspect the last recorded tool call and its result".to_string(),
-        format!("  Tool id          {}", last_tool_use.0),
-        format!("  Tool name        {}", last_tool_use.1),
-        "  Input".to_string(),
-        indent_block(&last_tool_use.2, 4),
-    ];
-
-    match tool_result {
-        Some((tool_name, output, is_error)) => {
-            lines.push("  Result".to_string());
-            lines.push(format!("    name           {tool_name}"));
-            lines.push(format!(
-                "    status         {}",
-                if is_error { "error" } else { "ok" }
-            ));
-            lines.push(indent_block(&output, 4));
-        }
-        None => lines.push("  Result           missing tool result".to_string()),
-    }
-
-    Ok(lines.join("\n"))
-}
-
-fn indent_block(value: &str, spaces: usize) -> String {
-    let indent = " ".repeat(spaces);
-    value
-        .lines()
-        .map(|line| format!("{indent}{line}"))
-        .collect::<Vec<_>>()
-        .join("\n")
-}
-
-fn validate_no_args(
-    command_name: &str,
-    args: Option<&str>,
-) -> Result<(), Box<dyn std::error::Error>> {
-    if let Some(args) = args.map(str::trim).filter(|value| !value.is_empty()) {
-        return Err(format!(
-            "{command_name} does not accept arguments. Received: {args}\nUsage: {command_name}"
-        )
-        .into());
-    }
-    Ok(())
-}
-
-fn format_bughunter_report(scope: Option<&str>) -> String {
-    format!(
-        "Bughunter
-  Scope            {}
-  Action           inspect the selected code for likely bugs and correctness issues
-  Output           findings should include file paths, severity, and suggested fixes",
-        scope.unwrap_or("the current repository")
-    )
-}
-
-fn format_ultraplan_report(task: Option<&str>) -> String {
-    format!(
-        "Ultraplan
-  Task             {}
-  Action           break work into a multi-step execution plan
-  Output           plan should cover goals, risks, sequencing, verification, and rollback",
-        task.unwrap_or("the current repo work")
-    )
-}
-
-fn format_pr_report(branch: &str, context: Option<&str>) -> String {
-    format!(
-        "PR
-  Branch           {branch}
-  Context          {}
-  Action           draft or create a pull request for the current branch
-  Output           title and markdown body suitable for GitHub",
-        context.unwrap_or("none")
-    )
-}
-
-fn format_issue_report(context: Option<&str>) -> String {
-    format!(
-        "Issue
-  Context          {}
-  Action           draft or create a GitHub issue from the current context
-  Output           title and markdown body suitable for GitHub",
-        context.unwrap_or("none")
-    )
-}
-
-fn git_output(args: &[&str]) -> Result<String, Box<dyn std::error::Error>> {
-    let output = Command::new("git")
-        .args(args)
-        .current_dir(env::current_dir()?)
-        .output()?;
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
-        return Err(format!("git {} failed: {stderr}", args.join(" ")).into());
-    }
-    Ok(String::from_utf8(output.stdout)?)
-}
-
-fn git_status_ok(args: &[&str]) -> Result<(), Box<dyn std::error::Error>> {
-    let output = Command::new("git")
-        .args(args)
-        .current_dir(env::current_dir()?)
-        .output()?;
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr).trim().to_string();
-        return Err(format!("git {} failed: {stderr}", args.join(" ")).into());
-    }
-    Ok(())
-}
-
-fn command_exists(name: &str) -> bool {
-    Command::new("which")
-        .arg(name)
-        .output()
-        .map(|output| output.status.success())
-        .unwrap_or(false)
-}
-
-fn write_temp_text_file(
-    filename: &str,
-    contents: &str,
-) -> Result<PathBuf, Box<dyn std::error::Error>> {
-    let path = env::temp_dir().join(filename);
-    fs::write(&path, contents)?;
-    Ok(path)
-}
-
-const DEFAULT_HISTORY_LIMIT: usize = 20;
-
-fn parse_history_count(raw: Option<&str>) -> Result<usize, String> {
-    let Some(raw) = raw else {
-        return Ok(DEFAULT_HISTORY_LIMIT);
-    };
-    let parsed: usize = raw
-        .parse()
-        .map_err(|_| format!("history: invalid count '{raw}'. Expected a positive integer."))?;
-    if parsed == 0 {
-        return Err("history: count must be greater than 0.".to_string());
-    }
-    Ok(parsed)
-}
-
-fn format_history_timestamp(timestamp_ms: u64) -> String {
-    let secs = timestamp_ms / 1_000;
-    let subsec_ms = timestamp_ms % 1_000;
-    let days_since_epoch = secs / 86_400;
-    let seconds_of_day = secs % 86_400;
-    let hours = seconds_of_day / 3_600;
-    let minutes = (seconds_of_day % 3_600) / 60;
-    let seconds = seconds_of_day % 60;
-
-    let (year, month, day) = civil_from_days(i64::try_from(days_since_epoch).unwrap_or(0));
-    format!("{year:04}-{month:02}-{day:02}T{hours:02}:{minutes:02}:{seconds:02}.{subsec_ms:03}Z")
-}
-
-// Computes civil (Gregorian) year/month/day from days since the Unix epoch
-// (1970-01-01) using Howard Hinnant's `civil_from_days` algorithm.
-fn civil_from_days(days: i64) -> (i32, u32, u32) {
-    let z = days + 719_468;
-    let era = if z >= 0 {
-        z / 146_097
-    } else {
-        (z - 146_096) / 146_097
-    };
-    let doe = (z - era * 146_097) as u64; // [0, 146_096]
-    let yoe = (doe - doe / 1_460 + doe / 36_524 - doe / 146_096) / 365; // [0, 399]
-    let y = yoe as i64 + era * 400;
-    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
-    let mp = (5 * doy + 2) / 153; // [0, 11]
-    let d = doy - (153 * mp + 2) / 5 + 1; // [1, 31]
-    let m = if mp < 10 { mp + 3 } else { mp - 9 }; // [1, 12]
-    let y = y + i64::from(m <= 2);
-    (y as i32, m as u32, d as u32)
-}
-
-fn render_prompt_history_report(entries: &[PromptHistoryEntry], limit: usize) -> String {
-    if entries.is_empty() {
-        return "Prompt history\n  Result           no prompts recorded yet".to_string();
-    }
-
-    let total = entries.len();
-    let start = total.saturating_sub(limit);
-    let shown = &entries[start..];
-    let mut lines = vec![
-        "Prompt history".to_string(),
-        format!("  Total            {total}"),
-        format!("  Showing          {} most recent", shown.len()),
-        format!("  Reverse search   Ctrl-R in the REPL"),
-        String::new(),
-    ];
-    for (offset, entry) in shown.iter().enumerate() {
-        let absolute_index = start + offset + 1;
-        let timestamp = format_history_timestamp(entry.timestamp_ms);
-        let first_line = entry.text.lines().next().unwrap_or("").trim();
-        let display = if first_line.chars().count() > 80 {
-            let truncated: String = first_line.chars().take(77).collect();
-            format!("{truncated}...")
-        } else {
-            first_line.to_string()
-        };
-        lines.push(format!("  {absolute_index:>3}. [{timestamp}] {display}"));
-    }
-    lines.join("\n")
-}
-
-fn collect_session_prompt_history(session: &Session) -> Vec<PromptHistoryEntry> {
-    if !session.prompt_history.is_empty() {
-        return session
-            .prompt_history
-            .iter()
-            .map(|entry| PromptHistoryEntry {
-                timestamp_ms: entry.timestamp_ms,
-                text: entry.text.clone(),
-            })
-            .collect();
-    }
-    let timestamp_ms = session.updated_at_ms;
-    session
-        .messages
-        .iter()
-        .filter(|message| message.role == MessageRole::User)
-        .filter_map(|message| {
-            message.blocks.iter().find_map(|block| match block {
-                ContentBlock::Text { text } => Some(PromptHistoryEntry {
-                    timestamp_ms,
-                    text: text.clone(),
-                }),
-                _ => None,
-            })
-        })
-        .collect()
-}
-
-fn recent_user_context(session: &Session, limit: usize) -> String {
-    let requests = session
-        .messages
-        .iter()
-        .filter(|message| message.role == MessageRole::User)
-        .filter_map(|message| {
-            message.blocks.iter().find_map(|block| match block {
-                ContentBlock::Text { text } => Some(text.trim().to_string()),
-                _ => None,
-            })
-        })
-        .rev()
-        .take(limit)
-        .collect::<Vec<_>>();
-
-    if requests.is_empty() {
-        "<no prior user messages>".to_string()
-    } else {
-        requests
-            .into_iter()
-            .rev()
-            .enumerate()
-            .map(|(index, text)| format!("{}. {}", index + 1, text))
-            .collect::<Vec<_>>()
-            .join("\n")
-    }
-}
-
-fn truncate_for_prompt(value: &str, limit: usize) -> String {
-    if value.chars().count() <= limit {
-        value.trim().to_string()
-    } else {
-        let truncated = value.chars().take(limit).collect::<String>();
-        format!("{}\n…[truncated]", truncated.trim_end())
-    }
-}
-
-fn sanitize_generated_message(value: &str) -> String {
-    value.trim().trim_matches('`').trim().replace("\r\n", "\n")
-}
-
-fn parse_titled_body(value: &str) -> Option<(String, String)> {
-    let normalized = sanitize_generated_message(value);
-    let title = normalized
-        .lines()
-        .find_map(|line| line.strip_prefix("TITLE:").map(str::trim))?;
-    let body_start = normalized.find("BODY:")?;
-    let body = normalized[body_start + "BODY:".len()..].trim();
-    Some((title.to_string(), body.to_string()))
-}
-
-fn render_version_report() -> String {
-    let git_sha = GIT_SHA.unwrap_or("unknown");
-    let target = BUILD_TARGET.unwrap_or("unknown");
-    format!(
-        "Claw Code\n  Version          {VERSION}\n  Git SHA          {git_sha}\n  Target           {target}\n  Build date       {DEFAULT_DATE}"
-    )
-}
-
-fn render_export_text(session: &Session) -> String {
-    let mut lines = vec!["# Conversation Export".to_string(), String::new()];
-    for (index, message) in session.messages.iter().enumerate() {
-        let role = match message.role {
-            MessageRole::System => "system",
-            MessageRole::User => "user",
-            MessageRole::Assistant => "assistant",
-            MessageRole::Tool => "tool",
-        };
-        lines.push(format!("## {}. {role}", index + 1));
-        for block in &message.blocks {
-            match block {
-                ContentBlock::Text { text } => lines.push(text.clone()),
-                ContentBlock::ToolUse { id, name, input } => {
-                    lines.push(format!("[tool_use id={id} name={name}] {input}"));
-                }
-                ContentBlock::ToolResult {
-                    tool_use_id,
-                    tool_name,
-                    output,
-                    is_error,
-                } => {
-                    lines.push(format!(
-                        "[tool_result id={tool_use_id} name={tool_name} error={is_error}] {output}"
-                    ));
-                }
-            }
-        }
-        lines.push(String::new());
-    }
-    lines.join("\n")
-}
-
-fn default_export_filename(session: &Session) -> String {
-    let stem = session
-        .messages
-        .iter()
-        .find_map(|message| match message.role {
-            MessageRole::User => message.blocks.iter().find_map(|block| match block {
-                ContentBlock::Text { text } => Some(text.as_str()),
-                _ => None,
-            }),
-            _ => None,
-        })
-        .map_or("conversation", |text| {
-            text.lines().next().unwrap_or("conversation")
-        })
-        .chars()
-        .map(|ch| {
-            if ch.is_ascii_alphanumeric() {
-                ch.to_ascii_lowercase()
-            } else {
-                '-'
-            }
-        })
-        .collect::<String>()
-        .split('-')
-        .filter(|part| !part.is_empty())
-        .take(8)
-        .collect::<Vec<_>>()
-        .join("-");
-    let fallback = if stem.is_empty() {
-        "conversation"
-    } else {
-        &stem
-    };
-    format!("{fallback}.txt")
-}
-
-fn resolve_export_path(
-    requested_path: Option<&str>,
-    session: &Session,
-) -> Result<PathBuf, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let file_name =
-        requested_path.map_or_else(|| default_export_filename(session), ToOwned::to_owned);
-    let final_name = if Path::new(&file_name)
-        .extension()
-        .is_some_and(|ext| ext.eq_ignore_ascii_case("txt"))
-    {
-        file_name
-    } else {
-        format!("{file_name}.txt")
-    };
-    Ok(cwd.join(final_name))
-}
-
-const SESSION_MARKDOWN_TOOL_SUMMARY_LIMIT: usize = 280;
-
-fn summarize_tool_payload_for_markdown(payload: &str) -> String {
-    let compact = match serde_json::from_str::<serde_json::Value>(payload) {
-        Ok(value) => value.to_string(),
-        Err(_) => payload.split_whitespace().collect::<Vec<_>>().join(" "),
-    };
-    if compact.is_empty() {
-        return String::new();
-    }
-    truncate_for_summary(&compact, SESSION_MARKDOWN_TOOL_SUMMARY_LIMIT)
-}
-
-fn run_export(
-    session_reference: &str,
-    output_path: Option<&Path>,
-    output_format: CliOutputFormat,
-) -> Result<(), Box<dyn std::error::Error>> {
-    let handle = resolve_session_reference(session_reference)?;
-    let session = Session::load_from_path(&handle.path)?;
-    let markdown = render_session_markdown(&session, &handle.id, &handle.path);
-
-    if let Some(path) = output_path {
-        fs::write(path, &markdown)?;
-        let report = format!(
-            "Export\n  Result           wrote markdown transcript\n  File             {}\n  Session          {}\n  Messages         {}",
-            path.display(),
-            handle.id,
-            session.messages.len(),
-        );
-        match output_format {
-            CliOutputFormat::Text => println!("{report}"),
-            CliOutputFormat::Json => println!(
-                "{}",
-                serde_json::to_string_pretty(&json!({
-                    "kind": "export",
-                    "message": report,
-                    "session_id": handle.id,
-                    "file": path.display().to_string(),
-                    "messages": session.messages.len(),
-                }))?
-            ),
-        }
-        return Ok(());
-    }
-
-    match output_format {
-        CliOutputFormat::Text => {
-            print!("{markdown}");
-            if !markdown.ends_with('\n') {
-                println!();
-            }
-        }
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&json!({
-                "kind": "export",
-                "session_id": handle.id,
-                "file": handle.path.display().to_string(),
-                "messages": session.messages.len(),
-                "markdown": markdown,
-            }))?
-        ),
-    }
-    Ok(())
-}
-
-fn render_session_markdown(session: &Session, session_id: &str, session_path: &Path) -> String {
-    let mut lines = vec![
-        "# Conversation Export".to_string(),
-        String::new(),
-        format!("- **Session**: `{session_id}`"),
-        format!("- **File**: `{}`", session_path.display()),
-        format!("- **Messages**: {}", session.messages.len()),
-    ];
-    if let Some(workspace_root) = session.workspace_root() {
-        lines.push(format!("- **Workspace**: `{}`", workspace_root.display()));
-    }
-    if let Some(fork) = &session.fork {
-        let branch = fork.branch_name.as_deref().unwrap_or("(unnamed)");
-        lines.push(format!(
-            "- **Forked from**: `{}` (branch `{branch}`)",
-            fork.parent_session_id
-        ));
-    }
-    if let Some(compaction) = &session.compaction {
-        lines.push(format!(
-            "- **Compactions**: {} (last removed {} messages)",
-            compaction.count, compaction.removed_message_count
-        ));
-    }
-    lines.push(String::new());
-    lines.push("---".to_string());
-    lines.push(String::new());
-
-    for (index, message) in session.messages.iter().enumerate() {
-        let role = match message.role {
-            MessageRole::System => "System",
-            MessageRole::User => "User",
-            MessageRole::Assistant => "Assistant",
-            MessageRole::Tool => "Tool",
-        };
-        lines.push(format!("## {}. {role}", index + 1));
-        lines.push(String::new());
-        for block in &message.blocks {
-            match block {
-                ContentBlock::Text { text } => {
-                    let trimmed = text.trim_end();
-                    if !trimmed.is_empty() {
-                        lines.push(trimmed.to_string());
-                        lines.push(String::new());
-                    }
-                }
-                ContentBlock::ToolUse { id, name, input } => {
-                    lines.push(format!(
-                        "**Tool call** `{name}` _(id `{}`)_",
-                        short_tool_id(id)
-                    ));
-                    let summary = summarize_tool_payload_for_markdown(input);
-                    if !summary.is_empty() {
-                        lines.push(format!("> {summary}"));
-                    }
-                    lines.push(String::new());
-                }
-                ContentBlock::ToolResult {
-                    tool_use_id,
-                    tool_name,
-                    output,
-                    is_error,
-                } => {
-                    let status = if *is_error { "error" } else { "ok" };
-                    lines.push(format!(
-                        "**Tool result** `{tool_name}` _(id `{}`, {status})_",
-                        short_tool_id(tool_use_id)
-                    ));
-                    let summary = summarize_tool_payload_for_markdown(output);
-                    if !summary.is_empty() {
-                        lines.push(format!("> {summary}"));
-                    }
-                    lines.push(String::new());
-                }
-            }
-        }
-        if let Some(usage) = message.usage {
-            lines.push(format!(
-                "_tokens: in={} out={} cache_create={} cache_read={}_",
-                usage.input_tokens,
-                usage.output_tokens,
-                usage.cache_creation_input_tokens,
-                usage.cache_read_input_tokens,
-            ));
-            lines.push(String::new());
-        }
-    }
-    lines.join("\n")
-}
-
-fn short_tool_id(id: &str) -> String {
-    let char_count = id.chars().count();
-    if char_count <= 12 {
-        return id.to_string();
-    }
-    let prefix: String = id.chars().take(12).collect();
-    format!("{prefix}…")
-}
-
-fn build_system_prompt() -> Result<Vec<String>, Box<dyn std::error::Error>> {
-    Ok(load_system_prompt(
-        env::current_dir()?,
-        DEFAULT_DATE,
-        env::consts::OS,
-        "unknown",
-    )?)
-}
-
-fn build_runtime_plugin_state() -> Result<RuntimePluginState, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    let loader = ConfigLoader::default_for(&cwd);
-    let runtime_config = loader.load()?;
-    build_runtime_plugin_state_with_loader(&cwd, &loader, &runtime_config)
-}
-
-fn build_runtime_plugin_state_with_loader(
-    cwd: &Path,
-    loader: &ConfigLoader,
-    runtime_config: &runtime::RuntimeConfig,
-) -> Result<RuntimePluginState, Box<dyn std::error::Error>> {
-    let plugin_manager = build_plugin_manager(cwd, loader, runtime_config);
-    let plugin_registry = plugin_manager.plugin_registry()?;
-    let plugin_hook_config =
-        runtime_hook_config_from_plugin_hooks(plugin_registry.aggregated_hooks()?);
-    let feature_config = runtime_config
-        .feature_config()
-        .clone()
-        .with_hooks(runtime_config.hooks().merged(&plugin_hook_config));
-    let (mcp_state, runtime_tools) = build_runtime_mcp_state(runtime_config)?;
-    let tool_registry = GlobalToolRegistry::with_plugin_tools(plugin_registry.aggregated_tools()?)?
-        .with_runtime_tools(runtime_tools)?;
-    Ok(RuntimePluginState {
-        feature_config,
-        tool_registry,
-        plugin_registry,
-        mcp_state,
-    })
-}
-
-fn build_plugin_manager(
-    cwd: &Path,
-    loader: &ConfigLoader,
-    runtime_config: &runtime::RuntimeConfig,
-) -> PluginManager {
-    let plugin_settings = runtime_config.plugins();
-    let mut plugin_config = PluginManagerConfig::new(loader.config_home().to_path_buf());
-    plugin_config.enabled_plugins = plugin_settings.enabled_plugins().clone();
-    plugin_config.external_dirs = plugin_settings
-        .external_directories()
-        .iter()
-        .map(|path| resolve_plugin_path(cwd, loader.config_home(), path))
-        .collect();
-    plugin_config.install_root = plugin_settings
-        .install_root()
-        .map(|path| resolve_plugin_path(cwd, loader.config_home(), path));
-    plugin_config.registry_path = plugin_settings
-        .registry_path()
-        .map(|path| resolve_plugin_path(cwd, loader.config_home(), path));
-    plugin_config.bundled_root = plugin_settings
-        .bundled_root()
-        .map(|path| resolve_plugin_path(cwd, loader.config_home(), path));
-    PluginManager::new(plugin_config)
-}
-
-fn resolve_plugin_path(cwd: &Path, config_home: &Path, value: &str) -> PathBuf {
-    let path = PathBuf::from(value);
-    if path.is_absolute() {
-        path
-    } else if value.starts_with('.') {
-        cwd.join(path)
-    } else {
-        config_home.join(path)
-    }
-}
-
-fn runtime_hook_config_from_plugin_hooks(hooks: PluginHooks) -> runtime::RuntimeHookConfig {
-    runtime::RuntimeHookConfig::new(
-        hooks.pre_tool_use,
-        hooks.post_tool_use,
-        hooks.post_tool_use_failure,
-    )
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-struct InternalPromptProgressState {
-    command_label: &'static str,
-    task_label: String,
-    step: usize,
-    phase: String,
-    detail: Option<String>,
-    saw_final_text: bool,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum InternalPromptProgressEvent {
-    Started,
-    Update,
-    Heartbeat,
-    Complete,
-    Failed,
-}
-
-#[derive(Debug)]
-struct InternalPromptProgressShared {
-    state: Mutex<InternalPromptProgressState>,
-    output_lock: Mutex<()>,
-    started_at: Instant,
-}
-
-#[derive(Debug, Clone)]
-struct InternalPromptProgressReporter {
-    shared: Arc<InternalPromptProgressShared>,
-}
-
-#[derive(Debug)]
-struct InternalPromptProgressRun {
-    reporter: InternalPromptProgressReporter,
-    heartbeat_stop: Option<mpsc::Sender<()>>,
-    heartbeat_handle: Option<thread::JoinHandle<()>>,
-}
-
-impl InternalPromptProgressReporter {
-    fn ultraplan(task: &str) -> Self {
-        Self {
-            shared: Arc::new(InternalPromptProgressShared {
-                state: Mutex::new(InternalPromptProgressState {
-                    command_label: "Ultraplan",
-                    task_label: task.to_string(),
-                    step: 0,
-                    phase: "planning started".to_string(),
-                    detail: Some(format!("task: {task}")),
-                    saw_final_text: false,
-                }),
-                output_lock: Mutex::new(()),
-                started_at: Instant::now(),
-            }),
-        }
-    }
-
-    fn emit(&self, event: InternalPromptProgressEvent, error: Option<&str>) {
-        let snapshot = self.snapshot();
-        let line = format_internal_prompt_progress_line(event, &snapshot, self.elapsed(), error);
-        self.write_line(&line);
-    }
-
-    fn mark_model_phase(&self) {
-        let snapshot = {
-            let mut state = self
-                .shared
-                .state
-                .lock()
-                .expect("internal prompt progress state poisoned");
-            state.step += 1;
-            state.phase = if state.step == 1 {
-                "analyzing request".to_string()
-            } else {
-                "reviewing findings".to_string()
-            };
-            state.detail = Some(format!("task: {}", state.task_label));
-            state.clone()
-        };
-        self.write_line(&format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Update,
-            &snapshot,
-            self.elapsed(),
-            None,
-        ));
-    }
-
-    fn mark_tool_phase(&self, name: &str, input: &str) {
-        let detail = describe_tool_progress(name, input);
-        let snapshot = {
-            let mut state = self
-                .shared
-                .state
-                .lock()
-                .expect("internal prompt progress state poisoned");
-            state.step += 1;
-            state.phase = format!("running {name}");
-            state.detail = Some(detail);
-            state.clone()
-        };
-        self.write_line(&format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Update,
-            &snapshot,
-            self.elapsed(),
-            None,
-        ));
-    }
-
-    fn mark_text_phase(&self, text: &str) {
-        let trimmed = text.trim();
-        if trimmed.is_empty() {
-            return;
-        }
-        let detail = truncate_for_summary(first_visible_line(trimmed), 120);
-        let snapshot = {
-            let mut state = self
-                .shared
-                .state
-                .lock()
-                .expect("internal prompt progress state poisoned");
-            if state.saw_final_text {
-                return;
-            }
-            state.saw_final_text = true;
-            state.step += 1;
-            state.phase = "drafting final plan".to_string();
-            state.detail = (!detail.is_empty()).then_some(detail);
-            state.clone()
-        };
-        self.write_line(&format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Update,
-            &snapshot,
-            self.elapsed(),
-            None,
-        ));
-    }
-
-    fn emit_heartbeat(&self) {
-        let snapshot = self.snapshot();
-        self.write_line(&format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Heartbeat,
-            &snapshot,
-            self.elapsed(),
-            None,
-        ));
-    }
-
-    fn snapshot(&self) -> InternalPromptProgressState {
-        self.shared
-            .state
-            .lock()
-            .expect("internal prompt progress state poisoned")
-            .clone()
-    }
-
-    fn elapsed(&self) -> Duration {
-        self.shared.started_at.elapsed()
-    }
-
-    fn write_line(&self, line: &str) {
-        let _guard = self
-            .shared
-            .output_lock
-            .lock()
-            .expect("internal prompt progress output lock poisoned");
-        let mut stdout = io::stdout();
-        let _ = writeln!(stdout, "{line}");
-        let _ = stdout.flush();
-    }
-}
-
-impl InternalPromptProgressRun {
-    fn start_ultraplan(task: &str) -> Self {
-        let reporter = InternalPromptProgressReporter::ultraplan(task);
-        reporter.emit(InternalPromptProgressEvent::Started, None);
-
-        let (heartbeat_stop, heartbeat_rx) = mpsc::channel();
-        let heartbeat_reporter = reporter.clone();
-        let heartbeat_handle = thread::spawn(move || loop {
-            match heartbeat_rx.recv_timeout(INTERNAL_PROGRESS_HEARTBEAT_INTERVAL) {
-                Ok(()) | Err(RecvTimeoutError::Disconnected) => break,
-                Err(RecvTimeoutError::Timeout) => heartbeat_reporter.emit_heartbeat(),
-            }
-        });
-
-        Self {
-            reporter,
-            heartbeat_stop: Some(heartbeat_stop),
-            heartbeat_handle: Some(heartbeat_handle),
-        }
-    }
-
-    fn reporter(&self) -> InternalPromptProgressReporter {
-        self.reporter.clone()
-    }
-
-    fn finish_success(&mut self) {
-        self.stop_heartbeat();
-        self.reporter
-            .emit(InternalPromptProgressEvent::Complete, None);
-    }
-
-    fn finish_failure(&mut self, error: &str) {
-        self.stop_heartbeat();
-        self.reporter
-            .emit(InternalPromptProgressEvent::Failed, Some(error));
-    }
-
-    fn stop_heartbeat(&mut self) {
-        if let Some(sender) = self.heartbeat_stop.take() {
-            let _ = sender.send(());
-        }
-        if let Some(handle) = self.heartbeat_handle.take() {
-            let _ = handle.join();
-        }
-    }
-}
-
-impl Drop for InternalPromptProgressRun {
-    fn drop(&mut self) {
-        self.stop_heartbeat();
-    }
-}
-
-fn format_internal_prompt_progress_line(
-    event: InternalPromptProgressEvent,
-    snapshot: &InternalPromptProgressState,
-    elapsed: Duration,
-    error: Option<&str>,
-) -> String {
-    let elapsed_seconds = elapsed.as_secs();
-    let step_label = if snapshot.step == 0 {
-        "current step pending".to_string()
-    } else {
-        format!("current step {}", snapshot.step)
-    };
-    let mut status_bits = vec![step_label, format!("phase {}", snapshot.phase)];
-    if let Some(detail) = snapshot
-        .detail
-        .as_deref()
-        .filter(|detail| !detail.is_empty())
-    {
-        status_bits.push(detail.to_string());
-    }
-    let status = status_bits.join(" · ");
-    match event {
-        InternalPromptProgressEvent::Started => {
-            format!(
-                "🧭 {} status · planning started · {status}",
-                snapshot.command_label
-            )
-        }
-        InternalPromptProgressEvent::Update => {
-            format!("… {} status · {status}", snapshot.command_label)
-        }
-        InternalPromptProgressEvent::Heartbeat => format!(
-            "… {} heartbeat · {elapsed_seconds}s elapsed · {status}",
-            snapshot.command_label
-        ),
-        InternalPromptProgressEvent::Complete => format!(
-            "✔ {} status · completed · {elapsed_seconds}s elapsed · {} steps total",
-            snapshot.command_label, snapshot.step
-        ),
-        InternalPromptProgressEvent::Failed => format!(
-            "✘ {} status · failed · {elapsed_seconds}s elapsed · {}",
-            snapshot.command_label,
-            error.unwrap_or("unknown error")
-        ),
-    }
-}
-
-fn describe_tool_progress(name: &str, input: &str) -> String {
-    let parsed: serde_json::Value =
-        serde_json::from_str(input).unwrap_or(serde_json::Value::String(input.to_string()));
-    match name {
-        "bash" | "Bash" => {
-            let command = parsed
-                .get("command")
-                .and_then(|value| value.as_str())
-                .unwrap_or_default();
-            if command.is_empty() {
-                "running shell command".to_string()
-            } else {
-                format!("command {}", truncate_for_summary(command.trim(), 100))
-            }
-        }
-        "read_file" | "Read" => format!("reading {}", extract_tool_path(&parsed)),
-        "write_file" | "Write" => format!("writing {}", extract_tool_path(&parsed)),
-        "edit_file" | "Edit" => format!("editing {}", extract_tool_path(&parsed)),
-        "glob_search" | "Glob" => {
-            let pattern = parsed
-                .get("pattern")
-                .and_then(|value| value.as_str())
-                .unwrap_or("?");
-            let scope = parsed
-                .get("path")
-                .and_then(|value| value.as_str())
-                .unwrap_or(".");
-            format!("glob `{pattern}` in {scope}")
-        }
-        "grep_search" | "Grep" => {
-            let pattern = parsed
-                .get("pattern")
-                .and_then(|value| value.as_str())
-                .unwrap_or("?");
-            let scope = parsed
-                .get("path")
-                .and_then(|value| value.as_str())
-                .unwrap_or(".");
-            format!("grep `{pattern}` in {scope}")
-        }
-        "web_search" | "WebSearch" => parsed
-            .get("query")
-            .and_then(|value| value.as_str())
-            .map_or_else(
-                || "running web search".to_string(),
-                |query| format!("query {}", truncate_for_summary(query, 100)),
-            ),
-        _ => {
-            let summary = summarize_tool_payload(input);
-            if summary.is_empty() {
-                format!("running {name}")
-            } else {
-                format!("{name}: {summary}")
-            }
-        }
-    }
-}
-
-#[allow(clippy::needless_pass_by_value)]
-#[allow(clippy::too_many_arguments)]
-fn build_runtime(
-    session: Session,
-    session_id: &str,
-    model: String,
-    system_prompt: Vec<String>,
-    enable_tools: bool,
-    emit_output: bool,
-    allowed_tools: Option<AllowedToolSet>,
-    permission_mode: PermissionMode,
-    progress_reporter: Option<InternalPromptProgressReporter>,
-) -> Result<BuiltRuntime, Box<dyn std::error::Error>> {
-    let runtime_plugin_state = build_runtime_plugin_state()?;
-    build_runtime_with_plugin_state(
-        session,
-        session_id,
-        model,
-        system_prompt,
-        enable_tools,
-        emit_output,
-        allowed_tools,
-        permission_mode,
-        progress_reporter,
-        runtime_plugin_state,
-    )
-}
-
-#[allow(clippy::needless_pass_by_value)]
-#[allow(clippy::too_many_arguments)]
-fn build_runtime_with_plugin_state(
-    session: Session,
-    session_id: &str,
-    model: String,
-    system_prompt: Vec<String>,
-    enable_tools: bool,
-    emit_output: bool,
-    allowed_tools: Option<AllowedToolSet>,
-    permission_mode: PermissionMode,
-    progress_reporter: Option<InternalPromptProgressReporter>,
-    runtime_plugin_state: RuntimePluginState,
-) -> Result<BuiltRuntime, Box<dyn std::error::Error>> {
-    let RuntimePluginState {
-        feature_config,
-        tool_registry,
-        plugin_registry,
-        mcp_state,
-    } = runtime_plugin_state;
-    plugin_registry.initialize()?;
-    let policy = permission_policy(permission_mode, &feature_config, &tool_registry)
-        .map_err(std::io::Error::other)?;
-    let mut runtime = ConversationRuntime::new_with_features(
-        session,
-        AnthropicRuntimeClient::new(
-            session_id,
-            model,
-            enable_tools,
-            emit_output,
-            allowed_tools.clone(),
-            tool_registry.clone(),
-            progress_reporter,
-        )?,
-        CliToolExecutor::new(
-            allowed_tools.clone(),
-            emit_output,
-            tool_registry.clone(),
-            mcp_state.clone(),
-        ),
-        policy,
-        system_prompt,
-        &feature_config,
-    );
-    if emit_output {
-        runtime = runtime.with_hook_progress_reporter(Box::new(CliHookProgressReporter));
-    }
-    Ok(BuiltRuntime::new(runtime, plugin_registry, mcp_state))
-}
-
-struct CliHookProgressReporter;
-
-impl runtime::HookProgressReporter for CliHookProgressReporter {
-    fn on_event(&mut self, event: &runtime::HookProgressEvent) {
-        match event {
-            runtime::HookProgressEvent::Started {
-                event,
-                tool_name,
-                command,
-            } => eprintln!(
-                "[hook {event_name}] {tool_name}: {command}",
-                event_name = event.as_str()
-            ),
-            runtime::HookProgressEvent::Completed {
-                event,
-                tool_name,
-                command,
-            } => eprintln!(
-                "[hook done {event_name}] {tool_name}: {command}",
-                event_name = event.as_str()
-            ),
-            runtime::HookProgressEvent::Cancelled {
-                event,
-                tool_name,
-                command,
-            } => eprintln!(
-                "[hook cancelled {event_name}] {tool_name}: {command}",
-                event_name = event.as_str()
-            ),
-        }
-    }
-}
-
-struct CliPermissionPrompter {
-    current_mode: PermissionMode,
-}
-
-impl CliPermissionPrompter {
-    fn new(current_mode: PermissionMode) -> Self {
-        Self { current_mode }
-    }
-}
-
-impl runtime::PermissionPrompter for CliPermissionPrompter {
-    fn decide(
-        &mut self,
-        request: &runtime::PermissionRequest,
-    ) -> runtime::PermissionPromptDecision {
-        println!();
-        println!("Permission approval required");
-        println!("  Tool             {}", request.tool_name);
-        println!("  Current mode     {}", self.current_mode.as_str());
-        println!("  Required mode    {}", request.required_mode.as_str());
-        if let Some(reason) = &request.reason {
-            println!("  Reason           {reason}");
-        }
-        println!("  Input            {}", request.input);
-        print!("Approve this tool call? [y/N]: ");
-        let _ = io::stdout().flush();
-
-        let mut response = String::new();
-        match io::stdin().read_line(&mut response) {
-            Ok(_) => {
-                let normalized = response.trim().to_ascii_lowercase();
-                if matches!(normalized.as_str(), "y" | "yes") {
-                    runtime::PermissionPromptDecision::Allow
-                } else {
-                    runtime::PermissionPromptDecision::Deny {
-                        reason: format!(
-                            "tool '{}' denied by user approval prompt",
-                            request.tool_name
-                        ),
-                    }
-                }
-            }
-            Err(error) => runtime::PermissionPromptDecision::Deny {
-                reason: format!("permission approval failed: {error}"),
-            },
-        }
-    }
-}
-
-// NOTE: Despite the historical name `AnthropicRuntimeClient`, this struct
-// now holds an `ApiProviderClient` which dispatches to Anthropic, xAI,
-// OpenAI, or DashScope at construction time based on
-// `detect_provider_kind(&model)`. The struct name is kept to avoid
-// churning `BuiltRuntime` and every Deref/DerefMut site that references
-// it. See ROADMAP #29 for the provider-dispatch routing fix.
-struct AnthropicRuntimeClient {
-    runtime: tokio::runtime::Runtime,
-    client: ApiProviderClient,
-    session_id: String,
-    model: String,
-    enable_tools: bool,
-    emit_output: bool,
-    allowed_tools: Option<AllowedToolSet>,
-    tool_registry: GlobalToolRegistry,
-    progress_reporter: Option<InternalPromptProgressReporter>,
-    reasoning_effort: Option<String>,
-}
-
-impl AnthropicRuntimeClient {
-    fn new(
-        session_id: &str,
-        model: String,
-        enable_tools: bool,
-        emit_output: bool,
-        allowed_tools: Option<AllowedToolSet>,
-        tool_registry: GlobalToolRegistry,
-        progress_reporter: Option<InternalPromptProgressReporter>,
-    ) -> Result<Self, Box<dyn std::error::Error>> {
-        // Dispatch to the correct provider at construction time.
-        // `ApiProviderClient` (exposed by the api crate as
-        // `ProviderClient`) is an enum over Anthropic / xAI / OpenAI
-        // variants, where xAI and OpenAI both use the OpenAI-compat
-        // wire format under the hood. We consult
-        // `detect_provider_kind(&resolved_model)` so model-name prefix
-        // routing (`openai/`, `gpt-`, `grok`, `qwen/`) wins over
-        // env-var presence.
-        //
-        // For Anthropic we build the client directly instead of going
-        // through `ApiProviderClient::from_model_with_anthropic_auth`
-        // so we can explicitly apply `api::read_base_url()` — that
-        // reads `ANTHROPIC_BASE_URL` and is required for the local
-        // mock-server test harness
-        // (`crates/rusty-claude-cli/tests/compact_output.rs`) to point
-        // claw at its fake Anthropic endpoint. We also attach a
-        // session-scoped prompt cache on the Anthropic path; the
-        // prompt cache is Anthropic-only so non-Anthropic variants
-        // skip it.
-        let resolved_model = api::resolve_model_alias(&model);
-        let client = match detect_provider_kind(&resolved_model) {
-            ProviderKind::Anthropic => {
-                let auth = resolve_cli_auth_source()?;
-                let inner = AnthropicClient::from_auth(auth)
-                    .with_base_url(api::read_base_url())
-                    .with_prompt_cache(PromptCache::new(session_id));
-                ApiProviderClient::Anthropic(inner)
-            }
-            ProviderKind::Xai | ProviderKind::OpenAi => {
-                // The api crate's `ProviderClient::from_model_with_anthropic_auth`
-                // with `None` for the anthropic auth routes via
-                // `detect_provider_kind` and builds an
-                // `OpenAiCompatClient::from_env` with the matching
-                // `OpenAiCompatConfig` (openai / xai / dashscope).
-                // That reads the correct API-key env var and BASE_URL
-                // override internally, so this one call covers OpenAI,
-                // OpenRouter, xAI, DashScope, Ollama, and any other
-                // OpenAI-compat endpoint users configure via
-                // `OPENAI_BASE_URL` / `XAI_BASE_URL` / `DASHSCOPE_BASE_URL`.
-                ApiProviderClient::from_model_with_anthropic_auth(&resolved_model, None)?
-            }
-        };
-        Ok(Self {
-            runtime: tokio::runtime::Runtime::new()?,
-            client,
-            session_id: session_id.to_string(),
-            model,
-            enable_tools,
-            emit_output,
-            allowed_tools,
-            tool_registry,
-            progress_reporter,
-            reasoning_effort: None,
-        })
-    }
-
-    fn set_reasoning_effort(&mut self, effort: Option<String>) {
-        self.reasoning_effort = effort;
-    }
-}
-
-fn resolve_cli_auth_source() -> Result<AuthSource, Box<dyn std::error::Error>> {
-    let cwd = env::current_dir()?;
-    Ok(resolve_cli_auth_source_for_cwd(&cwd, default_oauth_config)?)
-}
-
-fn resolve_cli_auth_source_for_cwd<F>(
-    cwd: &Path,
-    default_oauth: F,
-) -> Result<AuthSource, api::ApiError>
-where
-    F: FnOnce() -> OAuthConfig,
-{
-    resolve_startup_auth_source(|| {
-        Ok(Some(
-            load_runtime_oauth_config_for(cwd)?.unwrap_or_else(default_oauth),
-        ))
-    })
-}
-
-fn load_runtime_oauth_config_for(cwd: &Path) -> Result<Option<OAuthConfig>, api::ApiError> {
-    let config = ConfigLoader::default_for(cwd).load().map_err(|error| {
-        api::ApiError::Auth(format!("failed to load runtime OAuth config: {error}"))
-    })?;
-    Ok(config.oauth().cloned())
-}
-
-impl ApiClient for AnthropicRuntimeClient {
-    #[allow(clippy::too_many_lines)]
-    fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError> {
-        if let Some(progress_reporter) = &self.progress_reporter {
-            progress_reporter.mark_model_phase();
-        }
-        let is_post_tool = request_ends_with_tool_result(&request);
-        let message_request = MessageRequest {
-            model: self.model.clone(),
-            max_tokens: max_tokens_for_model(&self.model),
-            messages: convert_messages(&request.messages),
-            system: (!request.system_prompt.is_empty()).then(|| request.system_prompt.join("\n\n")),
-            tools: self
-                .enable_tools
-                .then(|| filter_tool_specs(&self.tool_registry, self.allowed_tools.as_ref())),
-            tool_choice: self.enable_tools.then_some(ToolChoice::Auto),
-            stream: true,
-            reasoning_effort: self.reasoning_effort.clone(),
-            ..Default::default()
-        };
-
-        self.runtime.block_on(async {
-            // When resuming after tool execution, apply a stall timeout on the
-            // first stream event.  If the model does not respond within the
-            // deadline we drop the stalled connection and re-send the request as
-            // a continuation nudge (one retry only).
-            let max_attempts: usize = if is_post_tool { 2 } else { 1 };
-
-            for attempt in 1..=max_attempts {
-                let result = self
-                    .consume_stream(&message_request, is_post_tool && attempt == 1)
-                    .await;
-                match result {
-                    Ok(events) => return Ok(events),
-                    Err(error)
-                        if error.to_string().contains("post-tool stall")
-                            && attempt < max_attempts =>
-                    {
-                        // Stalled after tool completion — nudge the model by
-                        // re-sending the same request.
-                        continue;
-                    }
-                    Err(error) => return Err(error),
-                }
-            }
-
-            Err(RuntimeError::new("post-tool continuation nudge exhausted"))
-        })
-    }
-}
-
-impl AnthropicRuntimeClient {
-    /// Consume a single streaming response, optionally applying a stall
-    /// timeout on the first event for post-tool continuations.
-    #[allow(clippy::too_many_lines)]
-    async fn consume_stream(
-        &self,
-        message_request: &MessageRequest,
-        apply_stall_timeout: bool,
-    ) -> Result<Vec<AssistantEvent>, RuntimeError> {
-        let mut stream = self
-            .client
-            .stream_message(message_request)
-            .await
-            .map_err(|error| {
-                RuntimeError::new(format_user_visible_api_error(&self.session_id, &error))
-            })?;
-        let mut stdout = io::stdout();
-        let mut sink = io::sink();
-        let out: &mut dyn Write = if self.emit_output {
-            &mut stdout
-        } else {
-            &mut sink
-        };
-        let renderer = TerminalRenderer::new();
-        let mut markdown_stream = MarkdownStreamState::default();
-        let mut events = Vec::new();
-        let mut pending_tool: Option<(String, String, String)> = None;
-        let mut block_has_thinking_summary = false;
-        let mut saw_stop = false;
-        let mut received_any_event = false;
-
-        loop {
-            let next = if apply_stall_timeout && !received_any_event {
-                match tokio::time::timeout(POST_TOOL_STALL_TIMEOUT, stream.next_event()).await {
-                    Ok(inner) => inner.map_err(|error| {
-                        RuntimeError::new(format_user_visible_api_error(&self.session_id, &error))
-                    })?,
-                    Err(_elapsed) => {
-                        return Err(RuntimeError::new(
-                            "post-tool stall: model did not respond within timeout",
-                        ));
-                    }
-                }
-            } else {
-                stream.next_event().await.map_err(|error| {
-                    RuntimeError::new(format_user_visible_api_error(&self.session_id, &error))
-                })?
-            };
-
-            let Some(event) = next else {
-                break;
-            };
-            received_any_event = true;
-
-            match event {
-                ApiStreamEvent::MessageStart(start) => {
-                    for block in start.message.content {
-                        push_output_block(
-                            block,
-                            out,
-                            &mut events,
-                            &mut pending_tool,
-                            true,
-                            &mut block_has_thinking_summary,
-                        )?;
-                    }
-                }
-                ApiStreamEvent::ContentBlockStart(start) => {
-                    push_output_block(
-                        start.content_block,
-                        out,
-                        &mut events,
-                        &mut pending_tool,
-                        true,
-                        &mut block_has_thinking_summary,
-                    )?;
-                }
-                ApiStreamEvent::ContentBlockDelta(delta) => match delta.delta {
-                    ContentBlockDelta::TextDelta { text } => {
-                        if !text.is_empty() {
-                            if let Some(progress_reporter) = &self.progress_reporter {
-                                progress_reporter.mark_text_phase(&text);
-                            }
-                            if let Some(rendered) = markdown_stream.push(&renderer, &text) {
-                                write!(out, "{rendered}")
-                                    .and_then(|()| out.flush())
-                                    .map_err(|error| RuntimeError::new(error.to_string()))?;
-                            }
-                            events.push(AssistantEvent::TextDelta(text));
-                        }
-                    }
-                    ContentBlockDelta::InputJsonDelta { partial_json } => {
-                        if let Some((_, _, input)) = &mut pending_tool {
-                            input.push_str(&partial_json);
-                        }
-                    }
-                    ContentBlockDelta::ThinkingDelta { .. } => {
-                        if !block_has_thinking_summary {
-                            render_thinking_block_summary(out, None, false)?;
-                            block_has_thinking_summary = true;
-                        }
-                    }
-                    ContentBlockDelta::SignatureDelta { .. } => {}
-                },
-                ApiStreamEvent::ContentBlockStop(_) => {
-                    block_has_thinking_summary = false;
-                    if let Some(rendered) = markdown_stream.flush(&renderer) {
-                        write!(out, "{rendered}")
-                            .and_then(|()| out.flush())
-                            .map_err(|error| RuntimeError::new(error.to_string()))?;
-                    }
-                    if let Some((id, name, input)) = pending_tool.take() {
-                        if let Some(progress_reporter) = &self.progress_reporter {
-                            progress_reporter.mark_tool_phase(&name, &input);
-                        }
-                        // Display tool call now that input is fully accumulated
-                        writeln!(out, "\n{}", format_tool_call_start(&name, &input))
-                            .and_then(|()| out.flush())
-                            .map_err(|error| RuntimeError::new(error.to_string()))?;
-                        events.push(AssistantEvent::ToolUse { id, name, input });
-                    }
-                }
-                ApiStreamEvent::MessageDelta(delta) => {
-                    events.push(AssistantEvent::Usage(delta.usage.token_usage()));
-                }
-                ApiStreamEvent::MessageStop(_) => {
-                    saw_stop = true;
-                    if let Some(rendered) = markdown_stream.flush(&renderer) {
-                        write!(out, "{rendered}")
-                            .and_then(|()| out.flush())
-                            .map_err(|error| RuntimeError::new(error.to_string()))?;
-                    }
-                    events.push(AssistantEvent::MessageStop);
-                }
-            }
-        }
-
-        push_prompt_cache_record(&self.client, &mut events);
-
-        if !saw_stop
-            && events.iter().any(|event| {
-                matches!(event, AssistantEvent::TextDelta(text) if !text.is_empty())
-                    || matches!(event, AssistantEvent::ToolUse { .. })
-            })
-        {
-            events.push(AssistantEvent::MessageStop);
-        }
-
-        if events
-            .iter()
-            .any(|event| matches!(event, AssistantEvent::MessageStop))
-        {
-            return Ok(events);
-        }
-
-        let response = self
-            .client
-            .send_message(&MessageRequest {
-                stream: false,
-                ..message_request.clone()
-            })
-            .await
-            .map_err(|error| {
-                RuntimeError::new(format_user_visible_api_error(&self.session_id, &error))
-            })?;
-        let mut events = response_to_events(response, out)?;
-        push_prompt_cache_record(&self.client, &mut events);
-        Ok(events)
-    }
-}
-
-/// Returns `true` when the conversation ends with a tool-result message,
-/// meaning the model is expected to continue after tool execution.
-fn request_ends_with_tool_result(request: &ApiRequest) -> bool {
-    request
-        .messages
-        .last()
-        .is_some_and(|message| message.role == MessageRole::Tool)
-}
-
-fn format_user_visible_api_error(session_id: &str, error: &api::ApiError) -> String {
-    if error.is_context_window_failure() {
-        format_context_window_blocked_error(session_id, error)
-    } else if error.is_generic_fatal_wrapper() {
-        let mut qualifiers = vec![format!("session {session_id}")];
-        if let Some(request_id) = error.request_id() {
-            qualifiers.push(format!("trace {request_id}"));
-        }
-        format!(
-            "{} ({}): {}",
-            error.safe_failure_class(),
-            qualifiers.join(", "),
-            error
-        )
-    } else {
-        error.to_string()
-    }
-}
-
-fn format_context_window_blocked_error(session_id: &str, error: &api::ApiError) -> String {
-    let mut lines = vec![
-        "Context window blocked".to_string(),
-        "  Failure class    context_window_blocked".to_string(),
-        format!("  Session          {session_id}"),
-    ];
-
-    if let Some(request_id) = error.request_id() {
-        lines.push(format!("  Trace            {request_id}"));
-    }
-
-    match error {
-        api::ApiError::ContextWindowExceeded {
-            model,
-            estimated_input_tokens,
-            requested_output_tokens,
-            estimated_total_tokens,
-            context_window_tokens,
-        } => {
-            lines.push(format!("  Model            {model}"));
-            lines.push(format!(
-                "  Input estimate   ~{estimated_input_tokens} tokens (heuristic)"
-            ));
-            lines.push(format!(
-                "  Requested output {requested_output_tokens} tokens"
-            ));
-            lines.push(format!(
-                "  Total estimate   ~{estimated_total_tokens} tokens (heuristic)"
-            ));
-            lines.push(format!("  Context window   {context_window_tokens} tokens"));
-        }
-        api::ApiError::Api { message, body, .. } => {
-            let detail = message.as_deref().unwrap_or(body).trim();
-            if !detail.is_empty() {
-                lines.push(format!(
-                    "  Detail           {}",
-                    truncate_for_summary(detail, 120)
-                ));
-            }
-        }
-        api::ApiError::RetriesExhausted { last_error, .. } => {
-            let detail = match last_error.as_ref() {
-                api::ApiError::Api { message, body, .. } => message.as_deref().unwrap_or(body),
-                other => return format_context_window_blocked_error(session_id, other),
-            }
-            .trim();
-            if !detail.is_empty() {
-                lines.push(format!(
-                    "  Detail           {}",
-                    truncate_for_summary(detail, 120)
-                ));
-            }
-        }
-        _ => {}
-    }
-
-    lines.push(String::new());
-    lines.push("Recovery".to_string());
-    lines.push("  Compact          /compact".to_string());
-    lines.push(format!(
-        "  Resume compact   claw --resume {session_id} /compact"
-    ));
-    lines.push("  Fresh session    /clear --confirm".to_string());
-    lines.push(
-        "  Reduce scope     remove large pasted context/files or ask for a smaller slice"
-            .to_string(),
-    );
-    lines.push("  Retry            rerun after compacting or reducing the request".to_string());
-
-    lines.join("\n")
-}
-
-fn final_assistant_text(summary: &runtime::TurnSummary) -> String {
-    summary
-        .assistant_messages
-        .last()
-        .map(|message| {
-            message
-                .blocks
-                .iter()
-                .filter_map(|block| match block {
-                    ContentBlock::Text { text } => Some(text.as_str()),
-                    _ => None,
-                })
-                .collect::<Vec<_>>()
-                .join("")
-        })
-        .unwrap_or_default()
-}
-
-fn collect_tool_uses(summary: &runtime::TurnSummary) -> Vec<serde_json::Value> {
-    summary
-        .assistant_messages
-        .iter()
-        .flat_map(|message| message.blocks.iter())
-        .filter_map(|block| match block {
-            ContentBlock::ToolUse { id, name, input } => Some(json!({
-                "id": id,
-                "name": name,
-                "input": input,
-            })),
-            _ => None,
-        })
-        .collect()
-}
-
-fn collect_tool_results(summary: &runtime::TurnSummary) -> Vec<serde_json::Value> {
-    summary
-        .tool_results
-        .iter()
-        .flat_map(|message| message.blocks.iter())
-        .filter_map(|block| match block {
-            ContentBlock::ToolResult {
-                tool_use_id,
-                tool_name,
-                output,
-                is_error,
-            } => Some(json!({
-                "tool_use_id": tool_use_id,
-                "tool_name": tool_name,
-                "output": output,
-                "is_error": is_error,
-            })),
-            _ => None,
-        })
-        .collect()
-}
-
-fn collect_prompt_cache_events(summary: &runtime::TurnSummary) -> Vec<serde_json::Value> {
-    summary
-        .prompt_cache_events
-        .iter()
-        .map(|event| {
-            json!({
-                "unexpected": event.unexpected,
-                "reason": event.reason,
-                "previous_cache_read_input_tokens": event.previous_cache_read_input_tokens,
-                "current_cache_read_input_tokens": event.current_cache_read_input_tokens,
-                "token_drop": event.token_drop,
-            })
-        })
-        .collect()
-}
-
-fn slash_command_completion_candidates_with_sessions(
-    model: &str,
-    active_session_id: Option<&str>,
-    recent_session_ids: Vec<String>,
-) -> Vec<String> {
-    let mut completions = BTreeSet::new();
-
-    for spec in slash_command_specs() {
-        completions.insert(format!("/{}", spec.name));
-        for alias in spec.aliases {
-            completions.insert(format!("/{alias}"));
-        }
-    }
-
-    for candidate in [
-        "/bughunter ",
-        "/clear --confirm",
-        "/config ",
-        "/config env",
-        "/config hooks",
-        "/config model",
-        "/config plugins",
-        "/mcp ",
-        "/mcp list",
-        "/mcp show ",
-        "/export ",
-        "/issue ",
-        "/model ",
-        "/model opus",
-        "/model sonnet",
-        "/model haiku",
-        "/permissions ",
-        "/permissions read-only",
-        "/permissions workspace-write",
-        "/permissions danger-full-access",
-        "/plugin list",
-        "/plugin install ",
-        "/plugin enable ",
-        "/plugin disable ",
-        "/plugin uninstall ",
-        "/plugin update ",
-        "/plugins list",
-        "/pr ",
-        "/resume ",
-        "/session list",
-        "/session switch ",
-        "/session fork ",
-        "/teleport ",
-        "/ultraplan ",
-        "/agents help",
-        "/mcp help",
-        "/skills help",
-    ] {
-        completions.insert(candidate.to_string());
-    }
-
-    if !model.trim().is_empty() {
-        completions.insert(format!("/model {}", resolve_model_alias(model)));
-        completions.insert(format!("/model {model}"));
-    }
-
-    if let Some(active_session_id) = active_session_id.filter(|value| !value.trim().is_empty()) {
-        completions.insert(format!("/resume {active_session_id}"));
-        completions.insert(format!("/session switch {active_session_id}"));
-    }
-
-    for session_id in recent_session_ids
-        .into_iter()
-        .filter(|value| !value.trim().is_empty())
-        .take(10)
-    {
-        completions.insert(format!("/resume {session_id}"));
-        completions.insert(format!("/session switch {session_id}"));
-    }
-
-    completions.into_iter().collect()
-}
-
-fn format_tool_call_start(name: &str, input: &str) -> String {
-    let parsed: serde_json::Value =
-        serde_json::from_str(input).unwrap_or(serde_json::Value::String(input.to_string()));
-
-    let detail = match name {
-        "bash" | "Bash" => format_bash_call(&parsed),
-        "read_file" | "Read" => {
-            let path = extract_tool_path(&parsed);
-            format!("\x1b[2m📄 Reading {path}…\x1b[0m")
-        }
-        "write_file" | "Write" => {
-            let path = extract_tool_path(&parsed);
-            let lines = parsed
-                .get("content")
-                .and_then(|value| value.as_str())
-                .map_or(0, |content| content.lines().count());
-            format!("\x1b[1;32m✏️ Writing {path}\x1b[0m \x1b[2m({lines} lines)\x1b[0m")
-        }
-        "edit_file" | "Edit" => {
-            let path = extract_tool_path(&parsed);
-            let old_value = parsed
-                .get("old_string")
-                .or_else(|| parsed.get("oldString"))
-                .and_then(|value| value.as_str())
-                .unwrap_or_default();
-            let new_value = parsed
-                .get("new_string")
-                .or_else(|| parsed.get("newString"))
-                .and_then(|value| value.as_str())
-                .unwrap_or_default();
-            format!(
-                "\x1b[1;33m📝 Editing {path}\x1b[0m{}",
-                format_patch_preview(old_value, new_value)
-                    .map(|preview| format!("\n{preview}"))
-                    .unwrap_or_default()
-            )
-        }
-        "glob_search" | "Glob" => format_search_start("🔎 Glob", &parsed),
-        "grep_search" | "Grep" => format_search_start("🔎 Grep", &parsed),
-        "web_search" | "WebSearch" => parsed
-            .get("query")
-            .and_then(|value| value.as_str())
-            .unwrap_or("?")
-            .to_string(),
-        _ => summarize_tool_payload(input),
-    };
-
-    let border = "─".repeat(name.len() + 8);
-    format!(
-        "\x1b[38;5;245m╭─ \x1b[1;36m{name}\x1b[0;38;5;245m ─╮\x1b[0m\n\x1b[38;5;245m│\x1b[0m {detail}\n\x1b[38;5;245m╰{border}╯\x1b[0m"
-    )
-}
-
-fn format_tool_result(name: &str, output: &str, is_error: bool) -> String {
-    let icon = if is_error {
-        "\x1b[1;31m✗\x1b[0m"
-    } else {
-        "\x1b[1;32m✓\x1b[0m"
-    };
-    if is_error {
-        let summary = truncate_for_summary(output.trim(), 160);
-        return if summary.is_empty() {
-            format!("{icon} \x1b[38;5;245m{name}\x1b[0m")
-        } else {
-            format!("{icon} \x1b[38;5;245m{name}\x1b[0m\n\x1b[38;5;203m{summary}\x1b[0m")
-        };
-    }
-
-    let parsed: serde_json::Value =
-        serde_json::from_str(output).unwrap_or(serde_json::Value::String(output.to_string()));
-    match name {
-        "bash" | "Bash" => format_bash_result(icon, &parsed),
-        "read_file" | "Read" => format_read_result(icon, &parsed),
-        "write_file" | "Write" => format_write_result(icon, &parsed),
-        "edit_file" | "Edit" => format_edit_result(icon, &parsed),
-        "glob_search" | "Glob" => format_glob_result(icon, &parsed),
-        "grep_search" | "Grep" => format_grep_result(icon, &parsed),
-        _ => format_generic_tool_result(icon, name, &parsed),
-    }
-}
-
-const DISPLAY_TRUNCATION_NOTICE: &str =
-    "\x1b[2m… output truncated for display; full result preserved in session.\x1b[0m";
-const READ_DISPLAY_MAX_LINES: usize = 80;
-const READ_DISPLAY_MAX_CHARS: usize = 6_000;
-const TOOL_OUTPUT_DISPLAY_MAX_LINES: usize = 60;
-const TOOL_OUTPUT_DISPLAY_MAX_CHARS: usize = 4_000;
-
-fn extract_tool_path(parsed: &serde_json::Value) -> String {
-    parsed
-        .get("file_path")
-        .or_else(|| parsed.get("filePath"))
-        .or_else(|| parsed.get("path"))
-        .and_then(|value| value.as_str())
-        .unwrap_or("?")
-        .to_string()
-}
-
-fn format_search_start(label: &str, parsed: &serde_json::Value) -> String {
-    let pattern = parsed
-        .get("pattern")
-        .and_then(|value| value.as_str())
-        .unwrap_or("?");
-    let scope = parsed
-        .get("path")
-        .and_then(|value| value.as_str())
-        .unwrap_or(".");
-    format!("{label} {pattern}\n\x1b[2min {scope}\x1b[0m")
-}
-
-fn format_patch_preview(old_value: &str, new_value: &str) -> Option<String> {
-    if old_value.is_empty() && new_value.is_empty() {
-        return None;
-    }
-    Some(format!(
-        "\x1b[38;5;203m- {}\x1b[0m\n\x1b[38;5;70m+ {}\x1b[0m",
-        truncate_for_summary(first_visible_line(old_value), 72),
-        truncate_for_summary(first_visible_line(new_value), 72)
-    ))
-}
-
-fn format_bash_call(parsed: &serde_json::Value) -> String {
-    let command = parsed
-        .get("command")
-        .and_then(|value| value.as_str())
-        .unwrap_or_default();
-    if command.is_empty() {
-        String::new()
-    } else {
-        format!(
-            "\x1b[48;5;236;38;5;255m $ {} \x1b[0m",
-            truncate_for_summary(command, 160)
-        )
-    }
-}
-
-fn first_visible_line(text: &str) -> &str {
-    text.lines()
-        .find(|line| !line.trim().is_empty())
-        .unwrap_or(text)
-}
-
-fn format_bash_result(icon: &str, parsed: &serde_json::Value) -> String {
-    use std::fmt::Write as _;
-
-    let mut lines = vec![format!("{icon} \x1b[38;5;245mbash\x1b[0m")];
-    if let Some(task_id) = parsed
-        .get("backgroundTaskId")
-        .and_then(|value| value.as_str())
-    {
-        write!(&mut lines[0], " backgrounded ({task_id})").expect("write to string");
-    } else if let Some(status) = parsed
-        .get("returnCodeInterpretation")
-        .and_then(|value| value.as_str())
-        .filter(|status| !status.is_empty())
-    {
-        write!(&mut lines[0], " {status}").expect("write to string");
-    }
-
-    if let Some(stdout) = parsed.get("stdout").and_then(|value| value.as_str()) {
-        if !stdout.trim().is_empty() {
-            lines.push(truncate_output_for_display(
-                stdout,
-                TOOL_OUTPUT_DISPLAY_MAX_LINES,
-                TOOL_OUTPUT_DISPLAY_MAX_CHARS,
-            ));
-        }
-    }
-    if let Some(stderr) = parsed.get("stderr").and_then(|value| value.as_str()) {
-        if !stderr.trim().is_empty() {
-            lines.push(format!(
-                "\x1b[38;5;203m{}\x1b[0m",
-                truncate_output_for_display(
-                    stderr,
-                    TOOL_OUTPUT_DISPLAY_MAX_LINES,
-                    TOOL_OUTPUT_DISPLAY_MAX_CHARS,
-                )
-            ));
-        }
-    }
-
-    lines.join("\n\n")
-}
-
-fn format_read_result(icon: &str, parsed: &serde_json::Value) -> String {
-    let file = parsed.get("file").unwrap_or(parsed);
-    let path = extract_tool_path(file);
-    let start_line = file
-        .get("startLine")
-        .and_then(serde_json::Value::as_u64)
-        .unwrap_or(1);
-    let num_lines = file
-        .get("numLines")
-        .and_then(serde_json::Value::as_u64)
-        .unwrap_or(0);
-    let total_lines = file
-        .get("totalLines")
-        .and_then(serde_json::Value::as_u64)
-        .unwrap_or(num_lines);
-    let content = file
-        .get("content")
-        .and_then(|value| value.as_str())
-        .unwrap_or_default();
-    let end_line = start_line.saturating_add(num_lines.saturating_sub(1));
-
-    format!(
-        "{icon} \x1b[2m📄 Read {path} (lines {}-{} of {})\x1b[0m\n{}",
-        start_line,
-        end_line.max(start_line),
-        total_lines,
-        truncate_output_for_display(content, READ_DISPLAY_MAX_LINES, READ_DISPLAY_MAX_CHARS)
-    )
-}
-
-fn format_write_result(icon: &str, parsed: &serde_json::Value) -> String {
-    let path = extract_tool_path(parsed);
-    let kind = parsed
-        .get("type")
-        .and_then(|value| value.as_str())
-        .unwrap_or("write");
-    let line_count = parsed
-        .get("content")
-        .and_then(|value| value.as_str())
-        .map_or(0, |content| content.lines().count());
-    format!(
-        "{icon} \x1b[1;32m✏️ {} {path}\x1b[0m \x1b[2m({line_count} lines)\x1b[0m",
-        if kind == "create" { "Wrote" } else { "Updated" },
-    )
-}
-
-fn format_structured_patch_preview(parsed: &serde_json::Value) -> Option<String> {
-    let hunks = parsed.get("structuredPatch")?.as_array()?;
-    let mut preview = Vec::new();
-    for hunk in hunks.iter().take(2) {
-        let lines = hunk.get("lines")?.as_array()?;
-        for line in lines.iter().filter_map(|value| value.as_str()).take(6) {
-            match line.chars().next() {
-                Some('+') => preview.push(format!("\x1b[38;5;70m{line}\x1b[0m")),
-                Some('-') => preview.push(format!("\x1b[38;5;203m{line}\x1b[0m")),
-                _ => preview.push(line.to_string()),
-            }
-        }
-    }
-    if preview.is_empty() {
-        None
-    } else {
-        Some(preview.join("\n"))
-    }
-}
-
-fn format_edit_result(icon: &str, parsed: &serde_json::Value) -> String {
-    let path = extract_tool_path(parsed);
-    let suffix = if parsed
-        .get("replaceAll")
-        .and_then(serde_json::Value::as_bool)
-        .unwrap_or(false)
-    {
-        " (replace all)"
-    } else {
-        ""
-    };
-    let preview = format_structured_patch_preview(parsed).or_else(|| {
-        let old_value = parsed
-            .get("oldString")
-            .and_then(|value| value.as_str())
-            .unwrap_or_default();
-        let new_value = parsed
-            .get("newString")
-            .and_then(|value| value.as_str())
-            .unwrap_or_default();
-        format_patch_preview(old_value, new_value)
-    });
-
-    match preview {
-        Some(preview) => format!("{icon} \x1b[1;33m📝 Edited {path}{suffix}\x1b[0m\n{preview}"),
-        None => format!("{icon} \x1b[1;33m📝 Edited {path}{suffix}\x1b[0m"),
-    }
-}
-
-fn format_glob_result(icon: &str, parsed: &serde_json::Value) -> String {
-    let num_files = parsed
-        .get("numFiles")
-        .and_then(serde_json::Value::as_u64)
-        .unwrap_or(0);
-    let filenames = parsed
-        .get("filenames")
-        .and_then(|value| value.as_array())
-        .map(|files| {
-            files
-                .iter()
-                .filter_map(|value| value.as_str())
-                .take(8)
-                .collect::<Vec<_>>()
-                .join("\n")
-        })
-        .unwrap_or_default();
-    if filenames.is_empty() {
-        format!("{icon} \x1b[38;5;245mglob_search\x1b[0m matched {num_files} files")
-    } else {
-        format!("{icon} \x1b[38;5;245mglob_search\x1b[0m matched {num_files} files\n{filenames}")
-    }
-}
-
-fn format_grep_result(icon: &str, parsed: &serde_json::Value) -> String {
-    let num_matches = parsed
-        .get("numMatches")
-        .and_then(serde_json::Value::as_u64)
-        .unwrap_or(0);
-    let num_files = parsed
-        .get("numFiles")
-        .and_then(serde_json::Value::as_u64)
-        .unwrap_or(0);
-    let content = parsed
-        .get("content")
-        .and_then(|value| value.as_str())
-        .unwrap_or_default();
-    let filenames = parsed
-        .get("filenames")
-        .and_then(|value| value.as_array())
-        .map(|files| {
-            files
-                .iter()
-                .filter_map(|value| value.as_str())
-                .take(8)
-                .collect::<Vec<_>>()
-                .join("\n")
-        })
-        .unwrap_or_default();
-    let summary = format!(
-        "{icon} \x1b[38;5;245mgrep_search\x1b[0m {num_matches} matches across {num_files} files"
-    );
-    if !content.trim().is_empty() {
-        format!(
-            "{summary}\n{}",
-            truncate_output_for_display(
-                content,
-                TOOL_OUTPUT_DISPLAY_MAX_LINES,
-                TOOL_OUTPUT_DISPLAY_MAX_CHARS,
-            )
-        )
-    } else if !filenames.is_empty() {
-        format!("{summary}\n{filenames}")
-    } else {
-        summary
-    }
-}
-
-fn format_generic_tool_result(icon: &str, name: &str, parsed: &serde_json::Value) -> String {
-    let rendered_output = match parsed {
-        serde_json::Value::String(text) => text.clone(),
-        serde_json::Value::Null => String::new(),
-        serde_json::Value::Object(_) | serde_json::Value::Array(_) => {
-            serde_json::to_string_pretty(parsed).unwrap_or_else(|_| parsed.to_string())
-        }
-        _ => parsed.to_string(),
-    };
-    let preview = truncate_output_for_display(
-        &rendered_output,
-        TOOL_OUTPUT_DISPLAY_MAX_LINES,
-        TOOL_OUTPUT_DISPLAY_MAX_CHARS,
-    );
-
-    if preview.is_empty() {
-        format!("{icon} \x1b[38;5;245m{name}\x1b[0m")
-    } else if preview.contains('\n') {
-        format!("{icon} \x1b[38;5;245m{name}\x1b[0m\n{preview}")
-    } else {
-        format!("{icon} \x1b[38;5;245m{name}:\x1b[0m {preview}")
-    }
-}
-
-fn summarize_tool_payload(payload: &str) -> String {
-    let compact = match serde_json::from_str::<serde_json::Value>(payload) {
-        Ok(value) => value.to_string(),
-        Err(_) => payload.trim().to_string(),
-    };
-    truncate_for_summary(&compact, 96)
-}
-
-fn truncate_for_summary(value: &str, limit: usize) -> String {
-    let mut chars = value.chars();
-    let truncated = chars.by_ref().take(limit).collect::<String>();
-    if chars.next().is_some() {
-        format!("{truncated}…")
-    } else {
-        truncated
-    }
-}
-
-fn truncate_output_for_display(content: &str, max_lines: usize, max_chars: usize) -> String {
-    let original = content.trim_end_matches('\n');
-    if original.is_empty() {
-        return String::new();
-    }
-
-    let mut preview_lines = Vec::new();
-    let mut used_chars = 0usize;
-    let mut truncated = false;
-
-    for (index, line) in original.lines().enumerate() {
-        if index >= max_lines {
-            truncated = true;
-            break;
-        }
-
-        let newline_cost = usize::from(!preview_lines.is_empty());
-        let available = max_chars.saturating_sub(used_chars + newline_cost);
-        if available == 0 {
-            truncated = true;
-            break;
-        }
-
-        let line_chars = line.chars().count();
-        if line_chars > available {
-            preview_lines.push(line.chars().take(available).collect::<String>());
-            truncated = true;
-            break;
-        }
-
-        preview_lines.push(line.to_string());
-        used_chars += newline_cost + line_chars;
-    }
-
-    let mut preview = preview_lines.join("\n");
-    if truncated {
-        if !preview.is_empty() {
-            preview.push('\n');
-        }
-        preview.push_str(DISPLAY_TRUNCATION_NOTICE);
-    }
-    preview
-}
-
-fn render_thinking_block_summary(
-    out: &mut (impl Write + ?Sized),
-    char_count: Option<usize>,
-    redacted: bool,
-) -> Result<(), RuntimeError> {
-    let summary = if redacted {
-        "\n▶ Thinking block hidden by provider\n".to_string()
-    } else if let Some(char_count) = char_count {
-        format!("\n▶ Thinking ({char_count} chars hidden)\n")
-    } else {
-        "\n▶ Thinking hidden\n".to_string()
-    };
-    write!(out, "{summary}")
-        .and_then(|()| out.flush())
-        .map_err(|error| RuntimeError::new(error.to_string()))
-}
-
-fn push_output_block(
-    block: OutputContentBlock,
-    out: &mut (impl Write + ?Sized),
-    events: &mut Vec<AssistantEvent>,
-    pending_tool: &mut Option<(String, String, String)>,
-    streaming_tool_input: bool,
-    block_has_thinking_summary: &mut bool,
-) -> Result<(), RuntimeError> {
-    match block {
-        OutputContentBlock::Text { text } => {
-            if !text.is_empty() {
-                let rendered = TerminalRenderer::new().markdown_to_ansi(&text);
-                write!(out, "{rendered}")
-                    .and_then(|()| out.flush())
-                    .map_err(|error| RuntimeError::new(error.to_string()))?;
-                events.push(AssistantEvent::TextDelta(text));
-            }
-        }
-        OutputContentBlock::ToolUse { id, name, input } => {
-            // During streaming, the initial content_block_start has an empty input ({}).
-            // The real input arrives via input_json_delta events. In
-            // non-streaming responses, preserve a legitimate empty object.
-            let initial_input = if streaming_tool_input
-                && input.is_object()
-                && input.as_object().is_some_and(serde_json::Map::is_empty)
-            {
-                String::new()
-            } else {
-                input.to_string()
-            };
-            *pending_tool = Some((id, name, initial_input));
-        }
-        OutputContentBlock::Thinking { thinking, .. } => {
-            render_thinking_block_summary(out, Some(thinking.chars().count()), false)?;
-            *block_has_thinking_summary = true;
-        }
-        OutputContentBlock::RedactedThinking { .. } => {
-            render_thinking_block_summary(out, None, true)?;
-            *block_has_thinking_summary = true;
-        }
-    }
-    Ok(())
-}
-
-fn response_to_events(
-    response: MessageResponse,
-    out: &mut (impl Write + ?Sized),
-) -> Result<Vec<AssistantEvent>, RuntimeError> {
-    let mut events = Vec::new();
-    let mut pending_tool = None;
-
-    for block in response.content {
-        let mut block_has_thinking_summary = false;
-        push_output_block(
-            block,
-            out,
-            &mut events,
-            &mut pending_tool,
-            false,
-            &mut block_has_thinking_summary,
-        )?;
-        if let Some((id, name, input)) = pending_tool.take() {
-            events.push(AssistantEvent::ToolUse { id, name, input });
-        }
-    }
-
-    events.push(AssistantEvent::Usage(response.usage.token_usage()));
-    events.push(AssistantEvent::MessageStop);
-    Ok(events)
-}
-
-fn push_prompt_cache_record(client: &ApiProviderClient, events: &mut Vec<AssistantEvent>) {
-    // `ApiProviderClient::take_last_prompt_cache_record` is a pass-through
-    // to the Anthropic variant and returns `None` for OpenAI-compat /
-    // xAI variants, which do not have a prompt cache. So this helper
-    // remains a no-op on non-Anthropic providers without any extra
-    // branching here.
-    if let Some(record) = client.take_last_prompt_cache_record() {
-        if let Some(event) = prompt_cache_record_to_runtime_event(record) {
-            events.push(AssistantEvent::PromptCache(event));
-        }
-    }
-}
-
-fn prompt_cache_record_to_runtime_event(
-    record: api::PromptCacheRecord,
-) -> Option<PromptCacheEvent> {
-    let cache_break = record.cache_break?;
-    Some(PromptCacheEvent {
-        unexpected: cache_break.unexpected,
-        reason: cache_break.reason,
-        previous_cache_read_input_tokens: cache_break.previous_cache_read_input_tokens,
-        current_cache_read_input_tokens: cache_break.current_cache_read_input_tokens,
-        token_drop: cache_break.token_drop,
-    })
-}
-
-struct CliToolExecutor {
-    renderer: TerminalRenderer,
-    emit_output: bool,
-    allowed_tools: Option<AllowedToolSet>,
-    tool_registry: GlobalToolRegistry,
-    mcp_state: Option<Arc<Mutex<RuntimeMcpState>>>,
-}
-
-impl CliToolExecutor {
-    fn new(
-        allowed_tools: Option<AllowedToolSet>,
-        emit_output: bool,
-        tool_registry: GlobalToolRegistry,
-        mcp_state: Option<Arc<Mutex<RuntimeMcpState>>>,
-    ) -> Self {
-        Self {
-            renderer: TerminalRenderer::new(),
-            emit_output,
-            allowed_tools,
-            tool_registry,
-            mcp_state,
-        }
-    }
-
-    fn execute_search_tool(&self, value: serde_json::Value) -> Result<String, ToolError> {
-        let input: ToolSearchRequest = serde_json::from_value(value)
-            .map_err(|error| ToolError::new(format!("invalid tool input JSON: {error}")))?;
-        let (pending_mcp_servers, mcp_degraded) =
-            self.mcp_state.as_ref().map_or((None, None), |state| {
-                let state = state
-                    .lock()
-                    .unwrap_or_else(std::sync::PoisonError::into_inner);
-                (state.pending_servers(), state.degraded_report())
-            });
-        serde_json::to_string_pretty(&self.tool_registry.search(
-            &input.query,
-            input.max_results.unwrap_or(5),
-            pending_mcp_servers,
-            mcp_degraded,
-        ))
-        .map_err(|error| ToolError::new(error.to_string()))
-    }
-
-    fn execute_runtime_tool(
-        &self,
-        tool_name: &str,
-        value: serde_json::Value,
-    ) -> Result<String, ToolError> {
-        let Some(mcp_state) = &self.mcp_state else {
-            return Err(ToolError::new(format!(
-                "runtime tool `{tool_name}` is unavailable without configured MCP servers"
-            )));
-        };
-        let mut mcp_state = mcp_state
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-
-        match tool_name {
-            "MCPTool" => {
-                let input: McpToolRequest = serde_json::from_value(value)
-                    .map_err(|error| ToolError::new(format!("invalid tool input JSON: {error}")))?;
-                let qualified_name = input
-                    .qualified_name
-                    .or(input.tool)
-                    .ok_or_else(|| ToolError::new("missing required field `qualifiedName`"))?;
-                mcp_state.call_tool(&qualified_name, input.arguments)
-            }
-            "ListMcpResourcesTool" => {
-                let input: ListMcpResourcesRequest = serde_json::from_value(value)
-                    .map_err(|error| ToolError::new(format!("invalid tool input JSON: {error}")))?;
-                match input.server {
-                    Some(server_name) => mcp_state.list_resources_for_server(&server_name),
-                    None => mcp_state.list_resources_for_all_servers(),
-                }
-            }
-            "ReadMcpResourceTool" => {
-                let input: ReadMcpResourceRequest = serde_json::from_value(value)
-                    .map_err(|error| ToolError::new(format!("invalid tool input JSON: {error}")))?;
-                mcp_state.read_resource(&input.server, &input.uri)
-            }
-            _ => mcp_state.call_tool(tool_name, Some(value)),
-        }
-    }
-}
-
-impl ToolExecutor for CliToolExecutor {
-    fn execute(&mut self, tool_name: &str, input: &str) -> Result<String, ToolError> {
-        if self
-            .allowed_tools
-            .as_ref()
-            .is_some_and(|allowed| !allowed.contains(tool_name))
-        {
-            return Err(ToolError::new(format!(
-                "tool `{tool_name}` is not enabled by the current --allowedTools setting"
-            )));
-        }
-        let value = serde_json::from_str(input)
-            .map_err(|error| ToolError::new(format!("invalid tool input JSON: {error}")))?;
-        let result = if tool_name == "ToolSearch" {
-            self.execute_search_tool(value)
-        } else if self.tool_registry.has_runtime_tool(tool_name) {
-            self.execute_runtime_tool(tool_name, value)
-        } else {
-            self.tool_registry
-                .execute(tool_name, &value)
-                .map_err(ToolError::new)
-        };
-        match result {
-            Ok(output) => {
-                if self.emit_output {
-                    let markdown = format_tool_result(tool_name, &output, false);
-                    self.renderer
-                        .stream_markdown(&markdown, &mut io::stdout())
-                        .map_err(|error| ToolError::new(error.to_string()))?;
-                }
-                Ok(output)
-            }
-            Err(error) => {
-                if self.emit_output {
-                    let markdown = format_tool_result(tool_name, &error.to_string(), true);
-                    self.renderer
-                        .stream_markdown(&markdown, &mut io::stdout())
-                        .map_err(|stream_error| ToolError::new(stream_error.to_string()))?;
-                }
-                Err(error)
-            }
-        }
-    }
-}
-
-fn permission_policy(
-    mode: PermissionMode,
-    feature_config: &runtime::RuntimeFeatureConfig,
-    tool_registry: &GlobalToolRegistry,
-) -> Result<PermissionPolicy, String> {
-    Ok(tool_registry.permission_specs(None)?.into_iter().fold(
-        PermissionPolicy::new(mode).with_permission_rules(feature_config.permission_rules()),
-        |policy, (name, required_permission)| {
-            policy.with_tool_requirement(name, required_permission)
-        },
-    ))
-}
-
-fn convert_messages(messages: &[ConversationMessage]) -> Vec<InputMessage> {
-    messages
-        .iter()
-        .filter_map(|message| {
-            let role = match message.role {
-                MessageRole::System | MessageRole::User | MessageRole::Tool => "user",
-                MessageRole::Assistant => "assistant",
-            };
-            let content = message
-                .blocks
-                .iter()
-                .map(|block| match block {
-                    ContentBlock::Text { text } => InputContentBlock::Text { text: text.clone() },
-                    ContentBlock::ToolUse { id, name, input } => InputContentBlock::ToolUse {
-                        id: id.clone(),
-                        name: name.clone(),
-                        input: serde_json::from_str(input)
-                            .unwrap_or_else(|_| serde_json::json!({ "raw": input })),
-                    },
-                    ContentBlock::ToolResult {
-                        tool_use_id,
-                        output,
-                        is_error,
-                        ..
-                    } => InputContentBlock::ToolResult {
-                        tool_use_id: tool_use_id.clone(),
-                        content: vec![ToolResultContentBlock::Text {
-                            text: output.clone(),
-                        }],
-                        is_error: *is_error,
-                    },
-                })
-                .collect::<Vec<_>>();
-            (!content.is_empty()).then(|| InputMessage {
-                role: role.to_string(),
-                content,
-            })
-        })
-        .collect()
-}
-
-#[allow(clippy::too_many_lines)]
-fn print_help_to(out: &mut impl Write) -> io::Result<()> {
-    writeln!(out, "claw v{VERSION}")?;
-    writeln!(out)?;
-    writeln!(out, "Usage:")?;
-    writeln!(
-        out,
-        "  claw [--model MODEL] [--allowedTools TOOL[,TOOL...]]"
-    )?;
-    writeln!(out, "      Start the interactive REPL")?;
-    writeln!(
-        out,
-        "  claw [--model MODEL] [--output-format text|json] prompt TEXT"
-    )?;
-    writeln!(out, "      Send one prompt and exit")?;
-    writeln!(
-        out,
-        "  claw [--model MODEL] [--output-format text|json] TEXT"
-    )?;
-    writeln!(out, "      Shorthand non-interactive prompt mode")?;
-    writeln!(
-        out,
-        "  claw --resume [SESSION.jsonl|session-id|latest] [/status] [/compact] [...]"
-    )?;
-    writeln!(
-        out,
-        "      Inspect or maintain a saved session without entering the REPL"
-    )?;
-    writeln!(out, "  claw help")?;
-    writeln!(out, "      Alias for --help")?;
-    writeln!(out, "  claw version")?;
-    writeln!(out, "      Alias for --version")?;
-    writeln!(out, "  claw status")?;
-    writeln!(
-        out,
-        "      Show the current local workspace status snapshot"
-    )?;
-    writeln!(out, "  claw sandbox")?;
-    writeln!(out, "      Show the current sandbox isolation snapshot")?;
-    writeln!(out, "  claw doctor")?;
-    writeln!(
-        out,
-        "      Diagnose local auth, config, workspace, and sandbox health"
-    )?;
-    writeln!(out, "  claw dump-manifests")?;
-    writeln!(out, "  claw bootstrap-plan")?;
-    writeln!(out, "  claw agents")?;
-    writeln!(out, "  claw mcp")?;
-    writeln!(out, "  claw skills")?;
-    writeln!(out, "  claw system-prompt [--cwd PATH] [--date YYYY-MM-DD]")?;
-    writeln!(out, "  claw login")?;
-    writeln!(out, "  claw logout")?;
-    writeln!(out, "  claw init")?;
-    writeln!(
-        out,
-        "  claw export [PATH] [--session SESSION] [--output PATH]"
-    )?;
-    writeln!(
-        out,
-        "      Dump the latest (or named) session as markdown; writes to PATH or stdout"
-    )?;
-    writeln!(out)?;
-    writeln!(out, "Flags:")?;
-    writeln!(
-        out,
-        "  --model MODEL              Override the active model"
-    )?;
-    writeln!(
-        out,
-        "  --output-format FORMAT     Non-interactive output format: text or json"
-    )?;
-    writeln!(
-        out,
-        "  --compact                  Strip tool call details; print only the final assistant text (text mode only; useful for piping)"
-    )?;
-    writeln!(
-        out,
-        "  --permission-mode MODE     Set read-only, workspace-write, or danger-full-access"
-    )?;
-    writeln!(
-        out,
-        "  --dangerously-skip-permissions  Skip all permission checks"
-    )?;
-    writeln!(out, "  --allowedTools TOOLS       Restrict enabled tools (repeatable; comma-separated aliases supported)")?;
-    writeln!(
-        out,
-        "  --version, -V              Print version and build information locally"
-    )?;
-    writeln!(out)?;
-    writeln!(out, "Interactive slash commands:")?;
-    writeln!(out, "{}", render_slash_command_help())?;
-    writeln!(out)?;
-    let resume_commands = resume_supported_slash_commands()
-        .into_iter()
-        .map(|spec| match spec.argument_hint {
-            Some(argument_hint) => format!("/{} {}", spec.name, argument_hint),
-            None => format!("/{}", spec.name),
-        })
-        .collect::<Vec<_>>()
-        .join(", ");
-    writeln!(out, "Resume-safe commands: {resume_commands}")?;
-    writeln!(out)?;
-    writeln!(out, "Session shortcuts:")?;
-    writeln!(
-        out,
-        "  REPL turns auto-save to .claw/sessions/<session-id>.{PRIMARY_SESSION_EXTENSION}"
-    )?;
-    writeln!(
-        out,
-        "  Use `{LATEST_SESSION_REFERENCE}` with --resume, /resume, or /session switch to target the newest saved session"
-    )?;
-    writeln!(
-        out,
-        "  Use /session list in the REPL to browse managed sessions"
-    )?;
-    writeln!(out, "Examples:")?;
-    writeln!(out, "  claw --model claude-opus \"summarize this repo\"")?;
-    writeln!(
-        out,
-        "  claw --output-format json prompt \"explain src/main.rs\""
-    )?;
-    writeln!(out, "  claw --compact \"summarize Cargo.toml\" | wc -l")?;
-    writeln!(
-        out,
-        "  claw --allowedTools read,glob \"summarize Cargo.toml\""
-    )?;
-    writeln!(out, "  claw --resume {LATEST_SESSION_REFERENCE}")?;
-    writeln!(
-        out,
-        "  claw --resume {LATEST_SESSION_REFERENCE} /status /diff /export notes.txt"
-    )?;
-    writeln!(out, "  claw agents")?;
-    writeln!(out, "  claw mcp show my-server")?;
-    writeln!(out, "  claw /skills")?;
-    writeln!(out, "  claw doctor")?;
-    writeln!(out, "  claw login")?;
-    writeln!(out, "  claw init")?;
-    writeln!(out, "  claw export")?;
-    writeln!(out, "  claw export conversation.md")?;
-    Ok(())
-}
-
-fn print_help(output_format: CliOutputFormat) -> Result<(), Box<dyn std::error::Error>> {
-    let mut buffer = Vec::new();
-    print_help_to(&mut buffer)?;
-    let message = String::from_utf8(buffer)?;
-    match output_format {
-        CliOutputFormat::Text => print!("{message}"),
-        CliOutputFormat::Json => println!(
-            "{}",
-            serde_json::to_string_pretty(&json!({
-                "kind": "help",
-                "message": message,
-            }))?
-        ),
-    }
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{
-        build_runtime_plugin_state_with_loader, build_runtime_with_plugin_state,
-        collect_session_prompt_history, create_managed_session_handle, describe_tool_progress,
-        filter_tool_specs, format_bughunter_report, format_commit_preflight_report,
-        format_commit_skipped_report, format_compact_report, format_connected_line,
-        format_cost_report, format_history_timestamp, format_internal_prompt_progress_line,
-        format_issue_report, format_model_report, format_model_switch_report,
-        format_permissions_report, format_permissions_switch_report, format_pr_report,
-        format_resume_report, format_status_report, format_tool_call_start, format_tool_result,
-        format_ultraplan_report, format_unknown_slash_command,
-        format_unknown_slash_command_message, format_user_visible_api_error,
-        merge_prompt_with_stdin, normalize_permission_mode, parse_args, parse_export_args,
-        parse_git_status_branch, parse_git_status_metadata_for, parse_git_workspace_summary,
-        parse_history_count, permission_policy, print_help_to, push_output_block,
-        render_config_report, render_diff_report, render_diff_report_for, render_memory_report,
-        render_prompt_history_report, render_repl_help, render_resume_usage,
-        render_session_markdown, resolve_model_alias, resolve_model_alias_with_config,
-        resolve_repl_model, resolve_session_reference, response_to_events,
-        resume_supported_slash_commands, run_resume_command, short_tool_id,
-        slash_command_completion_candidates_with_sessions, status_context,
-        summarize_tool_payload_for_markdown, validate_no_args, write_mcp_server_fixture, CliAction,
-        CliOutputFormat, CliToolExecutor, GitWorkspaceSummary, InternalPromptProgressEvent,
-        InternalPromptProgressState, LiveCli, LocalHelpTopic, PromptHistoryEntry, SlashCommand,
-        StatusUsage, DEFAULT_MODEL, LATEST_SESSION_REFERENCE,
-    };
-    use api::{ApiError, MessageResponse, OutputContentBlock, Usage};
-    use plugins::{
-        PluginManager, PluginManagerConfig, PluginTool, PluginToolDefinition, PluginToolPermission,
-    };
-    use runtime::{
-        load_oauth_credentials, save_oauth_credentials, AssistantEvent, ConfigLoader, ContentBlock,
-        ConversationMessage, MessageRole, OAuthConfig, PermissionMode, Session, ToolExecutor,
-    };
-    use serde_json::json;
-    use std::fs;
-    use std::io::{Read, Write};
-    use std::net::TcpListener;
-    use std::path::{Path, PathBuf};
-    use std::process::Command;
-    use std::sync::{Mutex, MutexGuard, OnceLock};
-    use std::thread;
-    use std::time::{Duration, SystemTime, UNIX_EPOCH};
-    use tools::GlobalToolRegistry;
-
-    fn registry_with_plugin_tool() -> GlobalToolRegistry {
-        GlobalToolRegistry::with_plugin_tools(vec![PluginTool::new(
-            "plugin-demo@external",
-            "plugin-demo",
-            PluginToolDefinition {
-                name: "plugin_echo".to_string(),
-                description: Some("Echo plugin payload".to_string()),
-                input_schema: json!({
-                    "type": "object",
-                    "properties": {
-                        "message": { "type": "string" }
-                    },
-                    "required": ["message"],
-                    "additionalProperties": false
-                }),
-            },
-            "echo".to_string(),
-            Vec::new(),
-            PluginToolPermission::WorkspaceWrite,
-            None,
-        )])
-        .expect("plugin tool registry should build")
-    }
-
-    #[test]
-    fn opaque_provider_wrapper_surfaces_failure_class_session_and_trace() {
-        let error = ApiError::Api {
-            status: "500".parse().expect("status"),
-            error_type: Some("api_error".to_string()),
-            message: Some(
-                "Something went wrong while processing your request. Please try again, or use /new to start a fresh session."
-                    .to_string(),
-            ),
-            request_id: Some("req_jobdori_789".to_string()),
-            body: String::new(),
-            retryable: true,
-        };
-
-        let rendered = format_user_visible_api_error("session-issue-22", &error);
-        assert!(rendered.contains("provider_internal"));
-        assert!(rendered.contains("session session-issue-22"));
-        assert!(rendered.contains("trace req_jobdori_789"));
-    }
-
-    #[test]
-    fn retry_exhaustion_uses_retry_failure_class_for_generic_provider_wrapper() {
-        let error = ApiError::RetriesExhausted {
-            attempts: 3,
-            last_error: Box::new(ApiError::Api {
-                status: "502".parse().expect("status"),
-                error_type: Some("api_error".to_string()),
-                message: Some(
-                    "Something went wrong while processing your request. Please try again, or use /new to start a fresh session."
-                        .to_string(),
-                ),
-                request_id: Some("req_jobdori_790".to_string()),
-                body: String::new(),
-                retryable: true,
-            }),
-        };
-
-        let rendered = format_user_visible_api_error("session-issue-22", &error);
-        assert!(rendered.contains("provider_retry_exhausted"), "{rendered}");
-        assert!(rendered.contains("session session-issue-22"));
-        assert!(rendered.contains("trace req_jobdori_790"));
-    }
-
-    #[test]
-    fn context_window_preflight_errors_render_recovery_steps() {
-        let error = ApiError::ContextWindowExceeded {
-            model: "claude-sonnet-4-6".to_string(),
-            estimated_input_tokens: 182_000,
-            requested_output_tokens: 64_000,
-            estimated_total_tokens: 246_000,
-            context_window_tokens: 200_000,
-        };
-
-        let rendered = format_user_visible_api_error("session-issue-32", &error);
-        assert!(rendered.contains("Context window blocked"), "{rendered}");
-        assert!(rendered.contains("context_window_blocked"), "{rendered}");
-        assert!(
-            rendered.contains("Session          session-issue-32"),
-            "{rendered}"
-        );
-        assert!(
-            rendered.contains("Model            claude-sonnet-4-6"),
-            "{rendered}"
-        );
-        assert!(
-            rendered.contains("Input estimate   ~182000 tokens (heuristic)"),
-            "{rendered}"
-        );
-        assert!(
-            rendered.contains("Total estimate   ~246000 tokens (heuristic)"),
-            "{rendered}"
-        );
-        assert!(rendered.contains("Compact          /compact"), "{rendered}");
-        assert!(
-            rendered.contains("Resume compact   claw --resume session-issue-32 /compact"),
-            "{rendered}"
-        );
-        assert!(
-            rendered.contains("Fresh session    /clear --confirm"),
-            "{rendered}"
-        );
-        assert!(rendered.contains("Reduce scope"), "{rendered}");
-        assert!(rendered.contains("Retry            rerun"), "{rendered}");
-    }
-
-    #[test]
-    fn provider_context_window_errors_are_reframed_with_same_guidance() {
-        let error = ApiError::Api {
-            status: "400".parse().expect("status"),
-            error_type: Some("invalid_request_error".to_string()),
-            message: Some(
-                "This model's maximum context length is 200000 tokens, but your request used 230000 tokens."
-                    .to_string(),
-            ),
-            request_id: Some("req_ctx_456".to_string()),
-            body: String::new(),
-            retryable: false,
-        };
-
-        let rendered = format_user_visible_api_error("session-issue-32", &error);
-        assert!(rendered.contains("context_window_blocked"), "{rendered}");
-        assert!(
-            rendered.contains("Trace            req_ctx_456"),
-            "{rendered}"
-        );
-        assert!(
-            rendered
-                .contains("Detail           This model's maximum context length is 200000 tokens"),
-            "{rendered}"
-        );
-        assert!(rendered.contains("Compact          /compact"), "{rendered}");
-        assert!(
-            rendered.contains("Fresh session    /clear --confirm"),
-            "{rendered}"
-        );
-    }
-
-    #[test]
-    fn retry_wrapped_context_window_errors_keep_recovery_guidance() {
-        let error = ApiError::RetriesExhausted {
-            attempts: 2,
-            last_error: Box::new(ApiError::Api {
-                status: "413".parse().expect("status"),
-                error_type: Some("invalid_request_error".to_string()),
-                message: Some("Request is too large for this model's context window.".to_string()),
-                request_id: Some("req_ctx_retry_789".to_string()),
-                body: String::new(),
-                retryable: false,
-            }),
-        };
-
-        let rendered = format_user_visible_api_error("session-issue-32", &error);
-        assert!(rendered.contains("Context window blocked"), "{rendered}");
-        assert!(rendered.contains("context_window_blocked"), "{rendered}");
-        assert!(
-            rendered.contains("Trace            req_ctx_retry_789"),
-            "{rendered}"
-        );
-        assert!(
-            rendered
-                .contains("Detail           Request is too large for this model's context window."),
-            "{rendered}"
-        );
-        assert!(rendered.contains("Compact          /compact"), "{rendered}");
-        assert!(
-            rendered.contains("Resume compact   claw --resume session-issue-32 /compact"),
-            "{rendered}"
-        );
-    }
-
-    fn temp_dir() -> PathBuf {
-        use std::sync::atomic::{AtomicU64, Ordering};
-
-        static COUNTER: AtomicU64 = AtomicU64::new(0);
-        let nanos = SystemTime::now()
-            .duration_since(UNIX_EPOCH)
-            .expect("time should be after epoch")
-            .as_nanos();
-        let unique = COUNTER.fetch_add(1, Ordering::Relaxed);
-        std::env::temp_dir().join(format!("rusty-claude-cli-{nanos}-{unique}"))
-    }
-
-    fn git(args: &[&str], cwd: &Path) {
-        let status = Command::new("git")
-            .args(args)
-            .current_dir(cwd)
-            .status()
-            .expect("git command should run");
-        assert!(
-            status.success(),
-            "git command failed: git {}",
-            args.join(" ")
-        );
-    }
-
-    fn env_lock() -> MutexGuard<'static, ()> {
-        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-        LOCK.get_or_init(|| Mutex::new(()))
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner)
-    }
-
-    fn sample_oauth_config(token_url: String) -> OAuthConfig {
-        OAuthConfig {
-            client_id: "runtime-client".to_string(),
-            authorize_url: "https://console.test/oauth/authorize".to_string(),
-            token_url,
-            callback_port: Some(4545),
-            manual_redirect_url: Some("https://console.test/oauth/callback".to_string()),
-            scopes: vec!["org:create_api_key".to_string(), "user:profile".to_string()],
-        }
-    }
-
-    fn spawn_token_server(response_body: &'static str) -> String {
-        let listener = TcpListener::bind("127.0.0.1:0").expect("bind listener");
-        let address = listener.local_addr().expect("local addr");
-        thread::spawn(move || {
-            let (mut stream, _) = listener.accept().expect("accept connection");
-            let mut buffer = [0_u8; 4096];
-            let _ = stream.read(&mut buffer).expect("read request");
-            let response = format!(
-                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\ncontent-length: {}\r\n\r\n{}",
-                response_body.len(),
-                response_body
-            );
-            stream
-                .write_all(response.as_bytes())
-                .expect("write response");
-        });
-        format!("http://{address}/oauth/token")
-    }
-
-    fn with_current_dir<T>(cwd: &Path, f: impl FnOnce() -> T) -> T {
-        let _guard = cwd_lock()
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let previous = std::env::current_dir().expect("cwd should load");
-        std::env::set_current_dir(cwd).expect("cwd should change");
-        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(f));
-        std::env::set_current_dir(previous).expect("cwd should restore");
-        match result {
-            Ok(value) => value,
-            Err(payload) => std::panic::resume_unwind(payload),
-        }
-    }
-
-    fn write_plugin_fixture(root: &Path, name: &str, include_hooks: bool, include_lifecycle: bool) {
-        fs::create_dir_all(root.join(".claude-plugin")).expect("manifest dir");
-        if include_hooks {
-            fs::create_dir_all(root.join("hooks")).expect("hooks dir");
-            fs::write(
-                root.join("hooks").join("pre.sh"),
-                "#!/bin/sh\nprintf 'plugin pre hook'\n",
-            )
-            .expect("write hook");
-        }
-        if include_lifecycle {
-            fs::create_dir_all(root.join("lifecycle")).expect("lifecycle dir");
-            fs::write(
-                root.join("lifecycle").join("init.sh"),
-                "#!/bin/sh\nprintf 'init\\n' >> lifecycle.log\n",
-            )
-            .expect("write init lifecycle");
-            fs::write(
-                root.join("lifecycle").join("shutdown.sh"),
-                "#!/bin/sh\nprintf 'shutdown\\n' >> lifecycle.log\n",
-            )
-            .expect("write shutdown lifecycle");
-        }
-
-        let hooks = if include_hooks {
-            ",\n  \"hooks\": {\n    \"PreToolUse\": [\"./hooks/pre.sh\"]\n  }"
-        } else {
-            ""
-        };
-        let lifecycle = if include_lifecycle {
-            ",\n  \"lifecycle\": {\n    \"Init\": [\"./lifecycle/init.sh\"],\n    \"Shutdown\": [\"./lifecycle/shutdown.sh\"]\n  }"
-        } else {
-            ""
-        };
-        fs::write(
-            root.join(".claude-plugin").join("plugin.json"),
-            format!(
-                "{{\n  \"name\": \"{name}\",\n  \"version\": \"1.0.0\",\n  \"description\": \"runtime plugin fixture\"{hooks}{lifecycle}\n}}"
-            ),
-        )
-        .expect("write plugin manifest");
-    }
-    #[test]
-    fn defaults_to_repl_when_no_args() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        assert_eq!(
-            parse_args(&[]).expect("args should parse"),
-            CliAction::Repl {
-                model: DEFAULT_MODEL.to_string(),
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn default_permission_mode_uses_project_config_when_env_is_unset() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        let cwd = root.join("project");
-        let config_home = root.join("config-home");
-        std::fs::create_dir_all(cwd.join(".claw")).expect("project config dir should exist");
-        std::fs::create_dir_all(&config_home).expect("config home should exist");
-        std::fs::write(
-            cwd.join(".claw").join("settings.json"),
-            r#"{"permissionMode":"acceptEdits"}"#,
-        )
-        .expect("project config should write");
-
-        let original_config_home = std::env::var("CLAW_CONFIG_HOME").ok();
-        let original_permission_mode = std::env::var("RUSTY_CLAUDE_PERMISSION_MODE").ok();
-        std::env::set_var("CLAW_CONFIG_HOME", &config_home);
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-
-        let resolved = with_current_dir(&cwd, super::default_permission_mode);
-
-        match original_config_home {
-            Some(value) => std::env::set_var("CLAW_CONFIG_HOME", value),
-            None => std::env::remove_var("CLAW_CONFIG_HOME"),
-        }
-        match original_permission_mode {
-            Some(value) => std::env::set_var("RUSTY_CLAUDE_PERMISSION_MODE", value),
-            None => std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE"),
-        }
-        std::fs::remove_dir_all(root).expect("temp config root should clean up");
-
-        assert_eq!(resolved, PermissionMode::WorkspaceWrite);
-    }
-
-    #[test]
-    fn env_permission_mode_overrides_project_config_default() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        let cwd = root.join("project");
-        let config_home = root.join("config-home");
-        std::fs::create_dir_all(cwd.join(".claw")).expect("project config dir should exist");
-        std::fs::create_dir_all(&config_home).expect("config home should exist");
-        std::fs::write(
-            cwd.join(".claw").join("settings.json"),
-            r#"{"permissionMode":"acceptEdits"}"#,
-        )
-        .expect("project config should write");
-
-        let original_config_home = std::env::var("CLAW_CONFIG_HOME").ok();
-        let original_permission_mode = std::env::var("RUSTY_CLAUDE_PERMISSION_MODE").ok();
-        std::env::set_var("CLAW_CONFIG_HOME", &config_home);
-        std::env::set_var("RUSTY_CLAUDE_PERMISSION_MODE", "read-only");
-
-        let resolved = with_current_dir(&cwd, super::default_permission_mode);
-
-        match original_config_home {
-            Some(value) => std::env::set_var("CLAW_CONFIG_HOME", value),
-            None => std::env::remove_var("CLAW_CONFIG_HOME"),
-        }
-        match original_permission_mode {
-            Some(value) => std::env::set_var("RUSTY_CLAUDE_PERMISSION_MODE", value),
-            None => std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE"),
-        }
-        std::fs::remove_dir_all(root).expect("temp config root should clean up");
-
-        assert_eq!(resolved, PermissionMode::ReadOnly);
-    }
-
-    #[test]
-    fn load_runtime_oauth_config_for_returns_none_without_project_config() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        std::fs::create_dir_all(&root).expect("workspace should exist");
-
-        let oauth = super::load_runtime_oauth_config_for(&root)
-            .expect("loading config should succeed when files are absent");
-
-        std::fs::remove_dir_all(root).expect("temp workspace should clean up");
-
-        assert_eq!(oauth, None);
-    }
-
-    #[test]
-    fn resolve_cli_auth_source_uses_default_oauth_when_runtime_config_is_missing() {
-        let _guard = env_lock();
-        let workspace = temp_dir();
-        let config_home = temp_dir();
-        std::fs::create_dir_all(&workspace).expect("workspace should exist");
-        std::fs::create_dir_all(&config_home).expect("config home should exist");
-
-        let original_config_home = std::env::var("CLAW_CONFIG_HOME").ok();
-        let original_api_key = std::env::var("ANTHROPIC_API_KEY").ok();
-        let original_auth_token = std::env::var("ANTHROPIC_AUTH_TOKEN").ok();
-        std::env::set_var("CLAW_CONFIG_HOME", &config_home);
-        std::env::remove_var("ANTHROPIC_API_KEY");
-        std::env::remove_var("ANTHROPIC_AUTH_TOKEN");
-
-        save_oauth_credentials(&runtime::OAuthTokenSet {
-            access_token: "expired-access-token".to_string(),
-            refresh_token: Some("refresh-token".to_string()),
-            expires_at: Some(0),
-            scopes: vec!["org:create_api_key".to_string(), "user:profile".to_string()],
-        })
-        .expect("save expired oauth credentials");
-
-        let token_url = spawn_token_server(
-            r#"{"access_token":"refreshed-access-token","refresh_token":"refreshed-refresh-token","expires_at":4102444800,"scopes":["org:create_api_key","user:profile"]}"#,
-        );
-
-        let auth =
-            super::resolve_cli_auth_source_for_cwd(&workspace, || sample_oauth_config(token_url))
-                .expect("expired saved oauth should refresh via default config");
-
-        let stored = load_oauth_credentials()
-            .expect("load stored credentials")
-            .expect("stored credentials should exist");
-
-        match original_config_home {
-            Some(value) => std::env::set_var("CLAW_CONFIG_HOME", value),
-            None => std::env::remove_var("CLAW_CONFIG_HOME"),
-        }
-        match original_api_key {
-            Some(value) => std::env::set_var("ANTHROPIC_API_KEY", value),
-            None => std::env::remove_var("ANTHROPIC_API_KEY"),
-        }
-        match original_auth_token {
-            Some(value) => std::env::set_var("ANTHROPIC_AUTH_TOKEN", value),
-            None => std::env::remove_var("ANTHROPIC_AUTH_TOKEN"),
-        }
-        std::fs::remove_dir_all(workspace).expect("temp workspace should clean up");
-        std::fs::remove_dir_all(config_home).expect("temp config home should clean up");
-
-        assert_eq!(auth.bearer_token(), Some("refreshed-access-token"));
-        assert_eq!(stored.access_token, "refreshed-access-token");
-        assert_eq!(
-            stored.refresh_token.as_deref(),
-            Some("refreshed-refresh-token")
-        );
-    }
-
-    #[test]
-    fn parses_prompt_subcommand() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec![
-            "prompt".to_string(),
-            "hello".to_string(),
-            "world".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::Prompt {
-                prompt: "hello world".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn merge_prompt_with_stdin_returns_prompt_unchanged_when_no_pipe() {
-        // given
-        let prompt = "Review this";
-
-        // when
-        let merged = merge_prompt_with_stdin(prompt, None);
-
-        // then
-        assert_eq!(merged, "Review this");
-    }
-
-    #[test]
-    fn merge_prompt_with_stdin_ignores_whitespace_only_pipe() {
-        // given
-        let prompt = "Review this";
-        let piped = "   \n\t\n  ";
-
-        // when
-        let merged = merge_prompt_with_stdin(prompt, Some(piped));
-
-        // then
-        assert_eq!(merged, "Review this");
-    }
-
-    #[test]
-    fn merge_prompt_with_stdin_appends_piped_content_as_context() {
-        // given
-        let prompt = "Review this";
-        let piped = "fn main() { println!(\"hi\"); }\n";
-
-        // when
-        let merged = merge_prompt_with_stdin(prompt, Some(piped));
-
-        // then
-        assert_eq!(merged, "Review this\n\nfn main() { println!(\"hi\"); }");
-    }
-
-    #[test]
-    fn merge_prompt_with_stdin_trims_surrounding_whitespace_on_pipe() {
-        // given
-        let prompt = "Summarize";
-        let piped = "\n\n  some notes  \n\n";
-
-        // when
-        let merged = merge_prompt_with_stdin(prompt, Some(piped));
-
-        // then
-        assert_eq!(merged, "Summarize\n\nsome notes");
-    }
-
-    #[test]
-    fn merge_prompt_with_stdin_returns_pipe_when_prompt_is_empty() {
-        // given
-        let prompt = "";
-        let piped = "standalone body";
-
-        // when
-        let merged = merge_prompt_with_stdin(prompt, Some(piped));
-
-        // then
-        assert_eq!(merged, "standalone body");
-    }
-
-    #[test]
-    fn parses_bare_prompt_and_json_output_flag() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec![
-            "--output-format=json".to_string(),
-            "--model".to_string(),
-            "claude-opus".to_string(),
-            "explain".to_string(),
-            "this".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::Prompt {
-                prompt: "explain this".to_string(),
-                model: "claude-opus".to_string(),
-                output_format: CliOutputFormat::Json,
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_compact_flag_for_prompt_mode() {
-        // given a bare prompt invocation that includes the --compact flag
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec![
-            "--compact".to_string(),
-            "summarize".to_string(),
-            "this".to_string(),
-        ];
-
-        // when parse_args interprets the flag
-        let parsed = parse_args(&args).expect("args should parse");
-
-        // then compact mode is propagated and other defaults stay unchanged
-        assert_eq!(
-            parsed,
-            CliAction::Prompt {
-                prompt: "summarize this".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                compact: true,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn prompt_subcommand_defaults_compact_to_false() {
-        // given a `prompt` subcommand invocation without --compact
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec!["prompt".to_string(), "hello".to_string()];
-
-        // when parse_args runs
-        let parsed = parse_args(&args).expect("args should parse");
-
-        // then compact stays false (opt-in flag)
-        match parsed {
-            CliAction::Prompt { compact, .. } => assert!(!compact),
-            other => panic!("expected Prompt action, got {other:?}"),
-        }
-    }
-
-    #[test]
-    fn resolves_model_aliases_in_args() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec![
-            "--model".to_string(),
-            "opus".to_string(),
-            "explain".to_string(),
-            "this".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::Prompt {
-                prompt: "explain this".to_string(),
-                model: "claude-opus-4-6".to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn resolves_known_model_aliases() {
-        assert_eq!(resolve_model_alias("opus"), "claude-opus-4-6");
-        assert_eq!(resolve_model_alias("sonnet"), "claude-sonnet-4-6");
-        assert_eq!(resolve_model_alias("haiku"), "claude-haiku-4-5-20251213");
-        assert_eq!(resolve_model_alias("claude-opus"), "claude-opus");
-    }
-
-    #[test]
-    fn user_defined_aliases_resolve_before_provider_dispatch() {
-        // given
-        let _guard = env_lock();
-        let root = temp_dir();
-        let cwd = root.join("project");
-        let config_home = root.join("config-home");
-        std::fs::create_dir_all(cwd.join(".claw")).expect("project config dir should exist");
-        std::fs::create_dir_all(&config_home).expect("config home should exist");
-        std::fs::write(
-            cwd.join(".claw").join("settings.json"),
-            r#"{"aliases":{"fast":"claude-haiku-4-5-20251213","smart":"opus","cheap":"grok-3-mini"}}"#,
-        )
-        .expect("project config should write");
-
-        let original_config_home = std::env::var("CLAW_CONFIG_HOME").ok();
-        std::env::set_var("CLAW_CONFIG_HOME", &config_home);
-
-        // when
-        let direct = with_current_dir(&cwd, || resolve_model_alias_with_config("fast"));
-        let chained = with_current_dir(&cwd, || resolve_model_alias_with_config("smart"));
-        let cross_provider = with_current_dir(&cwd, || resolve_model_alias_with_config("cheap"));
-        let unknown = with_current_dir(&cwd, || resolve_model_alias_with_config("unknown-model"));
-        let builtin = with_current_dir(&cwd, || resolve_model_alias_with_config("haiku"));
-
-        match original_config_home {
-            Some(value) => std::env::set_var("CLAW_CONFIG_HOME", value),
-            None => std::env::remove_var("CLAW_CONFIG_HOME"),
-        }
-        std::fs::remove_dir_all(root).expect("temp config root should clean up");
-
-        // then
-        assert_eq!(direct, "claude-haiku-4-5-20251213");
-        assert_eq!(chained, "claude-opus-4-6");
-        assert_eq!(cross_provider, "grok-3-mini");
-        assert_eq!(unknown, "unknown-model");
-        assert_eq!(builtin, "claude-haiku-4-5-20251213");
-    }
-
-    #[test]
-    fn parses_version_flags_without_initializing_prompt_mode() {
-        assert_eq!(
-            parse_args(&["--version".to_string()]).expect("args should parse"),
-            CliAction::Version {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["-V".to_string()]).expect("args should parse"),
-            CliAction::Version {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_permission_mode_flag() {
-        let args = vec!["--permission-mode=read-only".to_string()];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::Repl {
-                model: DEFAULT_MODEL.to_string(),
-                allowed_tools: None,
-                permission_mode: PermissionMode::ReadOnly,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn dangerously_skip_permissions_flag_forces_danger_full_access_in_repl() {
-        let _guard = env_lock();
-        std::env::set_var("RUSTY_CLAUDE_PERMISSION_MODE", "read-only");
-        let args = vec!["--dangerously-skip-permissions".to_string()];
-        let parsed = parse_args(&args).expect("args should parse");
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-
-        assert_eq!(
-            parsed,
-            CliAction::Repl {
-                model: DEFAULT_MODEL.to_string(),
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn dangerously_skip_permissions_flag_applies_to_prompt_subcommand() {
-        let _guard = env_lock();
-        std::env::set_var("RUSTY_CLAUDE_PERMISSION_MODE", "read-only");
-        let args = vec![
-            "--dangerously-skip-permissions".to_string(),
-            "prompt".to_string(),
-            "do".to_string(),
-            "the".to_string(),
-            "thing".to_string(),
-        ];
-        let parsed = parse_args(&args).expect("args should parse");
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-
-        assert_eq!(
-            parsed,
-            CliAction::Prompt {
-                prompt: "do the thing".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: PermissionMode::DangerFullAccess,
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_allowed_tools_flags_with_aliases_and_lists() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec![
-            "--allowedTools".to_string(),
-            "read,glob".to_string(),
-            "--allowed-tools=write_file".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::Repl {
-                model: DEFAULT_MODEL.to_string(),
-                allowed_tools: Some(
-                    ["glob_search", "read_file", "write_file"]
-                        .into_iter()
-                        .map(str::to_string)
-                        .collect()
-                ),
-                permission_mode: PermissionMode::DangerFullAccess,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn rejects_unknown_allowed_tools() {
-        let error = parse_args(&["--allowedTools".to_string(), "teleport".to_string()])
-            .expect_err("tool should be rejected");
-        assert!(error.contains("unsupported tool in --allowedTools: teleport"));
-    }
-
-    #[test]
-    fn parses_system_prompt_options() {
-        let args = vec![
-            "system-prompt".to_string(),
-            "--cwd".to_string(),
-            "/tmp/project".to_string(),
-            "--date".to_string(),
-            "2026-04-01".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::PrintSystemPrompt {
-                cwd: PathBuf::from("/tmp/project"),
-                date: "2026-04-01".to_string(),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_login_and_logout_subcommands() {
-        assert_eq!(
-            parse_args(&["login".to_string()]).expect("login should parse"),
-            CliAction::Login {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["logout".to_string()]).expect("logout should parse"),
-            CliAction::Logout {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["doctor".to_string()]).expect("doctor should parse"),
-            CliAction::Doctor {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["state".to_string()]).expect("state should parse"),
-            CliAction::State {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&[
-                "state".to_string(),
-                "--output-format".to_string(),
-                "json".to_string()
-            ])
-            .expect("state --output-format json should parse"),
-            CliAction::State {
-                output_format: CliOutputFormat::Json,
-            }
-        );
-        assert_eq!(
-            parse_args(&["init".to_string()]).expect("init should parse"),
-            CliAction::Init {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["agents".to_string()]).expect("agents should parse"),
-            CliAction::Agents {
-                args: None,
-                output_format: CliOutputFormat::Text
-            }
-        );
-        assert_eq!(
-            parse_args(&["mcp".to_string()]).expect("mcp should parse"),
-            CliAction::Mcp {
-                args: None,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["skills".to_string()]).expect("skills should parse"),
-            CliAction::Skills {
-                args: None,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&[
-                "skills".to_string(),
-                "help".to_string(),
-                "overview".to_string()
-            ])
-            .expect("skills help overview should invoke"),
-            CliAction::Prompt {
-                prompt: "$help overview".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: crate::default_permission_mode(),
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-        assert_eq!(
-            parse_args(&["agents".to_string(), "--help".to_string()])
-                .expect("agents help should parse"),
-            CliAction::Agents {
-                args: Some("--help".to_string()),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn local_command_help_flags_stay_on_the_local_parser_path() {
-        assert_eq!(
-            parse_args(&["status".to_string(), "--help".to_string()])
-                .expect("status help should parse"),
-            CliAction::HelpTopic(LocalHelpTopic::Status)
-        );
-        assert_eq!(
-            parse_args(&["sandbox".to_string(), "-h".to_string()])
-                .expect("sandbox help should parse"),
-            CliAction::HelpTopic(LocalHelpTopic::Sandbox)
-        );
-        assert_eq!(
-            parse_args(&["doctor".to_string(), "--help".to_string()])
-                .expect("doctor help should parse"),
-            CliAction::HelpTopic(LocalHelpTopic::Doctor)
-        );
-    }
-
-    #[test]
-    fn parses_single_word_command_aliases_without_falling_back_to_prompt_mode() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        assert_eq!(
-            parse_args(&["help".to_string()]).expect("help should parse"),
-            CliAction::Help {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["version".to_string()]).expect("version should parse"),
-            CliAction::Version {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["status".to_string()]).expect("status should parse"),
-            CliAction::Status {
-                model: DEFAULT_MODEL.to_string(),
-                permission_mode: PermissionMode::DangerFullAccess,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["sandbox".to_string()]).expect("sandbox should parse"),
-            CliAction::Sandbox {
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_bare_export_subcommand_targeting_latest_session() {
-        // given
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        let args = vec!["export".to_string()];
-
-        // when
-        let parsed = parse_args(&args).expect("bare export should parse");
-
-        // then
-        assert_eq!(
-            parsed,
-            CliAction::Export {
-                session_reference: LATEST_SESSION_REFERENCE.to_string(),
-                output_path: None,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_export_subcommand_with_positional_output_path() {
-        // given
-        let args = vec!["export".to_string(), "conversation.md".to_string()];
-
-        // when
-        let parsed = parse_args(&args).expect("export with path should parse");
-
-        // then
-        assert_eq!(
-            parsed,
-            CliAction::Export {
-                session_reference: LATEST_SESSION_REFERENCE.to_string(),
-                output_path: Some(PathBuf::from("conversation.md")),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_export_subcommand_with_session_and_output_flags() {
-        // given
-        let args = vec![
-            "export".to_string(),
-            "--session".to_string(),
-            "session-alpha".to_string(),
-            "--output".to_string(),
-            "/tmp/share.md".to_string(),
-        ];
-
-        // when
-        let parsed = parse_args(&args).expect("export flags should parse");
-
-        // then
-        assert_eq!(
-            parsed,
-            CliAction::Export {
-                session_reference: "session-alpha".to_string(),
-                output_path: Some(PathBuf::from("/tmp/share.md")),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_export_subcommand_with_inline_flag_values() {
-        // given
-        let args = vec![
-            "export".to_string(),
-            "--session=session-beta".to_string(),
-            "--output=/tmp/beta.md".to_string(),
-        ];
-
-        // when
-        let parsed = parse_args(&args).expect("export inline flags should parse");
-
-        // then
-        assert_eq!(
-            parsed,
-            CliAction::Export {
-                session_reference: "session-beta".to_string(),
-                output_path: Some(PathBuf::from("/tmp/beta.md")),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_export_subcommand_with_json_output_format() {
-        // given
-        let args = vec![
-            "--output-format=json".to_string(),
-            "export".to_string(),
-            "/tmp/notes.md".to_string(),
-        ];
-
-        // when
-        let parsed = parse_args(&args).expect("json export should parse");
-
-        // then
-        assert_eq!(
-            parsed,
-            CliAction::Export {
-                session_reference: LATEST_SESSION_REFERENCE.to_string(),
-                output_path: Some(PathBuf::from("/tmp/notes.md")),
-                output_format: CliOutputFormat::Json,
-            }
-        );
-    }
-
-    #[test]
-    fn rejects_unknown_export_options_with_helpful_message() {
-        // given
-        let args = vec!["export".to_string(), "--bogus".to_string()];
-
-        // when
-        let error = parse_args(&args).expect_err("unknown export option should fail");
-
-        // then
-        assert!(error.contains("unknown export option: --bogus"));
-    }
-
-    #[test]
-    fn rejects_export_with_extra_positional_after_path() {
-        // given
-        let args = vec![
-            "export".to_string(),
-            "first.md".to_string(),
-            "second.md".to_string(),
-        ];
-
-        // when
-        let error = parse_args(&args).expect_err("multiple positionals should fail");
-
-        // then
-        assert!(error.contains("unexpected export argument: second.md"));
-    }
-
-    #[test]
-    fn parse_export_args_helper_defaults_to_latest_reference_and_no_output() {
-        // given
-        let args: Vec<String> = vec![];
-
-        // when
-        let parsed = parse_export_args(&args, CliOutputFormat::Text)
-            .expect("empty export args should parse");
-
-        // then
-        assert_eq!(
-            parsed,
-            CliAction::Export {
-                session_reference: LATEST_SESSION_REFERENCE.to_string(),
-                output_path: None,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn render_session_markdown_includes_header_and_summarized_tool_calls() {
-        // given
-        let mut session = Session::new();
-        session.session_id = "session-export-test".to_string();
-        session.messages = vec![
-            ConversationMessage::user_text("How do I list files?"),
-            ConversationMessage::assistant(vec![
-                ContentBlock::Text {
-                    text: "I'll run a tool.".to_string(),
-                },
-                ContentBlock::ToolUse {
-                    id: "toolu_abcdefghijklmnop".to_string(),
-                    name: "bash".to_string(),
-                    input: r#"{"command":"ls -la"}"#.to_string(),
-                },
-            ]),
-            ConversationMessage {
-                role: MessageRole::Tool,
-                blocks: vec![ContentBlock::ToolResult {
-                    tool_use_id: "toolu_abcdefghijklmnop".to_string(),
-                    tool_name: "bash".to_string(),
-                    output: "total 8\ndrwxr-xr-x  2 user staff   64 Apr  7 12:00 .".to_string(),
-                    is_error: false,
-                }],
-                usage: None,
-            },
-        ];
-
-        // when
-        let markdown = render_session_markdown(
-            &session,
-            "session-export-test",
-            std::path::Path::new("/tmp/sessions/session-export-test.jsonl"),
-        );
-
-        // then
-        assert!(markdown.starts_with("# Conversation Export"));
-        assert!(markdown.contains("- **Session**: `session-export-test`"));
-        assert!(markdown.contains("- **Messages**: 3"));
-        assert!(markdown.contains("## 1. User"));
-        assert!(markdown.contains("How do I list files?"));
-        assert!(markdown.contains("## 2. Assistant"));
-        assert!(markdown.contains("**Tool call** `bash`"));
-        assert!(markdown.contains("toolu_abcdef…"));
-        assert!(markdown.contains("ls -la"));
-        assert!(markdown.contains("## 3. Tool"));
-        assert!(markdown.contains("**Tool result** `bash`"));
-        assert!(markdown.contains("ok"));
-        assert!(markdown.contains("total 8"));
-    }
-
-    #[test]
-    fn render_session_markdown_marks_tool_errors_and_skips_empty_summaries() {
-        // given
-        let mut session = Session::new();
-        session.session_id = "errs".to_string();
-        session.messages = vec![ConversationMessage {
-            role: MessageRole::Tool,
-            blocks: vec![ContentBlock::ToolResult {
-                tool_use_id: "short".to_string(),
-                tool_name: "read_file".to_string(),
-                output: "   ".to_string(),
-                is_error: true,
-            }],
-            usage: None,
-        }];
-
-        // when
-        let markdown =
-            render_session_markdown(&session, "errs", std::path::Path::new("errs.jsonl"));
-
-        // then
-        assert!(markdown.contains("**Tool result** `read_file` _(id `short`, error)_"));
-        // an empty summary should not produce a stray blockquote line
-        assert!(!markdown.contains("> \n"));
-    }
-
-    #[test]
-    fn summarize_tool_payload_for_markdown_compacts_json_and_truncates_overflow() {
-        // given
-        let json_payload = r#"{
-            "command":   "ls -la",
-            "cwd": "/tmp"
-        }"#;
-        let long_payload = "a".repeat(600);
-
-        // when
-        let compacted = summarize_tool_payload_for_markdown(json_payload);
-        let truncated = summarize_tool_payload_for_markdown(&long_payload);
-
-        // then
-        assert_eq!(compacted, r#"{"command":"ls -la","cwd":"/tmp"}"#);
-        assert!(truncated.ends_with('…'));
-        assert!(truncated.chars().count() <= 281);
-    }
-
-    #[test]
-    fn short_tool_id_truncates_long_identifiers_with_ellipsis() {
-        // given
-        let long = "toolu_01ABCDEFGHIJKLMN";
-        let short = "tool_1";
-
-        // when
-        let trimmed_long = short_tool_id(long);
-        let trimmed_short = short_tool_id(short);
-
-        // then
-        assert_eq!(trimmed_long, "toolu_01ABCD…");
-        assert_eq!(trimmed_short, "tool_1");
-    }
-
-    #[test]
-    fn parses_json_output_for_mcp_and_skills_commands() {
-        assert_eq!(
-            parse_args(&["--output-format=json".to_string(), "mcp".to_string()])
-                .expect("json mcp should parse"),
-            CliAction::Mcp {
-                args: None,
-                output_format: CliOutputFormat::Json,
-            }
-        );
-        assert_eq!(
-            parse_args(&[
-                "--output-format=json".to_string(),
-                "/skills".to_string(),
-                "help".to_string(),
-            ])
-            .expect("json /skills help should parse"),
-            CliAction::Skills {
-                args: Some("help".to_string()),
-                output_format: CliOutputFormat::Json,
-            }
-        );
-    }
-
-    #[test]
-    fn single_word_slash_command_names_return_guidance_instead_of_hitting_prompt_mode() {
-        let error = parse_args(&["cost".to_string()]).expect_err("cost should return guidance");
-        assert!(error.contains("slash command"));
-        assert!(error.contains("/cost"));
-    }
-
-    #[test]
-    fn multi_word_prompt_still_uses_shorthand_prompt_mode() {
-        let _guard = env_lock();
-        std::env::remove_var("RUSTY_CLAUDE_PERMISSION_MODE");
-        // Input is ["help", "me", "debug"] so the joined prompt shorthand
-        // must be "help me debug". A previous batch accidentally rewrote
-        // the expected string to "$help overview" (copy-paste slip).
-        assert_eq!(
-            parse_args(&["help".to_string(), "me".to_string(), "debug".to_string()])
-                .expect("prompt shorthand should still work"),
-            CliAction::Prompt {
-                prompt: "help me debug".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: crate::default_permission_mode(),
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_direct_agents_mcp_and_skills_slash_commands() {
-        assert_eq!(
-            parse_args(&["/agents".to_string()]).expect("/agents should parse"),
-            CliAction::Agents {
-                args: None,
-                output_format: CliOutputFormat::Text
-            }
-        );
-        assert_eq!(
-            parse_args(&["/mcp".to_string(), "show".to_string(), "demo".to_string()])
-                .expect("/mcp show demo should parse"),
-            CliAction::Mcp {
-                args: Some("show demo".to_string()),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["/skills".to_string()]).expect("/skills should parse"),
-            CliAction::Skills {
-                args: None,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["/skill".to_string()]).expect("/skill should parse"),
-            CliAction::Skills {
-                args: None,
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["/skills".to_string(), "help".to_string()])
-                .expect("/skills help should parse"),
-            CliAction::Skills {
-                args: Some("help".to_string()),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["/skill".to_string(), "list".to_string()])
-                .expect("/skill list should parse"),
-            CliAction::Skills {
-                args: Some("list".to_string()),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&[
-                "/skills".to_string(),
-                "help".to_string(),
-                "overview".to_string()
-            ])
-            .expect("/skills help overview should invoke"),
-            CliAction::Prompt {
-                prompt: "$help overview".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: crate::default_permission_mode(),
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-        assert_eq!(
-            parse_args(&[
-                "/skills".to_string(),
-                "install".to_string(),
-                "./fixtures/help-skill".to_string(),
-            ])
-            .expect("/skills install should parse"),
-            CliAction::Skills {
-                args: Some("install ./fixtures/help-skill".to_string()),
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["/skills".to_string(), "/test".to_string()])
-                .expect("/skills /test should normalize to a single skill prompt prefix"),
-            CliAction::Prompt {
-                prompt: "$test".to_string(),
-                model: DEFAULT_MODEL.to_string(),
-                output_format: CliOutputFormat::Text,
-                allowed_tools: None,
-                permission_mode: crate::default_permission_mode(),
-                compact: false,
-                base_commit: None,
-                reasoning_effort: None,
-            }
-        );
-        let error = parse_args(&["/status".to_string()])
-            .expect_err("/status should remain REPL-only when invoked directly");
-        assert!(error.contains("interactive-only"));
-        assert!(error.contains("claw --resume SESSION.jsonl /status"));
-    }
-
-    #[test]
-    fn direct_slash_commands_surface_shared_validation_errors() {
-        let compact_error = parse_args(&["/compact".to_string(), "now".to_string()])
-            .expect_err("invalid /compact shape should be rejected");
-        assert!(compact_error.contains("Unexpected arguments for /compact."));
-        assert!(compact_error.contains("Usage            /compact"));
-
-        let plugins_error = parse_args(&[
-            "/plugins".to_string(),
-            "list".to_string(),
-            "extra".to_string(),
-        ])
-        .expect_err("invalid /plugins list shape should be rejected");
-        assert!(plugins_error.contains("Usage: /plugin list"));
-        assert!(plugins_error.contains("Aliases          /plugins, /marketplace"));
-    }
-
-    #[test]
-    fn formats_unknown_slash_command_with_suggestions() {
-        let report = format_unknown_slash_command_message("statsu");
-        assert!(report.contains("unknown slash command: /statsu"));
-        assert!(report.contains("Did you mean"));
-        assert!(report.contains("Use /help"));
-    }
-
-    #[test]
-    fn formats_namespaced_omc_slash_command_with_contract_guidance() {
-        let report = format_unknown_slash_command_message("oh-my-claudecode:hud");
-        assert!(report.contains("unknown slash command: /oh-my-claudecode:hud"));
-        assert!(report.contains("Claude Code/OMC plugin command"));
-        assert!(report.contains("plugin slash commands"));
-        assert!(report.contains("statusline"));
-        assert!(report.contains("session hooks"));
-    }
-
-    #[test]
-    fn parses_resume_flag_with_slash_command() {
-        let args = vec![
-            "--resume".to_string(),
-            "session.jsonl".to_string(),
-            "/compact".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::ResumeSession {
-                session_path: PathBuf::from("session.jsonl"),
-                commands: vec!["/compact".to_string()],
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_resume_flag_without_path_as_latest_session() {
-        assert_eq!(
-            parse_args(&["--resume".to_string()]).expect("args should parse"),
-            CliAction::ResumeSession {
-                session_path: PathBuf::from("latest"),
-                commands: vec![],
-                output_format: CliOutputFormat::Text,
-            }
-        );
-        assert_eq!(
-            parse_args(&["--resume".to_string(), "/status".to_string()])
-                .expect("resume shortcut should parse"),
-            CliAction::ResumeSession {
-                session_path: PathBuf::from("latest"),
-                commands: vec!["/status".to_string()],
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_resume_flag_with_multiple_slash_commands() {
-        let args = vec![
-            "--resume".to_string(),
-            "session.jsonl".to_string(),
-            "/status".to_string(),
-            "/compact".to_string(),
-            "/cost".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::ResumeSession {
-                session_path: PathBuf::from("session.jsonl"),
-                commands: vec![
-                    "/status".to_string(),
-                    "/compact".to_string(),
-                    "/cost".to_string(),
-                ],
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn rejects_unknown_options_with_helpful_guidance() {
-        let error = parse_args(&["--resum".to_string()]).expect_err("unknown option should fail");
-        assert!(error.contains("unknown option: --resum"));
-        assert!(error.contains("Did you mean --resume?"));
-        assert!(error.contains("claw --help"));
-    }
-
-    #[test]
-    fn parses_resume_flag_with_slash_command_arguments() {
-        let args = vec![
-            "--resume".to_string(),
-            "session.jsonl".to_string(),
-            "/export".to_string(),
-            "notes.txt".to_string(),
-            "/clear".to_string(),
-            "--confirm".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::ResumeSession {
-                session_path: PathBuf::from("session.jsonl"),
-                commands: vec![
-                    "/export notes.txt".to_string(),
-                    "/clear --confirm".to_string(),
-                ],
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn parses_resume_flag_with_absolute_export_path() {
-        let args = vec![
-            "--resume".to_string(),
-            "session.jsonl".to_string(),
-            "/export".to_string(),
-            "/tmp/notes.txt".to_string(),
-            "/status".to_string(),
-        ];
-        assert_eq!(
-            parse_args(&args).expect("args should parse"),
-            CliAction::ResumeSession {
-                session_path: PathBuf::from("session.jsonl"),
-                commands: vec!["/export /tmp/notes.txt".to_string(), "/status".to_string()],
-                output_format: CliOutputFormat::Text,
-            }
-        );
-    }
-
-    #[test]
-    fn filtered_tool_specs_respect_allowlist() {
-        let allowed = ["read_file", "grep_search"]
-            .into_iter()
-            .map(str::to_string)
-            .collect();
-        let filtered = filter_tool_specs(&GlobalToolRegistry::builtin(), Some(&allowed));
-        let names = filtered
-            .into_iter()
-            .map(|spec| spec.name)
-            .collect::<Vec<_>>();
-        assert_eq!(names, vec!["read_file", "grep_search"]);
-    }
-
-    #[test]
-    fn filtered_tool_specs_include_plugin_tools() {
-        let filtered = filter_tool_specs(&registry_with_plugin_tool(), None);
-        let names = filtered
-            .into_iter()
-            .map(|definition| definition.name)
-            .collect::<Vec<_>>();
-        assert!(names.contains(&"bash".to_string()));
-        assert!(names.contains(&"plugin_echo".to_string()));
-    }
-
-    #[test]
-    fn permission_policy_uses_plugin_tool_permissions() {
-        let feature_config = runtime::RuntimeFeatureConfig::default();
-        let policy = permission_policy(
-            PermissionMode::ReadOnly,
-            &feature_config,
-            &registry_with_plugin_tool(),
-        )
-        .expect("permission policy should build");
-        let required = policy.required_mode_for("plugin_echo");
-        assert_eq!(required, PermissionMode::WorkspaceWrite);
-    }
-
-    #[test]
-    fn shared_help_uses_resume_annotation_copy() {
-        let help = commands::render_slash_command_help();
-        assert!(help.contains("Slash commands"));
-        assert!(help.contains("works with --resume SESSION.jsonl"));
-    }
-
-    #[test]
-    fn repl_help_includes_shared_commands_and_exit() {
-        let help = render_repl_help();
-        assert!(help.contains("REPL"));
-        assert!(help.contains("/help"));
-        assert!(help.contains("Complete commands, modes, and recent sessions"));
-        assert!(help.contains("/status"));
-        assert!(help.contains("/sandbox"));
-        assert!(help.contains("/model [model]"));
-        assert!(help.contains("/permissions [read-only|workspace-write|danger-full-access]"));
-        assert!(help.contains("/clear [--confirm]"));
-        assert!(help.contains("/cost"));
-        assert!(help.contains("/resume <session-path>"));
-        assert!(help.contains("/config [env|hooks|model|plugins]"));
-        assert!(help.contains("/mcp [list|show <server>|help]"));
-        assert!(help.contains("/memory"));
-        assert!(help.contains("/init"));
-        assert!(help.contains("/diff"));
-        assert!(help.contains("/version"));
-        assert!(help.contains("/export [file]"));
-        // Batch 5 added `/session delete`; match on the stable core rather than
-        // the trailing bracket so future additions don't re-break this.
-        assert!(help.contains("/session [list|switch <session-id>|fork [branch-name]"));
-        assert!(help.contains(
-            "/plugin [list|install <path>|enable <name>|disable <name>|uninstall <id>|update <id>]"
-        ));
-        assert!(help.contains("aliases: /plugins, /marketplace"));
-        assert!(help.contains("/agents"));
-        assert!(help.contains("/skills"));
-        assert!(help.contains("/exit"));
-        assert!(help.contains("Auto-save            .claw/sessions/<session-id>.jsonl"));
-        assert!(help.contains("Resume latest        /resume latest"));
-    }
-
-    #[test]
-    fn completion_candidates_include_workflow_shortcuts_and_dynamic_sessions() {
-        let completions = slash_command_completion_candidates_with_sessions(
-            "sonnet",
-            Some("session-current"),
-            vec!["session-old".to_string()],
-        );
-
-        assert!(completions.contains(&"/model claude-sonnet-4-6".to_string()));
-        assert!(completions.contains(&"/permissions workspace-write".to_string()));
-        assert!(completions.contains(&"/session list".to_string()));
-        assert!(completions.contains(&"/session switch session-current".to_string()));
-        assert!(completions.contains(&"/resume session-old".to_string()));
-        assert!(completions.contains(&"/mcp list".to_string()));
-        assert!(completions.contains(&"/ultraplan ".to_string()));
-    }
-
-    #[test]
-    fn startup_banner_mentions_workflow_completions() {
-        let _guard = env_lock();
-        // Inject dummy credentials so LiveCli can construct without real Anthropic key
-        std::env::set_var("ANTHROPIC_API_KEY", "test-dummy-key-for-banner-test");
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-
-        let banner = with_current_dir(&root, || {
-            LiveCli::new(
-                "claude-sonnet-4-6".to_string(),
-                true,
-                None,
-                PermissionMode::DangerFullAccess,
-            )
-            .expect("cli should initialize")
-            .startup_banner()
-        });
-
-        assert!(banner.contains("Tab"));
-        assert!(banner.contains("workflow completions"));
-
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-        std::env::remove_var("ANTHROPIC_API_KEY");
-    }
-
-    #[test]
-    fn format_connected_line_renders_anthropic_provider_for_claude_model() {
-        let model = "claude-sonnet-4-6";
-
-        let line = format_connected_line(model);
-
-        assert_eq!(line, "Connected: claude-sonnet-4-6 via anthropic");
-    }
-
-    #[test]
-    fn format_connected_line_renders_xai_provider_for_grok_model() {
-        let model = "grok-3";
-
-        let line = format_connected_line(model);
-
-        assert_eq!(line, "Connected: grok-3 via xai");
-    }
-
-    #[test]
-    fn resolve_repl_model_returns_user_supplied_model_unchanged_when_explicit() {
-        let user_model = "claude-sonnet-4-6".to_string();
-
-        let resolved = resolve_repl_model(user_model);
-
-        assert_eq!(resolved, "claude-sonnet-4-6");
-    }
-
-    #[test]
-    fn resolve_repl_model_falls_back_to_anthropic_model_env_when_default() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-        let config_home = root.join("config");
-        fs::create_dir_all(&config_home).expect("config home dir");
-        std::env::set_var("CLAW_CONFIG_HOME", &config_home);
-        std::env::remove_var("ANTHROPIC_MODEL");
-        std::env::set_var("ANTHROPIC_MODEL", "sonnet");
-
-        let resolved = with_current_dir(&root, || resolve_repl_model(DEFAULT_MODEL.to_string()));
-
-        assert_eq!(resolved, "claude-sonnet-4-6");
-
-        std::env::remove_var("ANTHROPIC_MODEL");
-        std::env::remove_var("CLAW_CONFIG_HOME");
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn resolve_repl_model_returns_default_when_env_unset_and_no_config() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-        let config_home = root.join("config");
-        fs::create_dir_all(&config_home).expect("config home dir");
-        std::env::set_var("CLAW_CONFIG_HOME", &config_home);
-        std::env::remove_var("ANTHROPIC_MODEL");
-
-        let resolved = with_current_dir(&root, || resolve_repl_model(DEFAULT_MODEL.to_string()));
-
-        assert_eq!(resolved, DEFAULT_MODEL);
-
-        std::env::remove_var("CLAW_CONFIG_HOME");
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn resume_supported_command_list_matches_expected_surface() {
-        let names = resume_supported_slash_commands()
-            .into_iter()
-            .map(|spec| spec.name)
-            .collect::<Vec<_>>();
-        // Now with 135+ slash commands, verify minimum resume support
-        assert!(
-            names.len() >= 39,
-            "expected at least 39 resume-supported commands, got {}",
-            names.len()
-        );
-        // Verify key resume commands still exist
-        assert!(names.contains(&"help"));
-        assert!(names.contains(&"status"));
-        assert!(names.contains(&"compact"));
-    }
-
-    #[test]
-    fn resume_report_uses_sectioned_layout() {
-        let report = format_resume_report("session.jsonl", 14, 6);
-        assert!(report.contains("Session resumed"));
-        assert!(report.contains("Session file     session.jsonl"));
-        assert!(report.contains("Messages         14"));
-        assert!(report.contains("Turns            6"));
-    }
-
-    #[test]
-    fn compact_report_uses_structured_output() {
-        let compacted = format_compact_report(8, 5, false);
-        assert!(compacted.contains("Compact"));
-        assert!(compacted.contains("Result           compacted"));
-        assert!(compacted.contains("Messages removed 8"));
-        let skipped = format_compact_report(0, 3, true);
-        assert!(skipped.contains("Result           skipped"));
-    }
-
-    #[test]
-    fn cost_report_uses_sectioned_layout() {
-        let report = format_cost_report(runtime::TokenUsage {
-            input_tokens: 20,
-            output_tokens: 8,
-            cache_creation_input_tokens: 3,
-            cache_read_input_tokens: 1,
-        });
-        assert!(report.contains("Cost"));
-        assert!(report.contains("Input tokens     20"));
-        assert!(report.contains("Output tokens    8"));
-        assert!(report.contains("Cache create     3"));
-        assert!(report.contains("Cache read       1"));
-        assert!(report.contains("Total tokens     32"));
-    }
-
-    #[test]
-    fn permissions_report_uses_sectioned_layout() {
-        let report = format_permissions_report("workspace-write");
-        assert!(report.contains("Permissions"));
-        assert!(report.contains("Active mode      workspace-write"));
-        assert!(report.contains("Modes"));
-        assert!(report.contains("read-only          ○ available Read/search tools only"));
-        assert!(report.contains("workspace-write    ● current   Edit files inside the workspace"));
-        assert!(report.contains("danger-full-access ○ available Unrestricted tool access"));
-    }
-
-    #[test]
-    fn permissions_switch_report_is_structured() {
-        let report = format_permissions_switch_report("read-only", "workspace-write");
-        assert!(report.contains("Permissions updated"));
-        assert!(report.contains("Result           mode switched"));
-        assert!(report.contains("Previous mode    read-only"));
-        assert!(report.contains("Active mode      workspace-write"));
-        assert!(report.contains("Applies to       subsequent tool calls"));
-    }
-
-    #[test]
-    fn init_help_mentions_direct_subcommand() {
-        let mut help = Vec::new();
-        print_help_to(&mut help).expect("help should render");
-        let help = String::from_utf8(help).expect("help should be utf8");
-        assert!(help.contains("claw help"));
-        assert!(help.contains("claw version"));
-        assert!(help.contains("claw status"));
-        assert!(help.contains("claw sandbox"));
-        assert!(help.contains("claw init"));
-        assert!(help.contains("claw agents"));
-        assert!(help.contains("claw mcp"));
-        assert!(help.contains("claw skills"));
-        assert!(help.contains("claw /skills"));
-    }
-
-    #[test]
-    fn model_report_uses_sectioned_layout() {
-        let report = format_model_report("claude-sonnet", 12, 4);
-        assert!(report.contains("Model"));
-        assert!(report.contains("Current model    claude-sonnet"));
-        assert!(report.contains("Session messages 12"));
-        assert!(report.contains("Switch models with /model <name>"));
-    }
-
-    #[test]
-    fn model_switch_report_preserves_context_summary() {
-        let report = format_model_switch_report("claude-sonnet", "claude-opus", 9);
-        assert!(report.contains("Model updated"));
-        assert!(report.contains("Previous         claude-sonnet"));
-        assert!(report.contains("Current          claude-opus"));
-        assert!(report.contains("Preserved msgs   9"));
-    }
-
-    #[test]
-    fn status_line_reports_model_and_token_totals() {
-        let status = format_status_report(
-            "claude-sonnet",
-            StatusUsage {
-                message_count: 7,
-                turns: 3,
-                latest: runtime::TokenUsage {
-                    input_tokens: 5,
-                    output_tokens: 4,
-                    cache_creation_input_tokens: 1,
-                    cache_read_input_tokens: 0,
-                },
-                cumulative: runtime::TokenUsage {
-                    input_tokens: 20,
-                    output_tokens: 8,
-                    cache_creation_input_tokens: 2,
-                    cache_read_input_tokens: 1,
-                },
-                estimated_tokens: 128,
-            },
-            "workspace-write",
-            &super::StatusContext {
-                cwd: PathBuf::from("/tmp/project"),
-                session_path: Some(PathBuf::from("session.jsonl")),
-                loaded_config_files: 2,
-                discovered_config_files: 3,
-                memory_file_count: 4,
-                project_root: Some(PathBuf::from("/tmp")),
-                git_branch: Some("main".to_string()),
-                git_summary: GitWorkspaceSummary {
-                    changed_files: 3,
-                    staged_files: 1,
-                    unstaged_files: 1,
-                    untracked_files: 1,
-                    conflicted_files: 0,
-                },
-                sandbox_status: runtime::SandboxStatus::default(),
-            },
-        );
-        assert!(status.contains("Status"));
-        assert!(status.contains("Model            claude-sonnet"));
-        assert!(status.contains("Permission mode  workspace-write"));
-        assert!(status.contains("Messages         7"));
-        assert!(status.contains("Latest total     10"));
-        assert!(status.contains("Cumulative total 31"));
-        assert!(status.contains("Cwd              /tmp/project"));
-        assert!(status.contains("Project root     /tmp"));
-        assert!(status.contains("Git branch       main"));
-        assert!(
-            status.contains("Git state        dirty · 3 files · 1 staged, 1 unstaged, 1 untracked")
-        );
-        assert!(status.contains("Changed files    3"));
-        assert!(status.contains("Staged           1"));
-        assert!(status.contains("Unstaged         1"));
-        assert!(status.contains("Untracked        1"));
-        assert!(status.contains("Session          session.jsonl"));
-        assert!(status.contains("Config files     loaded 2/3"));
-        assert!(status.contains("Memory files     4"));
-        assert!(status.contains("Suggested flow   /status → /diff → /commit"));
-    }
-
-    #[test]
-    fn commit_reports_surface_workspace_context() {
-        let summary = GitWorkspaceSummary {
-            changed_files: 2,
-            staged_files: 1,
-            unstaged_files: 1,
-            untracked_files: 0,
-            conflicted_files: 0,
-        };
-
-        let preflight = format_commit_preflight_report(Some("feature/ux"), summary);
-        assert!(preflight.contains("Result           ready"));
-        assert!(preflight.contains("Branch           feature/ux"));
-        assert!(preflight.contains("Workspace        dirty · 2 files · 1 staged, 1 unstaged"));
-        assert!(preflight
-            .contains("Action           create a git commit from the current workspace changes"));
-    }
-
-    #[test]
-    fn commit_skipped_report_points_to_next_steps() {
-        let report = format_commit_skipped_report();
-        assert!(report.contains("Reason           no workspace changes"));
-        assert!(report
-            .contains("Action           create a git commit from the current workspace changes"));
-        assert!(report.contains("/status to inspect context"));
-        assert!(report.contains("/diff to inspect repo changes"));
-    }
-
-    #[test]
-    fn runtime_slash_reports_describe_command_behavior() {
-        let bughunter = format_bughunter_report(Some("runtime"));
-        assert!(bughunter.contains("Scope            runtime"));
-        assert!(bughunter.contains("inspect the selected code for likely bugs"));
-
-        let ultraplan = format_ultraplan_report(Some("ship the release"));
-        assert!(ultraplan.contains("Task             ship the release"));
-        assert!(ultraplan.contains("break work into a multi-step execution plan"));
-
-        let pr = format_pr_report("feature/ux", Some("ready for review"));
-        assert!(pr.contains("Branch           feature/ux"));
-        assert!(pr.contains("draft or create a pull request"));
-
-        let issue = format_issue_report(Some("flaky test"));
-        assert!(issue.contains("Context          flaky test"));
-        assert!(issue.contains("draft or create a GitHub issue"));
-    }
-
-    #[test]
-    fn no_arg_commands_reject_unexpected_arguments() {
-        assert!(validate_no_args("/commit", None).is_ok());
-
-        let error = validate_no_args("/commit", Some("now"))
-            .expect_err("unexpected arguments should fail")
-            .to_string();
-        assert!(error.contains("/commit does not accept arguments"));
-        assert!(error.contains("Received: now"));
-    }
-
-    #[test]
-    fn config_report_supports_section_views() {
-        let report = render_config_report(Some("env")).expect("config report should render");
-        assert!(report.contains("Merged section: env"));
-        let plugins_report =
-            render_config_report(Some("plugins")).expect("plugins config report should render");
-        assert!(plugins_report.contains("Merged section: plugins"));
-    }
-
-    #[test]
-    fn memory_report_uses_sectioned_layout() {
-        let report = render_memory_report().expect("memory report should render");
-        assert!(report.contains("Memory"));
-        assert!(report.contains("Working directory"));
-        assert!(report.contains("Instruction files"));
-        assert!(report.contains("Discovered files"));
-    }
-
-    #[test]
-    fn config_report_uses_sectioned_layout() {
-        let report = render_config_report(None).expect("config report should render");
-        assert!(report.contains("Config"));
-        assert!(report.contains("Discovered files"));
-        assert!(report.contains("Merged JSON"));
-    }
-
-    #[test]
-    fn parses_git_status_metadata() {
-        let _guard = env_lock();
-        let temp_root = temp_dir();
-        fs::create_dir_all(&temp_root).expect("root dir");
-        let (project_root, branch) = parse_git_status_metadata_for(
-            &temp_root,
-            Some(
-                "## rcc/cli...origin/rcc/cli
- M src/main.rs",
-            ),
-        );
-        assert_eq!(branch.as_deref(), Some("rcc/cli"));
-        assert!(project_root.is_none());
-        fs::remove_dir_all(temp_root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn parses_detached_head_from_status_snapshot() {
-        let _guard = env_lock();
-        assert_eq!(
-            parse_git_status_branch(Some(
-                "## HEAD (no branch)
- M src/main.rs"
-            )),
-            Some("detached HEAD".to_string())
-        );
-    }
-
-    #[test]
-    fn parses_git_workspace_summary_counts() {
-        let summary = parse_git_workspace_summary(Some(
-            "## feature/ux
-M  src/main.rs
- M README.md
-?? notes.md
-UU conflicted.rs",
-        ));
-
-        assert_eq!(
-            summary,
-            GitWorkspaceSummary {
-                changed_files: 4,
-                staged_files: 2,
-                unstaged_files: 2,
-                untracked_files: 1,
-                conflicted_files: 1,
-            }
-        );
-        assert_eq!(
-            summary.headline(),
-            "dirty · 4 files · 2 staged, 2 unstaged, 1 untracked, 1 conflicted"
-        );
-    }
-
-    #[test]
-    fn render_diff_report_shows_clean_tree_for_committed_repo() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-        git(&["init", "--quiet"], &root);
-        git(&["config", "user.email", "tests@example.com"], &root);
-        git(&["config", "user.name", "Rusty Claude Tests"], &root);
-        fs::write(root.join("tracked.txt"), "hello\n").expect("write file");
-        git(&["add", "tracked.txt"], &root);
-        git(&["commit", "-m", "init", "--quiet"], &root);
-
-        let report = render_diff_report_for(&root).expect("diff report should render");
-        assert!(report.contains("clean working tree"));
-
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn render_diff_report_includes_staged_and_unstaged_sections() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-        git(&["init", "--quiet"], &root);
-        git(&["config", "user.email", "tests@example.com"], &root);
-        git(&["config", "user.name", "Rusty Claude Tests"], &root);
-        fs::write(root.join("tracked.txt"), "hello\n").expect("write file");
-        git(&["add", "tracked.txt"], &root);
-        git(&["commit", "-m", "init", "--quiet"], &root);
-
-        fs::write(root.join("tracked.txt"), "hello\nstaged\n").expect("update file");
-        git(&["add", "tracked.txt"], &root);
-        fs::write(root.join("tracked.txt"), "hello\nstaged\nunstaged\n")
-            .expect("update file twice");
-
-        let report = render_diff_report_for(&root).expect("diff report should render");
-        assert!(report.contains("Staged changes:"));
-        assert!(report.contains("Unstaged changes:"));
-        assert!(report.contains("tracked.txt"));
-
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn render_diff_report_omits_ignored_files() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-        git(&["init", "--quiet"], &root);
-        git(&["config", "user.email", "tests@example.com"], &root);
-        git(&["config", "user.name", "Rusty Claude Tests"], &root);
-        fs::write(root.join(".gitignore"), ".omx/\nignored.txt\n").expect("write gitignore");
-        fs::write(root.join("tracked.txt"), "hello\n").expect("write tracked");
-        git(&["add", ".gitignore", "tracked.txt"], &root);
-        git(&["commit", "-m", "init", "--quiet"], &root);
-        fs::create_dir_all(root.join(".omx")).expect("write omx dir");
-        fs::write(root.join(".omx").join("state.json"), "{}").expect("write ignored omx");
-        fs::write(root.join("ignored.txt"), "secret\n").expect("write ignored file");
-        fs::write(root.join("tracked.txt"), "hello\nworld\n").expect("write tracked change");
-
-        let report = render_diff_report_for(&root).expect("diff report should render");
-        assert!(report.contains("tracked.txt"));
-        assert!(!report.contains("+++ b/ignored.txt"));
-        assert!(!report.contains("+++ b/.omx/state.json"));
-
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn resume_diff_command_renders_report_for_saved_session() {
-        let _guard = env_lock();
-        let root = temp_dir();
-        fs::create_dir_all(&root).expect("root dir");
-        git(&["init", "--quiet"], &root);
-        git(&["config", "user.email", "tests@example.com"], &root);
-        git(&["config", "user.name", "Rusty Claude Tests"], &root);
-        fs::write(root.join("tracked.txt"), "hello\n").expect("write tracked");
-        git(&["add", "tracked.txt"], &root);
-        git(&["commit", "-m", "init", "--quiet"], &root);
-        fs::write(root.join("tracked.txt"), "hello\nworld\n").expect("modify tracked");
-        let session_path = root.join("session.json");
-        Session::new()
-            .save_to_path(&session_path)
-            .expect("session should save");
-
-        let session = Session::load_from_path(&session_path).expect("session should load");
-        let outcome = with_current_dir(&root, || {
-            run_resume_command(&session_path, &session, &SlashCommand::Diff)
-                .expect("resume diff should work")
-        });
-        let message = outcome.message.expect("diff message should exist");
-        assert!(message.contains("Unstaged changes:"));
-        assert!(message.contains("tracked.txt"));
-
-        fs::remove_dir_all(root).expect("cleanup temp dir");
-    }
-
-    #[test]
-    fn status_context_reads_real_workspace_metadata() {
-        let context = status_context(None).expect("status context should load");
-        assert!(context.cwd.is_absolute());
-        assert!(context.discovered_config_files >= context.loaded_config_files);
-        assert!(context.loaded_config_files <= context.discovered_config_files);
-    }
-
-    #[test]
-    fn normalizes_supported_permission_modes() {
-        assert_eq!(normalize_permission_mode("read-only"), Some("read-only"));
-        assert_eq!(
-            normalize_permission_mode("workspace-write"),
-            Some("workspace-write")
-        );
-        assert_eq!(
-            normalize_permission_mode("danger-full-access"),
-            Some("danger-full-access")
-        );
-        assert_eq!(normalize_permission_mode("unknown"), None);
-    }
-
-    #[test]
-    fn clear_command_requires_explicit_confirmation_flag() {
-        assert_eq!(
-            SlashCommand::parse("/clear"),
-            Ok(Some(SlashCommand::Clear { confirm: false }))
-        );
-        assert_eq!(
-            SlashCommand::parse("/clear --confirm"),
-            Ok(Some(SlashCommand::Clear { confirm: true }))
-        );
-    }
-
-    #[test]
-    fn parses_resume_and_config_slash_commands() {
-        assert_eq!(
-            SlashCommand::parse("/resume saved-session.jsonl"),
-            Ok(Some(SlashCommand::Resume {
-                session_path: Some("saved-session.jsonl".to_string())
-            }))
-        );
-        assert_eq!(
-            SlashCommand::parse("/clear --confirm"),
-            Ok(Some(SlashCommand::Clear { confirm: true }))
-        );
-        assert_eq!(
-            SlashCommand::parse("/config"),
-            Ok(Some(SlashCommand::Config { section: None }))
-        );
-        assert_eq!(
-            SlashCommand::parse("/config env"),
-            Ok(Some(SlashCommand::Config {
-                section: Some("env".to_string())
-            }))
-        );
-        assert_eq!(
-            SlashCommand::parse("/memory"),
-            Ok(Some(SlashCommand::Memory))
-        );
-        assert_eq!(SlashCommand::parse("/init"), Ok(Some(SlashCommand::Init)));
-        assert_eq!(
-            SlashCommand::parse("/session fork incident-review"),
-            Ok(Some(SlashCommand::Session {
-                action: Some("fork".to_string()),
-                target: Some("incident-review".to_string())
-            }))
-        );
-    }
-
-    #[test]
-    fn help_mentions_jsonl_resume_examples() {
-        let mut help = Vec::new();
-        print_help_to(&mut help).expect("help should render");
-        let help = String::from_utf8(help).expect("help should be utf8");
-        assert!(help.contains("claw --resume [SESSION.jsonl|session-id|latest]"));
-        assert!(help.contains("Use `latest` with --resume, /resume, or /session switch"));
-        assert!(help.contains("claw --resume latest"));
-        assert!(help.contains("claw --resume latest /status /diff /export notes.txt"));
-    }
-
-    #[test]
-    fn managed_sessions_default_to_jsonl_and_resolve_legacy_json() {
-        let _guard = cwd_lock().lock().expect("cwd lock");
-        let workspace = temp_workspace("session-resolution");
-        std::fs::create_dir_all(&workspace).expect("workspace should create");
-        let previous = std::env::current_dir().expect("cwd");
-        std::env::set_current_dir(&workspace).expect("switch cwd");
-
-        let handle = create_managed_session_handle("session-alpha").expect("jsonl handle");
-        assert!(handle.path.ends_with("session-alpha.jsonl"));
-
-        let legacy_path = workspace.join(".claw/sessions/legacy.json");
-        std::fs::create_dir_all(
-            legacy_path
-                .parent()
-                .expect("legacy path should have parent directory"),
-        )
-        .expect("session dir should exist");
-        Session::new()
-            .with_persistence_path(legacy_path.clone())
-            .save_to_path(&legacy_path)
-            .expect("legacy session should save");
-
-        let resolved = resolve_session_reference("legacy").expect("legacy session should resolve");
-        assert_eq!(
-            resolved
-                .path
-                .canonicalize()
-                .expect("resolved path should exist"),
-            legacy_path
-                .canonicalize()
-                .expect("legacy path should exist")
-        );
-
-        std::env::set_current_dir(previous).expect("restore cwd");
-        std::fs::remove_dir_all(workspace).expect("workspace should clean up");
-    }
-
-    #[test]
-    fn latest_session_alias_resolves_most_recent_managed_session() {
-        let _guard = cwd_lock().lock().expect("cwd lock");
-        let workspace = temp_workspace("latest-session-alias");
-        std::fs::create_dir_all(&workspace).expect("workspace should create");
-        let previous = std::env::current_dir().expect("cwd");
-        std::env::set_current_dir(&workspace).expect("switch cwd");
-
-        let older = create_managed_session_handle("session-older").expect("older handle");
-        Session::new()
-            .with_persistence_path(older.path.clone())
-            .save_to_path(&older.path)
-            .expect("older session should save");
-        std::thread::sleep(Duration::from_millis(20));
-        let newer = create_managed_session_handle("session-newer").expect("newer handle");
-        Session::new()
-            .with_persistence_path(newer.path.clone())
-            .save_to_path(&newer.path)
-            .expect("newer session should save");
-
-        let resolved = resolve_session_reference("latest").expect("latest session should resolve");
-        assert_eq!(
-            resolved
-                .path
-                .canonicalize()
-                .expect("resolved path should exist"),
-            newer.path.canonicalize().expect("newer path should exist")
-        );
-
-        std::env::set_current_dir(previous).expect("restore cwd");
-        std::fs::remove_dir_all(workspace).expect("workspace should clean up");
-    }
-
-    #[test]
-    fn unknown_slash_command_guidance_suggests_nearby_commands() {
-        let message = format_unknown_slash_command("stats");
-        assert!(message.contains("Unknown slash command: /stats"));
-        assert!(message.contains("/status"));
-        assert!(message.contains("/help"));
-    }
-
-    #[test]
-    fn unknown_omc_slash_command_guidance_explains_runtime_gap() {
-        let message = format_unknown_slash_command("oh-my-claudecode:hud");
-        assert!(message.contains("Unknown slash command: /oh-my-claudecode:hud"));
-        assert!(message.contains("Claude Code/OMC plugin command"));
-        assert!(message.contains("does not yet load plugin slash commands"));
-    }
-
-    #[test]
-    fn resume_usage_mentions_latest_shortcut() {
-        let usage = render_resume_usage();
-        assert!(usage.contains("/resume <session-path|session-id|latest>"));
-        assert!(usage.contains(".claw/sessions/<session-id>.jsonl"));
-        assert!(usage.contains("/session list"));
-    }
-
-    fn cwd_lock() -> &'static Mutex<()> {
-        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
-        LOCK.get_or_init(|| Mutex::new(()))
-    }
-
-    fn temp_workspace(label: &str) -> PathBuf {
-        let nanos = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .expect("system time should be after epoch")
-            .as_nanos();
-        std::env::temp_dir().join(format!("claw-cli-{label}-{nanos}"))
-    }
-
-    #[test]
-    fn init_template_mentions_detected_rust_workspace() {
-        let _guard = cwd_lock()
-            .lock()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let workspace_root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..");
-        let rendered = crate::init::render_init_claude_md(&workspace_root);
-        assert!(rendered.contains("# CLAUDE.md"));
-        assert!(rendered.contains("cargo clippy --workspace --all-targets -- -D warnings"));
-    }
-
-    #[test]
-    fn converts_tool_roundtrip_messages() {
-        let messages = vec![
-            ConversationMessage::user_text("hello"),
-            ConversationMessage::assistant(vec![ContentBlock::ToolUse {
-                id: "tool-1".to_string(),
-                name: "bash".to_string(),
-                input: "{\"command\":\"pwd\"}".to_string(),
-            }]),
-            ConversationMessage {
-                role: MessageRole::Tool,
-                blocks: vec![ContentBlock::ToolResult {
-                    tool_use_id: "tool-1".to_string(),
-                    tool_name: "bash".to_string(),
-                    output: "ok".to_string(),
-                    is_error: false,
-                }],
-                usage: None,
-            },
-        ];
-
-        let converted = super::convert_messages(&messages);
-        assert_eq!(converted.len(), 3);
-        assert_eq!(converted[1].role, "assistant");
-        assert_eq!(converted[2].role, "user");
-    }
-    #[test]
-    fn repl_help_mentions_history_completion_and_multiline() {
-        let help = render_repl_help();
-        assert!(help.contains("Up/Down"));
-        assert!(help.contains("Tab"));
-        assert!(help.contains("Shift+Enter/Ctrl+J"));
-        assert!(help.contains("Ctrl-R"));
-        assert!(help.contains("Reverse-search prompt history"));
-        assert!(help.contains("/history [count]"));
-    }
-
-    #[test]
-    fn parse_history_count_defaults_to_twenty_when_missing() {
-        // given
-        let raw: Option<&str> = None;
-
-        // when
-        let parsed = parse_history_count(raw);
-
-        // then
-        assert_eq!(parsed, Ok(20));
-    }
-
-    #[test]
-    fn parse_history_count_accepts_positive_integers() {
-        // given
-        let raw = Some("25");
-
-        // when
-        let parsed = parse_history_count(raw);
-
-        // then
-        assert_eq!(parsed, Ok(25));
-    }
-
-    #[test]
-    fn parse_history_count_rejects_zero() {
-        // given
-        let raw = Some("0");
-
-        // when
-        let parsed = parse_history_count(raw);
-
-        // then
-        assert!(parsed.is_err());
-        assert!(parsed.unwrap_err().contains("greater than 0"));
-    }
-
-    #[test]
-    fn parse_history_count_rejects_non_numeric() {
-        // given
-        let raw = Some("abc");
-
-        // when
-        let parsed = parse_history_count(raw);
-
-        // then
-        assert!(parsed.is_err());
-        assert!(parsed.unwrap_err().contains("invalid count 'abc'"));
-    }
-
-    #[test]
-    fn format_history_timestamp_renders_iso8601_utc() {
-        // given
-        // 2023-01-15T12:34:56.789Z -> 1673786096789 ms
-        let timestamp_ms: u64 = 1_673_786_096_789;
-
-        // when
-        let formatted = format_history_timestamp(timestamp_ms);
-
-        // then
-        assert_eq!(formatted, "2023-01-15T12:34:56.789Z");
-    }
-
-    #[test]
-    fn format_history_timestamp_renders_unix_epoch_origin() {
-        // given
-        let timestamp_ms: u64 = 0;
-
-        // when
-        let formatted = format_history_timestamp(timestamp_ms);
-
-        // then
-        assert_eq!(formatted, "1970-01-01T00:00:00.000Z");
-    }
-
-    #[test]
-    fn render_prompt_history_report_lists_entries_with_timestamps() {
-        // given
-        let entries = vec![
-            PromptHistoryEntry {
-                timestamp_ms: 1_673_786_096_000,
-                text: "first prompt".to_string(),
-            },
-            PromptHistoryEntry {
-                timestamp_ms: 1_673_786_100_000,
-                text: "second prompt".to_string(),
-            },
-        ];
-
-        // when
-        let rendered = render_prompt_history_report(&entries, 10);
-
-        // then
-        assert!(rendered.contains("Prompt history"));
-        assert!(rendered.contains("Total            2"));
-        assert!(rendered.contains("Showing          2 most recent"));
-        assert!(rendered.contains("Reverse search   Ctrl-R in the REPL"));
-        assert!(rendered.contains("2023-01-15T12:34:56.000Z"));
-        assert!(rendered.contains("first prompt"));
-        assert!(rendered.contains("second prompt"));
-    }
-
-    #[test]
-    fn render_prompt_history_report_truncates_to_limit_from_the_tail() {
-        // given
-        let entries = vec![
-            PromptHistoryEntry {
-                timestamp_ms: 1_000,
-                text: "older".to_string(),
-            },
-            PromptHistoryEntry {
-                timestamp_ms: 2_000,
-                text: "middle".to_string(),
-            },
-            PromptHistoryEntry {
-                timestamp_ms: 3_000,
-                text: "latest".to_string(),
-            },
-        ];
-
-        // when
-        let rendered = render_prompt_history_report(&entries, 2);
-
-        // then
-        assert!(rendered.contains("Total            3"));
-        assert!(rendered.contains("Showing          2 most recent"));
-        assert!(!rendered.contains("older"));
-        assert!(rendered.contains("middle"));
-        assert!(rendered.contains("latest"));
-    }
-
-    #[test]
-    fn render_prompt_history_report_handles_empty_history() {
-        // given
-        let entries: Vec<PromptHistoryEntry> = Vec::new();
-
-        // when
-        let rendered = render_prompt_history_report(&entries, 10);
-
-        // then
-        assert!(rendered.contains("no prompts recorded yet"));
-    }
-
-    #[test]
-    fn collect_session_prompt_history_extracts_user_text_blocks() {
-        // given
-        let mut session = Session::new();
-        session.push_user_text("hello").unwrap();
-        session.push_user_text("world").unwrap();
-
-        // when
-        let entries = collect_session_prompt_history(&session);
-
-        // then
-        assert_eq!(entries.len(), 2);
-        assert_eq!(entries[0].text, "hello");
-        assert_eq!(entries[1].text, "world");
-    }
-
-    #[test]
-    fn tool_rendering_helpers_compact_output() {
-        let start = format_tool_call_start("read_file", r#"{"path":"src/main.rs"}"#);
-        assert!(start.contains("read_file"));
-        assert!(start.contains("src/main.rs"));
-
-        let done = format_tool_result(
-            "read_file",
-            r#"{"file":{"filePath":"src/main.rs","content":"hello","numLines":1,"startLine":1,"totalLines":1}}"#,
-            false,
-        );
-        assert!(done.contains("📄 Read src/main.rs"));
-        assert!(done.contains("hello"));
-    }
-
-    #[test]
-    fn tool_rendering_truncates_large_read_output_for_display_only() {
-        let content = (0..200)
-            .map(|index| format!("line {index:03}"))
-            .collect::<Vec<_>>()
-            .join("\n");
-        let output = json!({
-            "file": {
-                "filePath": "src/main.rs",
-                "content": content,
-                "numLines": 200,
-                "startLine": 1,
-                "totalLines": 200
-            }
-        })
-        .to_string();
-
-        let rendered = format_tool_result("read_file", &output, false);
-
-        assert!(rendered.contains("line 000"));
-        assert!(rendered.contains("line 079"));
-        assert!(!rendered.contains("line 199"));
-        assert!(rendered.contains("full result preserved in session"));
-        assert!(output.contains("line 199"));
-    }
-
-    #[test]
-    fn tool_rendering_truncates_large_bash_output_for_display_only() {
-        let stdout = (0..120)
-            .map(|index| format!("stdout {index:03}"))
-            .collect::<Vec<_>>()
-            .join("\n");
-        let output = json!({
-            "stdout": stdout,
-            "stderr": "",
-            "returnCodeInterpretation": "completed successfully"
-        })
-        .to_string();
-
-        let rendered = format_tool_result("bash", &output, false);
-
-        assert!(rendered.contains("stdout 000"));
-        assert!(rendered.contains("stdout 059"));
-        assert!(!rendered.contains("stdout 119"));
-        assert!(rendered.contains("full result preserved in session"));
-        assert!(output.contains("stdout 119"));
-    }
-
-    #[test]
-    fn tool_rendering_truncates_generic_long_output_for_display_only() {
-        let items = (0..120)
-            .map(|index| format!("payload {index:03}"))
-            .collect::<Vec<_>>();
-        let output = json!({
-            "summary": "plugin payload",
-            "items": items,
-        })
-        .to_string();
-
-        let rendered = format_tool_result("plugin_echo", &output, false);
-
-        assert!(rendered.contains("plugin_echo"));
-        assert!(rendered.contains("payload 000"));
-        assert!(rendered.contains("payload 040"));
-        assert!(!rendered.contains("payload 080"));
-        assert!(!rendered.contains("payload 119"));
-        assert!(rendered.contains("full result preserved in session"));
-        assert!(output.contains("payload 119"));
-    }
-
-    #[test]
-    fn tool_rendering_truncates_raw_generic_output_for_display_only() {
-        let output = (0..120)
-            .map(|index| format!("raw {index:03}"))
-            .collect::<Vec<_>>()
-            .join("\n");
-
-        let rendered = format_tool_result("plugin_echo", &output, false);
-
-        assert!(rendered.contains("plugin_echo"));
-        assert!(rendered.contains("raw 000"));
-        assert!(rendered.contains("raw 059"));
-        assert!(!rendered.contains("raw 119"));
-        assert!(rendered.contains("full result preserved in session"));
-        assert!(output.contains("raw 119"));
-    }
-
-    #[test]
-    fn ultraplan_progress_lines_include_phase_step_and_elapsed_status() {
-        let snapshot = InternalPromptProgressState {
-            command_label: "Ultraplan",
-            task_label: "ship plugin progress".to_string(),
-            step: 3,
-            phase: "running read_file".to_string(),
-            detail: Some("reading rust/crates/rusty-claude-cli/src/main.rs".to_string()),
-            saw_final_text: false,
-        };
-
-        let started = format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Started,
-            &snapshot,
-            Duration::from_secs(0),
-            None,
-        );
-        let heartbeat = format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Heartbeat,
-            &snapshot,
-            Duration::from_secs(9),
-            None,
-        );
-        let completed = format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Complete,
-            &snapshot,
-            Duration::from_secs(12),
-            None,
-        );
-        let failed = format_internal_prompt_progress_line(
-            InternalPromptProgressEvent::Failed,
-            &snapshot,
-            Duration::from_secs(12),
-            Some("network timeout"),
-        );
-
-        assert!(started.contains("planning started"));
-        assert!(started.contains("current step 3"));
-        assert!(heartbeat.contains("heartbeat"));
-        assert!(heartbeat.contains("9s elapsed"));
-        assert!(heartbeat.contains("phase running read_file"));
-        assert!(completed.contains("completed"));
-        assert!(completed.contains("3 steps total"));
-        assert!(failed.contains("failed"));
-        assert!(failed.contains("network timeout"));
-    }
-
-    #[test]
-    fn describe_tool_progress_summarizes_known_tools() {
-        assert_eq!(
-            describe_tool_progress("read_file", r#"{"path":"src/main.rs"}"#),
-            "reading src/main.rs"
-        );
-        assert!(
-            describe_tool_progress("bash", r#"{"command":"cargo test -p rusty-claude-cli"}"#)
-                .contains("cargo test -p rusty-claude-cli")
-        );
-        assert_eq!(
-            describe_tool_progress("grep_search", r#"{"pattern":"ultraplan","path":"rust"}"#),
-            "grep `ultraplan` in rust"
-        );
-    }
-
-    #[test]
-    fn push_output_block_renders_markdown_text() {
-        let mut out = Vec::new();
-        let mut events = Vec::new();
-        let mut pending_tool = None;
-        let mut block_has_thinking_summary = false;
-
-        push_output_block(
-            OutputContentBlock::Text {
-                text: "# Heading".to_string(),
-            },
-            &mut out,
-            &mut events,
-            &mut pending_tool,
-            false,
-            &mut block_has_thinking_summary,
-        )
-        .expect("text block should render");
-
-        let rendered = String::from_utf8(out).expect("utf8");
-        assert!(rendered.contains("Heading"));
-        assert!(rendered.contains('\u{1b}'));
-    }
-
-    #[test]
-    fn push_output_block_skips_empty_object_prefix_for_tool_streams() {
-        let mut out = Vec::new();
-        let mut events = Vec::new();
-        let mut pending_tool = None;
-        let mut block_has_thinking_summary = false;
-
-        push_output_block(
-            OutputContentBlock::ToolUse {
-                id: "tool-1".to_string(),
-                name: "read_file".to_string(),
-                input: json!({}),
-            },
-            &mut out,
-            &mut events,
-            &mut pending_tool,
-            true,
-            &mut block_has_thinking_summary,
-        )
-        .expect("tool block should accumulate");
-
-        assert!(events.is_empty());
-        assert_eq!(
-            pending_tool,
-            Some(("tool-1".to_string(), "read_file".to_string(), String::new(),))
-        );
-    }
-
-    #[test]
-    fn response_to_events_preserves_empty_object_json_input_outside_streaming() {
-        let mut out = Vec::new();
-        let events = response_to_events(
-            MessageResponse {
-                id: "msg-1".to_string(),
-                kind: "message".to_string(),
-                model: "claude-opus-4-6".to_string(),
-                role: "assistant".to_string(),
-                content: vec![OutputContentBlock::ToolUse {
-                    id: "tool-1".to_string(),
-                    name: "read_file".to_string(),
-                    input: json!({}),
-                }],
-                stop_reason: Some("tool_use".to_string()),
-                stop_sequence: None,
-                usage: Usage {
-                    input_tokens: 1,
-                    output_tokens: 1,
-                    cache_creation_input_tokens: 0,
-                    cache_read_input_tokens: 0,
-                },
-                request_id: None,
-            },
-            &mut out,
-        )
-        .expect("response conversion should succeed");
-
-        assert!(matches!(
-            &events[0],
-            AssistantEvent::ToolUse { name, input, .. }
-                if name == "read_file" && input == "{}"
-        ));
-    }
-
-    #[test]
-    fn response_to_events_preserves_non_empty_json_input_outside_streaming() {
-        let mut out = Vec::new();
-        let events = response_to_events(
-            MessageResponse {
-                id: "msg-2".to_string(),
-                kind: "message".to_string(),
-                model: "claude-opus-4-6".to_string(),
-                role: "assistant".to_string(),
-                content: vec![OutputContentBlock::ToolUse {
-                    id: "tool-2".to_string(),
-                    name: "read_file".to_string(),
-                    input: json!({ "path": "rust/Cargo.toml" }),
-                }],
-                stop_reason: Some("tool_use".to_string()),
-                stop_sequence: None,
-                usage: Usage {
-                    input_tokens: 1,
-                    output_tokens: 1,
-                    cache_creation_input_tokens: 0,
-                    cache_read_input_tokens: 0,
-                },
-                request_id: None,
-            },
-            &mut out,
-        )
-        .expect("response conversion should succeed");
-
-        assert!(matches!(
-            &events[0],
-            AssistantEvent::ToolUse { name, input, .. }
-                if name == "read_file" && input == "{\"path\":\"rust/Cargo.toml\"}"
-        ));
-    }
-
-    #[test]
-    fn response_to_events_renders_collapsed_thinking_summary() {
-        let mut out = Vec::new();
-        let events = response_to_events(
-            MessageResponse {
-                id: "msg-3".to_string(),
-                kind: "message".to_string(),
-                model: "claude-opus-4-6".to_string(),
-                role: "assistant".to_string(),
-                content: vec![
-                    OutputContentBlock::Thinking {
-                        thinking: "step 1".to_string(),
-                        signature: Some("sig_123".to_string()),
-                    },
-                    OutputContentBlock::Text {
-                        text: "Final answer".to_string(),
-                    },
-                ],
-                stop_reason: Some("end_turn".to_string()),
-                stop_sequence: None,
-                usage: Usage {
-                    input_tokens: 1,
-                    output_tokens: 1,
-                    cache_creation_input_tokens: 0,
-                    cache_read_input_tokens: 0,
-                },
-                request_id: None,
-            },
-            &mut out,
-        )
-        .expect("response conversion should succeed");
-
-        assert!(matches!(
-            &events[0],
-            AssistantEvent::TextDelta(text) if text == "Final answer"
-        ));
-        let rendered = String::from_utf8(out).expect("utf8");
-        assert!(rendered.contains("▶ Thinking (6 chars hidden)"));
-        assert!(!rendered.contains("step 1"));
-    }
-
-    #[test]
-    fn login_browser_failure_keeps_json_stdout_clean() {
-        let mut stdout = Vec::new();
-        let mut stderr = Vec::new();
-        let error = std::io::Error::new(
-            std::io::ErrorKind::NotFound,
-            "no supported browser opener command found",
-        );
-
-        super::emit_login_browser_open_failure(
-            CliOutputFormat::Json,
-            "https://example.test/oauth/authorize",
-            &error,
-            &mut stdout,
-            &mut stderr,
-        )
-        .expect("browser warning should render");
-
-        assert!(stdout.is_empty());
-        let stderr = String::from_utf8(stderr).expect("utf8");
-        assert!(stderr.contains("failed to open browser automatically"));
-        assert!(stderr.contains("Open this URL manually:"));
-        assert!(stderr.contains("https://example.test/oauth/authorize"));
-    }
-
-    #[test]
-    fn build_runtime_plugin_state_merges_plugin_hooks_into_runtime_features() {
-        let config_home = temp_dir();
-        let workspace = temp_dir();
-        let source_root = temp_dir();
-        fs::create_dir_all(&config_home).expect("config home");
-        fs::create_dir_all(&workspace).expect("workspace");
-        fs::create_dir_all(&source_root).expect("source root");
-        write_plugin_fixture(&source_root, "hook-runtime-demo", true, false);
-
-        let mut manager = PluginManager::new(PluginManagerConfig::new(&config_home));
-        manager
-            .install(source_root.to_str().expect("utf8 source path"))
-            .expect("plugin install should succeed");
-        let loader = ConfigLoader::new(&workspace, &config_home);
-        let runtime_config = loader.load().expect("runtime config should load");
-        let state = build_runtime_plugin_state_with_loader(&workspace, &loader, &runtime_config)
-            .expect("plugin state should load");
-        let pre_hooks = state.feature_config.hooks().pre_tool_use();
-        assert_eq!(pre_hooks.len(), 1);
-        assert!(
-            pre_hooks[0].ends_with("hooks/pre.sh"),
-            "expected installed plugin hook path, got {pre_hooks:?}"
-        );
-
-        let _ = fs::remove_dir_all(config_home);
-        let _ = fs::remove_dir_all(workspace);
-        let _ = fs::remove_dir_all(source_root);
-    }
-
-    #[test]
-    #[allow(clippy::too_many_lines)]
-    fn build_runtime_plugin_state_discovers_mcp_tools_and_surfaces_pending_servers() {
-        let config_home = temp_dir();
-        let workspace = temp_dir();
-        fs::create_dir_all(&config_home).expect("config home");
-        fs::create_dir_all(&workspace).expect("workspace");
-        let script_path = workspace.join("fixture-mcp.py");
-        write_mcp_server_fixture(&script_path);
-        fs::write(
-            config_home.join("settings.json"),
-            format!(
-                r#"{{
-                  "mcpServers": {{
-                    "alpha": {{
-                      "command": "python3",
-                      "args": ["{}"]
-                    }},
-                    "broken": {{
-                      "command": "python3",
-                      "args": ["-c", "import sys; sys.exit(0)"]
-                    }}
-                  }}
-                }}"#,
-                script_path.to_string_lossy()
-            ),
-        )
-        .expect("write mcp settings");
-
-        let loader = ConfigLoader::new(&workspace, &config_home);
-        let runtime_config = loader.load().expect("runtime config should load");
-        let state = build_runtime_plugin_state_with_loader(&workspace, &loader, &runtime_config)
-            .expect("runtime plugin state should load");
-
-        let allowed = state
-            .tool_registry
-            .normalize_allowed_tools(&["mcp__alpha__echo".to_string(), "MCPTool".to_string()])
-            .expect("mcp tools should be allow-listable")
-            .expect("allow-list should exist");
-        assert!(allowed.contains("mcp__alpha__echo"));
-        assert!(allowed.contains("MCPTool"));
-
-        let mut executor = CliToolExecutor::new(
-            None,
-            false,
-            state.tool_registry.clone(),
-            state.mcp_state.clone(),
-        );
-
-        let tool_output = executor
-            .execute("mcp__alpha__echo", r#"{"text":"hello"}"#)
-            .expect("discovered mcp tool should execute");
-        let tool_json: serde_json::Value =
-            serde_json::from_str(&tool_output).expect("tool output should be json");
-        assert_eq!(tool_json["structuredContent"]["echoed"], "hello");
-
-        let wrapped_output = executor
-            .execute(
-                "MCPTool",
-                r#"{"qualifiedName":"mcp__alpha__echo","arguments":{"text":"wrapped"}}"#,
-            )
-            .expect("generic mcp wrapper should execute");
-        let wrapped_json: serde_json::Value =
-            serde_json::from_str(&wrapped_output).expect("wrapped output should be json");
-        assert_eq!(wrapped_json["structuredContent"]["echoed"], "wrapped");
-
-        let search_output = executor
-            .execute("ToolSearch", r#"{"query":"alpha echo","max_results":5}"#)
-            .expect("tool search should execute");
-        let search_json: serde_json::Value =
-            serde_json::from_str(&search_output).expect("search output should be json");
-        assert_eq!(search_json["matches"][0], "mcp__alpha__echo");
-        assert_eq!(search_json["pending_mcp_servers"][0], "broken");
-        assert_eq!(
-            search_json["mcp_degraded"]["failed_servers"][0]["server_name"],
-            "broken"
-        );
-        assert_eq!(
-            search_json["mcp_degraded"]["failed_servers"][0]["phase"],
-            "tool_discovery"
-        );
-        assert_eq!(
-            search_json["mcp_degraded"]["available_tools"][0],
-            "mcp__alpha__echo"
-        );
-
-        let listed = executor
-            .execute("ListMcpResourcesTool", r#"{"server":"alpha"}"#)
-            .expect("resources should list");
-        let listed_json: serde_json::Value =
-            serde_json::from_str(&listed).expect("resource output should be json");
-        assert_eq!(listed_json["resources"][0]["uri"], "file://guide.txt");
-
-        let read = executor
-            .execute(
-                "ReadMcpResourceTool",
-                r#"{"server":"alpha","uri":"file://guide.txt"}"#,
-            )
-            .expect("resource should read");
-        let read_json: serde_json::Value =
-            serde_json::from_str(&read).expect("resource read output should be json");
-        assert_eq!(
-            read_json["contents"][0]["text"],
-            "contents for file://guide.txt"
-        );
-
-        if let Some(mcp_state) = state.mcp_state {
-            mcp_state
-                .lock()
-                .unwrap_or_else(std::sync::PoisonError::into_inner)
-                .shutdown()
-                .expect("mcp shutdown should succeed");
-        }
-
-        let _ = fs::remove_dir_all(config_home);
-        let _ = fs::remove_dir_all(workspace);
-    }
-
-    #[test]
-    fn build_runtime_plugin_state_surfaces_unsupported_mcp_servers_structurally() {
-        let config_home = temp_dir();
-        let workspace = temp_dir();
-        fs::create_dir_all(&config_home).expect("config home");
-        fs::create_dir_all(&workspace).expect("workspace");
-        fs::write(
-            config_home.join("settings.json"),
-            r#"{
-              "mcpServers": {
-                "remote": {
-                  "url": "https://example.test/mcp"
-                }
-              }
-            }"#,
-        )
-        .expect("write mcp settings");
-
-        let loader = ConfigLoader::new(&workspace, &config_home);
-        let runtime_config = loader.load().expect("runtime config should load");
-        let state = build_runtime_plugin_state_with_loader(&workspace, &loader, &runtime_config)
-            .expect("runtime plugin state should load");
-        let mut executor = CliToolExecutor::new(
-            None,
-            false,
-            state.tool_registry.clone(),
-            state.mcp_state.clone(),
-        );
-
-        let search_output = executor
-            .execute("ToolSearch", r#"{"query":"remote","max_results":5}"#)
-            .expect("tool search should execute");
-        let search_json: serde_json::Value =
-            serde_json::from_str(&search_output).expect("search output should be json");
-        assert_eq!(search_json["pending_mcp_servers"][0], "remote");
-        assert_eq!(
-            search_json["mcp_degraded"]["failed_servers"][0]["server_name"],
-            "remote"
-        );
-        assert_eq!(
-            search_json["mcp_degraded"]["failed_servers"][0]["phase"],
-            "server_registration"
-        );
-        assert_eq!(
-            search_json["mcp_degraded"]["failed_servers"][0]["error"]["context"]["transport"],
-            "http"
-        );
-
-        let _ = fs::remove_dir_all(config_home);
-        let _ = fs::remove_dir_all(workspace);
-    }
-
-    #[test]
-    fn build_runtime_runs_plugin_lifecycle_init_and_shutdown() {
-        // Serialize access to process-wide env vars so parallel tests that
-        // set/remove ANTHROPIC_API_KEY do not race with this test.
-        let _guard = env_lock();
-        let config_home = temp_dir();
-        // Inject a dummy API key so runtime construction succeeds without real credentials.
-        // This test only exercises plugin lifecycle (init/shutdown), never calls the API.
-        std::env::set_var("ANTHROPIC_API_KEY", "test-dummy-key-for-plugin-lifecycle");
-        let workspace = temp_dir();
-        let source_root = temp_dir();
-        fs::create_dir_all(&config_home).expect("config home");
-        fs::create_dir_all(&workspace).expect("workspace");
-        fs::create_dir_all(&source_root).expect("source root");
-        write_plugin_fixture(&source_root, "lifecycle-runtime-demo", false, true);
-
-        let mut manager = PluginManager::new(PluginManagerConfig::new(&config_home));
-        let install = manager
-            .install(source_root.to_str().expect("utf8 source path"))
-            .expect("plugin install should succeed");
-        let log_path = install.install_path.join("lifecycle.log");
-        let loader = ConfigLoader::new(&workspace, &config_home);
-        let runtime_config = loader.load().expect("runtime config should load");
-        let runtime_plugin_state =
-            build_runtime_plugin_state_with_loader(&workspace, &loader, &runtime_config)
-                .expect("plugin state should load");
-        let mut runtime = build_runtime_with_plugin_state(
-            Session::new(),
-            "runtime-plugin-lifecycle",
-            DEFAULT_MODEL.to_string(),
-            vec!["test system prompt".to_string()],
-            true,
-            false,
-            None,
-            PermissionMode::DangerFullAccess,
-            None,
-            runtime_plugin_state,
-        )
-        .expect("runtime should build");
-
-        assert_eq!(
-            fs::read_to_string(&log_path).expect("init log should exist"),
-            "init\n"
-        );
-
-        runtime
-            .shutdown_plugins()
-            .expect("plugin shutdown should succeed");
-
-        assert_eq!(
-            fs::read_to_string(&log_path).expect("shutdown log should exist"),
-            "init\nshutdown\n"
-        );
-
-        let _ = fs::remove_dir_all(config_home);
-        let _ = fs::remove_dir_all(workspace);
-        let _ = fs::remove_dir_all(source_root);
-        std::env::remove_var("ANTHROPIC_API_KEY");
-    }
-}
-
-fn write_mcp_server_fixture(script_path: &Path) {
-    let script = [
-            "#!/usr/bin/env python3",
-            "import json, sys",
-            "",
-            "def read_message():",
-            "    header = b''",
-            r"    while not header.endswith(b'\r\n\r\n'):",
-            "        chunk = sys.stdin.buffer.read(1)",
-            "        if not chunk:",
-            "            return None",
-            "        header += chunk",
-            "    length = 0",
-            r"    for line in header.decode().split('\r\n'):",
-            r"        if line.lower().startswith('content-length:'):",
-            "            length = int(line.split(':', 1)[1].strip())",
-            "    payload = sys.stdin.buffer.read(length)",
-            "    return json.loads(payload.decode())",
-            "",
-            "def send_message(message):",
-            "    payload = json.dumps(message).encode()",
-            r"    sys.stdout.buffer.write(f'Content-Length: {len(payload)}\r\n\r\n'.encode() + payload)",
-            "    sys.stdout.buffer.flush()",
-            "",
-            "while True:",
-            "    request = read_message()",
-            "    if request is None:",
-            "        break",
-            "    method = request['method']",
-            "    if method == 'initialize':",
-            "        send_message({",
-            "            'jsonrpc': '2.0',",
-            "            'id': request['id'],",
-            "            'result': {",
-            "                'protocolVersion': request['params']['protocolVersion'],",
-            "                'capabilities': {'tools': {}, 'resources': {}},",
-            "                'serverInfo': {'name': 'fixture', 'version': '1.0.0'}",
-            "            }",
-            "        })",
-            "    elif method == 'tools/list':",
-            "        send_message({",
-            "            'jsonrpc': '2.0',",
-            "            'id': request['id'],",
-            "            'result': {",
-            "                'tools': [",
-            "                    {",
-            "                        'name': 'echo',",
-            "                        'description': 'Echo from MCP fixture',",
-            "                        'inputSchema': {",
-            "                            'type': 'object',",
-            "                            'properties': {'text': {'type': 'string'}},",
-            "                            'required': ['text'],",
-            "                            'additionalProperties': False",
-            "                        },",
-            "                        'annotations': {'readOnlyHint': True}",
-            "                    }",
-            "                ]",
-            "            }",
-            "        })",
-            "    elif method == 'tools/call':",
-            "        args = request['params'].get('arguments') or {}",
-            "        send_message({",
-            "            'jsonrpc': '2.0',",
-            "            'id': request['id'],",
-            "            'result': {",
-            "                'content': [{'type': 'text', 'text': f\"echo:{args.get('text', '')}\"}],",
-            "                'structuredContent': {'echoed': args.get('text', '')},",
-            "                'isError': False",
-            "            }",
-            "        })",
-            "    elif method == 'resources/list':",
-            "        send_message({",
-            "            'jsonrpc': '2.0',",
-            "            'id': request['id'],",
-            "            'result': {",
-            "                'resources': [{'uri': 'file://guide.txt', 'name': 'guide', 'mimeType': 'text/plain'}]",
-            "            }",
-            "        })",
-            "    elif method == 'resources/read':",
-            "        uri = request['params']['uri']",
-            "        send_message({",
-            "            'jsonrpc': '2.0',",
-            "            'id': request['id'],",
-            "            'result': {",
-            "                'contents': [{'uri': uri, 'mimeType': 'text/plain', 'text': f'contents for {uri}'}]",
-            "            }",
-            "        })",
-            "    else:",
-            "        send_message({",
-            "            'jsonrpc': '2.0',",
-            "            'id': request['id'],",
-            "            'error': {'code': -32601, 'message': method}",
-            "        })",
-            "",
-        ]
-        .join("\n");
-    fs::write(script_path, script).expect("mcp fixture script should write");
-}
-
-#[cfg(test)]
-mod sandbox_report_tests {
-    use super::{format_sandbox_report, HookAbortMonitor};
-    use runtime::HookAbortSignal;
-    use std::sync::mpsc;
-    use std::time::Duration;
-
-    #[test]
-    fn sandbox_report_renders_expected_fields() {
-        let report = format_sandbox_report(&runtime::SandboxStatus::default());
-        assert!(report.contains("Sandbox"));
-        assert!(report.contains("Enabled"));
-        assert!(report.contains("Filesystem mode"));
-        assert!(report.contains("Fallback reason"));
-    }
-
-    #[test]
-    fn hook_abort_monitor_stops_without_aborting() {
-        let abort_signal = HookAbortSignal::new();
-        let (ready_tx, ready_rx) = mpsc::channel();
-        let monitor = HookAbortMonitor::spawn_with_waiter(
-            abort_signal.clone(),
-            move |stop_rx, abort_signal| {
-                ready_tx.send(()).expect("ready signal");
-                let _ = stop_rx.recv();
-                assert!(!abort_signal.is_aborted());
-            },
-        );
-
-        ready_rx.recv().expect("waiter should be ready");
-        monitor.stop();
-
-        assert!(!abort_signal.is_aborted());
-    }
-
-    #[test]
-    fn hook_abort_monitor_propagates_interrupt() {
-        let abort_signal = HookAbortSignal::new();
-        let (done_tx, done_rx) = mpsc::channel();
-        let monitor = HookAbortMonitor::spawn_with_waiter(
-            abort_signal.clone(),
-            move |_stop_rx, abort_signal| {
-                abort_signal.abort();
-                done_tx.send(()).expect("done signal");
-            },
-        );
-
-        done_rx
-            .recv_timeout(Duration::from_secs(1))
-            .expect("interrupt should complete");
-        monitor.stop();
-
-        assert!(abort_signal.is_aborted());
-    }
-}