hexdaemon · santyr · Feb 6, 2026 · Feb 6, 2026 · Feb 7, 2026 · Feb 7, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,42 @@
 
 All notable changes to cl-hive will be documented in this file.
 
+## [Unreleased]
+
+### Fixed
+- **Ban Enforcement**: Fixed ban enforcement race conditions and stigmergic marker thread safety (e94f63f)
+- **Coordinated Splicing**: Fixed 6 bugs across splice_manager, splice_coordinator, and PSBT exchange (e1660c7)
+- **Anticipatory Liquidity + NNLB**: Thread safety fixes, AttributeError on missing keys, key mismatch in pattern detection (4ecabac)
+- **Intent Lock + MCF**: Thread safety, TOCTOU race condition, TypeError and AttributeError fixes (6423375)
+- **HiveMap + Planner**: Feerate gate validation, freshness checks, defensive copies (f8f07f3)
+- **MCF Coordination**: TypeError crashes, missing permission checks, encapsulation violations (64c9c0d)
+- **Cooperative Rebalancing**: 10 bugs in crashes, thread safety, routing, MCF (656466e)
+- **Pheromone Fee Learning**: Repaired broken loop between cl-hive and cl-revenue-ops (fb9c471)
+- **State Manager**: Added capabilities field validation in state entries (d818771)
+- **MCF Assignments**: Replaced private _mcf_assignments access with public API (cf37109)
+
+## [2.2.8] - 2026-02-07
+
+### Added
+- vitality plugin v0.2.3 for automatic plugin health monitoring and restart
+- Thread safety locks in 7 coordination modules (AdaptiveFeeController, StigmergicCoordinator, MyceliumDefenseSystem, TimeBasedFeeAdjuster, FeeCoordinationManager, VPNTransportManager)
+- Cache bounds to prevent memory bloat (500-1000 entry limits on peer/route caches)
+- Docker image version 2.2.8
+
+### Fixed
+- **Thread Safety**: Fixed race conditions in concurrent modification of shared state
+- **Governance Bypass**: task_manager expansion now routes through governance engine (security)
+- **Outbox Retry**: Parse/serialization errors now fail permanently instead of infinite retry
+- **P0 Crashes**: Fixed AttributeError on _get_topology_snapshot() and None handling in task execution
+- **P1 Logic Errors**: Fixed analyzer references, field names, method calls across 12 modules
+- **P2 Edge Cases**: MCF solution validation, force_close counting, yield metric clamping
+
+### Removed
+- trustedcoin plugin (explorer-only Bitcoin backend no longer needed)
+
+### Changed
+- Updated .env.example documentation to reflect vitality instead of trustedcoin
+
 ## [1.9.0] - 2026-01-24
 
 ### Added

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -41,7 +41,7 @@ Core Lightning
 - **cl-revenue-ops**: Executes fee policies and rebalancing (called via RPC)
 - **Core Lightning**: Underlying node operations and HSM-based crypto
 
-### Module Organization
+### Module Organization (41 modules)
 
 | Module | Purpose |
 |--------|---------|
@@ -56,12 +56,36 @@ Core Lightning
 | `contribution.py` | Forwarding stats and anti-leech detection |
 | `planner.py` | Topology optimization - saturation analysis, expansion election, feerate gate |
 | `splice_manager.py` | Coordinated splice operations between hive members (Phase 11) |
+| `splice_coordinator.py` | High-level splice coordination and recommendation engine |
 | `mcf_solver.py` | Min-Cost Max-Flow solver for global fleet rebalance optimization |
 | `liquidity_coordinator.py` | Liquidity needs aggregation and rebalance assignment distribution |
 | `cost_reduction.py` | Fleet rebalance routing with MCF/BFS fallback |
-| `anticipatory_manager.py` | Kalman-filtered flow prediction, intra-day pattern detection |
+| `anticipatory_liquidity.py` | Kalman-filtered flow prediction, intra-day pattern detection |
+| `fee_coordination.py` | Pheromone-based fee coordination + stigmergic markers |
+| `fee_intelligence.py` | Fee intelligence aggregation and sharing across fleet |
+| `cooperative_expansion.py` | Fleet-wide expansion election protocol (Nominate→Elect→Open) |
+| `budget_manager.py` | Autonomous/failsafe mode budget tracking and enforcement |
+| `idempotency.py` | Message deduplication via event ID tracking |
+| `outbox.py` | Reliable message delivery with retry and exponential backoff |
+| `routing_intelligence.py` | Routing path intelligence sharing across fleet |
+| `routing_pool.py` | Routing pool management for fee distribution |
+| `settlement.py` | BOLT12 settlement system - proposal/vote/execute consensus |
+| `health_aggregator.py` | Fleet health scoring and NNLB status |
+| `network_metrics.py` | Network-level metrics collection |
+| `peer_reputation.py` | Peer reputation tracking and scoring |
+| `quality_scorer.py` | Peer quality scoring for membership decisions |
+| `relay.py` | Message relay logic for multi-hop fleet communication |
+| `rpc_commands.py` | RPC command handlers for all hive-* commands |
+| `channel_rationalization.py` | Channel optimization recommendations |
+| `strategic_positioning.py` | Strategic network positioning analysis |
+| `task_manager.py` | Background task coordination and scheduling |
+| `vpn_transport.py` | VPN transport layer (WireGuard integration) |
+| `yield_metrics.py` | Yield tracking and optimization metrics |
+| `governance.py` | Decision engine (advisor/failsafe mode routing) |
 | `config.py` | Hot-reloadable configuration with snapshot pattern |
-| `database.py` | SQLite with WAL mode, thread-local connections |
+| `did_credentials.py` | DID credential issuance, verification, reputation aggregation (Phase 16) |
+| `management_schemas.py` | 15 management schema categories, danger scoring, credential lifecycle (Phase 2) |
+| `database.py` | SQLite with WAL mode, thread-local connections, 50 tables |
 
 ### Key Patterns
 
@@ -87,14 +111,25 @@ Core Lightning
 - "Peek & Check" pattern in custommsg hook
 - JSON payload, max 65535 bytes per message
 
+**Idempotent Delivery**:
+- All protocol messages carry unique event IDs
+- `proto_events` table tracks processed events
+- `proto_outbox` table enables reliable retry with exponential backoff
+
+**Relay Protocol**:
+- Multi-hop message relay for peers not directly connected
+- Relay logic in `relay.py` with TTL-based loop prevention
+
 ### Governance Modes
 
 | Mode | Behavior |
 |------|----------|
 | `advisor` | **Primary mode** - Queue to pending_actions for AI/human approval via MCP server |
 | `failsafe` | Emergency mode - Auto-execute only critical safety actions (bans) within strict limits |
 
-### Database Tables
+### Database Tables (50 tables)
+
+Key tables (see `database.py` for complete schema):
 
 | Table | Purpose |
 |-------|---------|
@@ -103,10 +138,29 @@ Core Lightning
 | `hive_state` | Key-value store for persistent state |
 | `contribution_ledger` | Forwarding contribution tracking |
 | `hive_bans` | Ban proposals and votes |
-| `promotion_requests` | Pending promotion requests |
+| `ban_proposals` / `ban_votes` | Distributed ban voting |
+| `promotion_requests` / `promotion_vouches` | Promotion workflow |
 | `hive_planner_log` | Planner decision audit log |
 | `pending_actions` | Actions awaiting approval (advisor mode) |
-| `splice_sessions` | Active and historical splice operations (Phase 11) |
+| `splice_sessions` | Active and historical splice operations |
+| `peer_fee_profiles` | Fee profiles shared by fleet members |
+| `fee_intelligence` | Aggregated fee intelligence data |
+| `fee_reports` | Fee earnings for settlement calculations |
+| `liquidity_needs` / `member_liquidity_state` | Liquidity coordination |
+| `pool_contributions` / `pool_revenue` / `pool_distributions` | Routing pool management |
+| `settlement_proposals` / `settlement_ready_votes` / `settlement_executions` | BOLT12 settlement |
+| `flow_samples` / `temporal_patterns` | Anticipatory liquidity data |
+| `peer_reputation` | Peer reputation scores |
+| `member_health` | Fleet member health tracking |
+| `budget_tracking` / `budget_holds` | Budget enforcement |
+| `proto_events` | Processed event IDs for idempotency |
+| `proto_outbox` | Reliable message delivery outbox |
+| `peer_presence` | Peer online/offline tracking |
+| `peer_capabilities` | Peer protocol capabilities |
+| `did_credentials` | DID reputation credentials (issued and received) |
+| `did_reputation_cache` | Cached aggregated reputation scores |
+| `management_credentials` | Management credentials (operator → agent permission) |
+| `management_receipts` | Signed receipts of management action executions |
 
 ## Safety Constraints
 
@@ -162,7 +216,7 @@ Note: Sling IS required for cl-revenue-ops itself.
 - Only external dependency: `pyln-client>=24.0`
 - All crypto done via CLN HSM (signmessage/checkmessage) - no crypto libs imported
 - Plugin options defined at top of `cl-hive.py` (30 configurable parameters)
-- Background loops: intent_monitor_loop, membership_loop, planner_loop, gossip_loop
+- Background loops (9): gossip_loop, membership_maintenance_loop, planner_loop, intent_monitor_loop, fee_intelligence_loop, settlement_loop, mcf_optimization_loop, outbox_retry_loop, did_maintenance_loop
 
 ## Testing Conventions
 
@@ -176,29 +230,56 @@ Note: Sling IS required for cl-revenue-ops itself.
 ```
 cl-hive/
 ├── cl-hive.py              # Main plugin entry point
-├── modules/
+├── modules/                # 41 modules
 │   ├── protocol.py         # Message types and encoding
 │   ├── handshake.py        # PKI authentication
-│   ├── state_manager.py    # Distributed state
+│   ├── state_manager.py    # Distributed state (HiveMap)
 │   ├── gossip.py           # Gossip protocol
 │   ├── intent_manager.py   # Intent locks
-│   ├── bridge.py           # cl-revenue-ops bridge
+│   ├── bridge.py           # cl-revenue-ops bridge (Circuit Breaker)
 │   ├── clboss_bridge.py    # Optional CLBoss bridge
 │   ├── membership.py       # Member management
 │   ├── contribution.py     # Contribution tracking
 │   ├── planner.py          # Topology planner
+│   ├── cooperative_expansion.py  # Fleet expansion elections
 │   ├── splice_manager.py   # Coordinated splice operations
+│   ├── splice_coordinator.py    # Splice coordination engine
+│   ├── mcf_solver.py       # Min-Cost Max-Flow solver
+│   ├── liquidity_coordinator.py # Liquidity needs aggregation
+│   ├── cost_reduction.py   # Fleet rebalance routing
+│   ├── anticipatory_liquidity.py # Kalman-filtered flow prediction
+│   ├── fee_coordination.py # Pheromone-based fee coordination
+│   ├── fee_intelligence.py # Fee intelligence sharing
+│   ├── settlement.py       # BOLT12 settlement system
+│   ├── routing_intelligence.py  # Routing path intelligence
+│   ├── routing_pool.py     # Routing pool management
+│   ├── budget_manager.py   # Budget tracking and enforcement
+│   ├── idempotency.py      # Message deduplication
+│   ├── outbox.py           # Reliable message delivery
+│   ├── relay.py            # Message relay logic
+│   ├── health_aggregator.py    # Fleet health scoring
+│   ├── network_metrics.py  # Network metrics collection
+│   ├── peer_reputation.py  # Peer reputation tracking
+│   ├── quality_scorer.py   # Peer quality scoring
+│   ├── channel_rationalization.py # Channel optimization
+│   ├── strategic_positioning.py   # Network positioning
+│   ├── yield_metrics.py    # Yield tracking
+│   ├── task_manager.py     # Background task coordination
+│   ├── vpn_transport.py    # VPN transport layer
+│   ├── rpc_commands.py     # RPC command handlers
 │   ├── governance.py       # Decision engine (advisor/failsafe)
+│   ├── did_credentials.py  # DID credential issuance + reputation (Phase 16)
+│   ├── management_schemas.py # Management schemas + danger scoring (Phase 2)
 │   ├── config.py           # Configuration
-│   └── database.py         # Database layer
+│   └── database.py         # Database layer (50 tables)
 ├── tools/
 │   ├── mcp-hive-server.py  # MCP server for Claude Code integration
 │   ├── hive-monitor.py     # Real-time monitoring daemon
 │   └── ai_advisor.py       # AI advisor utility
 ├── config/
 │   ├── nodes.rest.example.json    # REST API config example
 │   └── nodes.docker.example.json  # Docker/Polar config example
-├── tests/                  # Test suite
+├── tests/                  # 1,918 tests across 48 files
 ├── docs/                   # Documentation
 │   ├── design/             # Design documents
 │   ├── planning/           # Implementation plans

diff --git a/MOLTY.md b/MOLTY.md
@@ -231,5 +231,5 @@ See `CLAUDE.md` for detailed development guidance.
 ## Related Documentation
 
 - [MCP_SERVER.md](docs/MCP_SERVER.md) — Full tool reference
-- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — Protocol specification
+- [hive-docs](https://github.com/lightning-goats/hive-docs) — Full documentation (architecture, specs, planning)
 - [CLAUDE.md](CLAUDE.md) — Development guidance
diff --git a/README.md b/README.md
@@ -50,15 +50,30 @@ Global fleet-wide rebalancing optimization using Successive Shortest Paths algor
 ### Anticipatory Liquidity Management
 Predictive liquidity positioning using Kalman-filtered flow velocity estimation and intra-day pattern detection. Detects temporal patterns (surge, drain, quiet periods) and recommends proactive rebalancing before demand spikes.
 
+### Stigmergic Markers & Pheromone Trails
+Bio-inspired coordination using pheromone-based fee signals. Nodes deposit "scent markers" on channels they route through, creating emergent fee corridors that the fleet collectively optimizes without central planning — similar to how ant colonies find optimal paths.
+
+### Settlement System (BOLT12)
+Decentralized fee distribution using BOLT12 offers. Members propose settlements for completed periods, auto-vote when data hashes match (51% quorum), and each node pays their share. Period-based idempotency prevents double settlement.
+
+### Idempotent Message Delivery & Reliable Outbox
+Deduplication of all protocol messages via event ID tracking. Reliable delivery with automatic retry and exponential backoff ensures messages reach all peers even through transient disconnections.
+
+### Routing Intelligence
+Fleet-wide routing path intelligence sharing. Nodes share probe results and failure data to collectively build a superior view of the network graph, improving payment success rates for the entire fleet.
+
+### Budget Manager
+Autonomous mode budget tracking with per-day spend limits, reserve percentage enforcement, and per-channel spend caps. Prevents runaway spending in failsafe mode.
+
 ### VPN Transport Support
 Optional WireGuard VPN integration for secure fleet communication.
 
 ## Governance Modes
 
 | Mode | Behavior |
 |------|----------|
-| `advisor` | Log recommendations and queue actions for manual approval (default) |
-| `autonomous` | Execute actions automatically within strict safety bounds |
+| `advisor` | Log recommendations and queue actions for AI/human approval via MCP server (default) |
+| `failsafe` | Emergency mode - auto-execute only critical safety actions (bans) within strict limits |
 
 ## Join the Lightning Hive
 
@@ -84,12 +99,14 @@ See [Joining the Hive](docs/JOINING_THE_HIVE.md) for the complete guide.
 
 ### Prerequisites
 - Core Lightning (CLN) v23.05+
-- Python 3.8+
+- Python 3.10+ (required for `match` statements used in newer modules)
 - `cl-revenue-ops` v1.4.0+ (Recommended for full functionality)
 
 ### Optional Integrations
 - **CLBoss**: Not required. If installed, cl-hive coordinates to prevent redundant channel opens.
 - **Sling**: Not required for cl-hive. Rebalancing is handled by cl-revenue-ops.
+- **cl-hive-comms**: Optional Phase 6 sibling plugin (detected automatically when installed).
+- **cl-hive-archon**: Optional Phase 6 Archon sibling plugin. If active without comms, `hive-phase6-plugins` reports a warning.
 
 ### Setup
 
@@ -105,6 +122,8 @@ pip install -r requirements.txt
 lightningd --plugin=/path/to/cl-hive/cl-hive.py
 ```
 
+Phase 6 planning references: see [hive-docs](https://github.com/lightning-goats/hive-docs)
+
 ## RPC Commands
 
 ### Hive Management
@@ -116,9 +135,10 @@ lightningd --plugin=/path/to/cl-hive/cl-hive.py
 | `hive-join <ticket>` | Join an existing Hive using an invitation ticket |
 | `hive-leave` | Leave the current Hive |
 | `hive-status` | Get current membership tier, fleet size, and governance mode |
+| `hive-phase6-plugins` | Show detected optional sibling plugin status (`cl-hive-comms`, `cl-hive-archon`) |
 | `hive-members` | List all Hive members and their current stats |
 | `hive-config` | View current configuration |
-| `hive-set-mode <mode>` | Change governance mode (advisor/autonomous/oracle) |
+| `hive-set-mode <mode>` | Change governance mode (advisor/failsafe) |
 
 ### Membership & Governance
 
@@ -259,7 +279,7 @@ All options can be set in your CLN config file or passed as CLI arguments. Most
 | Option | Default | Description |
 |--------|---------|-------------|
 | `hive-db-path` | `~/.lightning/cl_hive.db` | SQLite database path (immutable) |
-| `hive-governance-mode` | `advisor` | Governance mode: advisor, autonomous, oracle |
+| `hive-governance-mode` | `advisor` | Governance mode: advisor, failsafe |
 | `hive-max-members` | `50` | Maximum Hive members (Dunbar cap) |
 
 ### Membership Settings
@@ -335,20 +355,19 @@ See:
 
 ## Documentation
 
+Full docs: **https://github.com/lightning-goats/hive-docs**
+
 | Document | Description |
 |----------|-------------|
 | [Joining the Hive](docs/JOINING_THE_HIVE.md) | How to join an existing hive |
-| [MOLTY.md](MOLTY.md) | AI agent instructions |
 | [MCP Server](docs/MCP_SERVER.md) | MCP server setup and tool reference |
-| [Cooperative Fee Coordination](docs/design/cooperative-fee-coordination.md) | Fee coordination design |
-| [VPN Transport](docs/design/VPN_HIVE_TRANSPORT.md) | VPN transport design |
-| [Liquidity Integration](docs/design/LIQUIDITY_INTEGRATION.md) | cl-revenue-ops integration |
-| [Architecture](docs/ARCHITECTURE.md) | Complete protocol specification |
+| [MOLTY.md](MOLTY.md) | AI agent instructions |
 | [Docker Deployment](docker/README.md) | Docker deployment guide |
-| [Threat Model](docs/security/THREAT_MODEL.md) | Security threat analysis |
 
 ## Testing
 
+1,340 tests across 46 test files covering all modules.
+
 ```bash
 # Run all tests
 python3 -m pytest tests/
@@ -360,6 +379,19 @@ python3 -m pytest tests/test_planner.py
 python3 -m pytest tests/ -v
 ```
 
+## Recent Hardening
+
+Extensive security and stability work across the codebase:
+
+- **Thread safety**: Locks added to all shared mutable state in coordination modules (fee controllers, stigmergic coordinator, defense system, VPN transport)
+- **Cache bounds**: All peer/route caches bounded to 500-1000 entries to prevent memory bloat
+- **Governance enforcement**: All expansion paths now route through governance engine
+- **Outbox reliability**: Parse/serialization errors fail permanently instead of infinite retry
+- **Crash fixes**: AttributeError, TypeError, and None-handling fixes across 12+ modules
+- **MCF hardening**: Solution validation, force-close counting, coordinator election staleness failover
+- **Splicing fixes**: 6 bugs fixed across splice manager, coordinator, and PSBT exchange
+- **Anticipatory liquidity**: Thread safety, AttributeError fixes, key mismatch corrections
+
 ## License
 
 MIT