slaguru666/AIPass
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(system): docs(prax): comprehensive README update — full rewrite with accurate architecture, commands, API docs, test coverage table

Browse Source 
Co-Authored-By: @devpulse <devpulse@aipass>
This commit is contained in:
AIOSAI
2026-04-22 21:21:53 -07:00
co-authored by @devpulse
parent 192e3563ac
commit 58b7e12b5a
4 changed files with 311 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/hooks/.diagnostics_state.json
-1
View File
@@ -1 +0,0 @@
{"file": "/home/patrick/Projects/AIPass/src/aipass/seedgo/apps/modules/inbox_audit.py", "errors": [{"line": 86, "message": "E501: Line too long (125 > 120)"}]}
src/aipass/memory/README.md
+128 -92
View File
@@ -2,7 +2,7 @@
# MEMORY
**Purpose:** Central memory archive with semantic search, rollover, and archival across all AIPass branches.
**Purpose:** Central memory archive — vector search, rollover, and memory management for all AIPass branches.
**Module:** `aipass.memory`
**Created:** 2026-03-07
**Last Updated:** 2026-04-22
@@ -12,53 +12,58 @@
## Overview
Memory is the central memory archive system that:
- Provides semantic search across all branch memories
- Archives memories when branches hit rollover limits (600 lines)
- Extracts symbolic dimensions from conversations
- Manages template distribution and line-count tracking across branches
Memory is the archival backbone of AIPass. Every branch accumulates session history and learnings in `.trinity/` files. When those files reach capacity, Memory archives the oldest entries into ChromaDB vectors — searchable, permanent, never lost.
What Memory does:
- **Rollover** — detects when `.trinity/local.json` or `observations.json` exceed limits, extracts oldest entries, embeds them via sentence-transformers, stores in ChromaDB, trims the source file
- **Search** — semantic search across all archived branch memories (4+ collections, 2200+ vectors)
- **Templates** — distributes `.trinity/` schema updates across all branches (push, diff, status)
- **Symbolic** — fragmented memory extraction from conversations (demo, analyze, extract, fragments, bootstrap, hook-test)
- **Verify** — checks whether a flow plan is vectorized in ChromaDB
- **Watch** — persistent file watcher that auto-triggers rollover on changes
---
## Commands / Usage
## Commands
All commands via `drone @memory <command>`:
**Via Drone (recommended):**
```bash
# Introspection
drone @memory # Module list, version
drone @memory --help # Full command reference
drone @memory --version # Version string
# Rollover
drone @memory rollover # Show rollover module introspection
drone @memory rollover run # Execute memory rollover for files over limits
drone @memory rollover status # Show rollover statistics for all branches
drone @memory rollover check # Dry run — check which files need rollover
drone @memory rollover sync-lines # Update line count metadata for all branches
drone @memory rollover # Module introspection (handlers + subcommands)
drone @memory rollover run # Execute rollover for files over limits
drone @memory rollover status # Show per-branch rollover statistics
drone @memory rollover check # Dry run — check what needs rollover
drone @memory rollover sync-lines # Update line count metadata for all branches
# Search
drone @memory search "error handling" # Semantic search across all branch memories
drone @memory search "query" --branch SEEDGO # Filter search by branch
drone @memory search "query" --n 10 # Limit number of results
drone @memory search "error handling" # Semantic search across all branch memories
drone @memory search "query" --branch X # Filter search by branch
drone @memory search "query" --n 10 # Limit number of results
# Symbolic (fragmented memory)
drone @memory symbolic # Show symbolic module introspection
drone @memory symbolic demo # Run fragmented memory demonstration
drone @memory symbolic fragments "query" # Search symbolic fragments (not operational — no stored fragments)
drone @memory symbolic extract <file> # Extract fragments via LLM (requires API)
# Symbolic
drone @memory symbolic # Module introspection (6 handlers, subcommands)
drone @memory symbolic demo # Run v1 + v2 mock analysis demonstration
drone @memory symbolic fragments "query" # Search stored symbolic fragments
drone @memory symbolic extract <file> # Extract fragments via LLM (requires API key)
drone @memory symbolic bootstrap # Populate fragments from session JSONLs
drone @memory symbolic hook-test # Test hook with sample conversation text
# Templates (not operational — template files missing)
drone @memory templates # Show templates module introspection
drone @memory templates push-templates # Push template updates to all branches (not operational)
drone @memory templates diff-templates # Show template differences per branch (not operational)
drone @memory templates template-status # Show template version and push status (not operational)
# Templates
drone @memory templates push-templates # Push template updates to all branches
drone @memory templates diff-templates # Show template differences per branch
drone @memory templates template-status # Show template version and push status
# Verify
drone @memory verify FPLAN-XXXX # Check if a plan is vectorized in ChromaDB
drone @memory verify FPLAN-XXXX # Check if plan is vectorized in ChromaDB
# Watch
drone @memory watch # Start auto-rollover watcher (Ctrl+C to stop)
```
**Direct execution:**
```bash
python3 -m aipass.memory.apps.memory search "query"
python3 -m aipass.memory.apps.memory rollover status
drone @memory watch # Auto-rollover watcher daemon (Ctrl+C to stop)
```
---
@@ -67,88 +72,119 @@ python3 -m aipass.memory.apps.memory rollover status
```
memory/
├── __init__.py # Package init
├── README.md # This file
├── DASHBOARD.local.json # System status dashboard
├── pytest.ini # Test configuration
├── .trinity/ # Identity & memory
│ ├── passport.json # Branch identity
│ ├── local.json # Session history (v2 schema, entry-count limits)
│ └── observations.json # Collaboration patterns (v1 schema, line-count limits)
├── .aipass/ # Branch prompt
├── .ai_mail.local/ # Mailbox
├── apps/
│ ├── __init__.py
│ ├── memory.py # Entry point (CLI) — auto-discovers modules
│ ├── modules/
│ │ ├── __init__.py
│ │ ├── rollover.py # Rollover orchestrator — line checks, archival triggers
│ │ ├── search.py # Search orchestrator — semantic query routing
│ │ └── verify.py # Plan verification — check vectorized plan status
│ ├── handlers/
│ │ ├── __init__.py
│ │ ├── central_writer.py # Central memory write operations
│ │ ├── dashboard_push.py # Dashboard status push
│ │ ├── archive/ # Memory archival indexing
│ │ ├── json/ # JSON handler operations
│ │ ├── learnings/ # Learning extraction
│ │ ├── monitor/ # File watcher for auto-rollover
│ │ ├── rollover/ # Rollover implementation logic
│ │ ├── schema/ # Memory schema definitions
│ │ ├── search/ # Search implementation (vector/semantic)
│ │ ├── storage/ # Storage backend operations
│ │ ├── tracking/ # Line count and metadata tracking
│ │ ├── symbolic/ # Symbolic dimension extraction
│ │ ├── templates/ # Template management
│ │ └── vector/ # Vector DB (ChromaDB) operations
│ ├── extensions/ # Extension plugins
│ └── plugins/ # Plugin system
├── artifacts/ # Build/output artifacts
├── docs/ # Documentation
├── memory_json/ # Memory JSON data store
├── tests/ # Test suite
└── tools/ # Utility scripts
│ ├── memory.py # Entry point — auto-discovers modules via handle_command()
│ ├── modules/ # Business logic (5 modules)
│ │ ├── rollover.py # Rollover orchestration, status display, sync-lines
│ │ ├── search.py # Semantic query routing
│ │ ├── verify.py # Plan vectorization check
│ │ ├── symbolic.py # Fragmented memory extraction and search
│ │ └── templates.py # Template push, diff, status
│ └── handlers/ # Implementation (14 handler groups, 35 files)
│ ├── archive/ # indexer.py — memory archival indexing
│ ├── intake/ # plans_processor.py, pool_processor.py — ingest pipelines
│ ├── json/ # json_handler.py, memory_files.py — JSON operations
│ ├── learnings/ # manager.py — learning extraction and management
│ ├── monitor/ # detector.py, memory_watcher.py — rollover detection + auto-trigger
│ ├── rollover/ # extractor.py, orchestrator.py — backup → extract → embed → store
│ ├── schema/ # normalize.py — schema version normalization
│ ├── search/ # query_executor.py, vector_search.py — semantic search impl
│ ├── storage/ # chroma.py, chroma_subprocess.py — ChromaDB backend
│ ├── symbolic/ # 6 handlers — chroma_client, deduplicator, extractor, hook, retriever, storage
│ ├── templates/ # pusher.py, differ.py, spawn_pusher.py — template distribution
│ ├── tracking/ # line_counter.py — metadata line count tracking
│ ├── vector/ # embedder.py, embed_subprocess.py — sentence-transformer embeddings
│ ├── central_writer.py # Central memory write operations
│ └── dashboard_push.py # Dashboard status push
├── config/ # memory_bank.config.json — per-branch rollover limits
├── templates/ # LOCAL.template.json, OBS.template — schema templates
├── tests/ # 450 tests (16/16 module coverage)
├── .chroma/ # Global ChromaDB vector store
└── memory_json/ # Operation log files (auto-created)
```
### Rollover Pipeline
```
startup trigger → check_and_rollover()
→ detector.check_all_branches() # scan AIPASS_REGISTRY.json
→ _should_rollover(file) # v1: line_count >= max_lines
# v2: len(sessions) >= max_sessions, etc.
→ orchestrator.execute_rollover()
→ create_rollover_backup() # safety copy to branch/.backup/
→ extract_items() # v2: max(excess, 1) oldest entries
→ embed via subprocess # sentence-transformers in memory .venv
→ store in ChromaDB # global + local collections
→ trim source file # write back with oldest removed
```
### Dual Schema Support
- **v1** (line-count): `schema_version: "1.0.0"` — triggers at `current_lines >= max_lines` (default 600)
- **v2** (entry-count): `schema_version: "2.0.0"` — triggers at `len(sessions) >= max_sessions` or `len(key_learnings) >= max_key_learnings`. Extractor uses `max(excess, 1)` guard to prevent Python's `list[-0:]` trap.
### Subprocess Isolation
All ML operations (torch, sentence-transformers, chromadb) run via subprocess. The main process never imports these heavy libraries. Each embedding call spawns `memory/.venv/bin/python3` with a self-contained script that reads stdin JSON and writes stdout JSON.
---
## Integration Points
## Dependencies
### Depends On
- `rich` — Console output, panels, and tables
- Python stdlib (`sys`, `time`, `signal`, `logging`, `pathlib`, `importlib`)
### Runtime
- `rich` — console output, panels, tables
- Python stdlib (`json`, `pathlib`, `logging`, `importlib`, `signal`)
- `prax` (internal) — logging via `get_system_logger()`
### ML (in memory `.venv/` only)
- `torch` + `sentence-transformers` — embedding generation
- `chromadb` — vector storage and semantic search
- `numpy` — numerical operations
### Provides To
- All branches — memory rollover, archival, and retrieval services
- All branches — semantic search across branch memories
- All branches — template distribution via `push-templates`
- All branches — line count metadata via `sync-lines`
- All branches — memory rollover and archival when `.trinity/` files hit limits
- All branches — semantic search across archived memories
- All branches — template schema distribution
- All branches — line count metadata sync
---
## Key Modules
## Quality
### rollover
The rollover module monitors memory files across all branches registered in `AIPASS_REGISTRY.json`. When files exceed entry-count limits (20 sessions, 25 key_learnings), it triggers archival — extracting oldest entries, embedding them via subprocess, and storing in ChromaDB vectors. The `watch` command runs a persistent file watcher that auto-triggers rollover on changes.
- **Seedgo:** 100% (33/33 standards) — maintained since s12
- **Tests:** 450 pass, 1 skip (test_vector.py gated with `importorskip` for numpy)
- **Coverage:** 175 public functions, 102 tested (58%), 16/16 modules
- **Type checking:** 35 files, 0 errors
### search
Semantic search across all branch memories using ChromaDB + sentence-transformers. Requires memory `.venv/` with torch installed (~3GB). All ML operations run via subprocess isolation — main process never imports torch.
---
### symbolic *(partial)*
Fragmented memory extraction and search. Demo and introspection work. `fragments` search returns 0 results (no stored fragments). `extract` requires API key. Code is operational but no fragment data has been stored yet.
## Known Issues
### templates *(not operational)*
Living template push system for distributing `.trinity/` schema updates across branches. Template files (`LOCAL.template.json`, `OBS.template`) are missing — all subcommands (`push-templates`, `diff-templates`, `template-status`) fail.
### verify
Checks whether a specific flow plan (FPLAN-XXXX) has been vectorized into ChromaDB. Works correctly.
- `search` requires torch/sentence-transformers in memory `.venv/` — fails without them
- memory_watcher.py at 704 lines (near 700 threshold, bypassed in seedgo)
- symbolic.py at 1604 lines (legacy port, bypassed)
- manager.py at 1076 lines (complex learning extraction, bypassed)
- `memory_threshold_exceeded` trigger event registered but never fired — rollover auto-runs at startup via watcher
- `rollover status` shows 0 branches when `AIPASS_REGISTRY.json` path not resolved
---
## Identity
- **Passport:** `.trinity/passport.json`
- **Session History:** `.trinity/local.json`
- **Observations:** `.trinity/observations.json`
- **Branch Prompt:** `.aipass/branch_system_prompt.md`
- **Session History:** `.trinity/local.json` (v2 schema, 20 sessions max, 25 key_learnings max)
- **Observations:** `.trinity/observations.json` (v1 schema, 600 lines max)
- **Branch Prompt:** `.aipass/aipass_local_prompt.md`
---
*Last Updated: 2026-04-07*
*Last Updated: 2026-04-22*
---
[← Back to AIPass](../../../README.md)
src/aipass/prax/CLOSED_PLANS.local.json
+24 -1
View File
@@ -63,5 +63,28 @@
"date_closed": "2026-04-10",
"location": "prax"
}
]
],
"document_metadata": {
"version": "2.0.0",
"schema_version": "2.0.0",
"document_type": "session_history",
"tags": [
"session_tracking",
"work_log",
"PRAX"
],
"limits": {
"max_sessions": 20,
"max_key_learnings": 25,
"session_summary_max_chars": 150,
"learning_value_max_chars": 200,
"note": "Auto-rollover to @memory when limits exceeded. Oldest entries trimmed first."
},
"status": {
"health": "healthy",
"last_health_check": "2026-04-22",
"current_lines": 0
}
},
"key_learnings": {}
}
src/aipass/prax/README.md
+159 -82
View File
@@ -2,31 +2,20 @@
# PRAX
**Purpose:** System-wide logging, real-time monitoring, and dashboard for AIPass.
**Purpose:** System-wide logging, real-time monitoring, and dashboard infrastructure for AIPass.
**Module:** `aipass.prax`
**Version:** 2.0.0
**Last Updated:** 2026-04-22
---
## Overview
Prax auto-routes log output from any module to per-module log files and provides a live monitoring console (Mission Control) that shows file changes, log events, and command execution across all branches. Monitors Claude Code, Codex, and Gemini CLI sessions.
Prax is the logging and monitoring backbone of the AIPass ecosystem. Any branch imports `logger` and gets automatic log routing — prax detects the caller via stack introspection and writes to the correct per-module log file. No configuration needed.
## Commands
On top of logging, prax provides Mission Control (a real-time terminal console for file changes, log events, and agent activity), a log audit system, a dashboard infrastructure, and cross-branch STATUS.md synchronization.
```bash
drone @prax monitor run # Launch Mission Control
drone @prax status # System health status
drone @prax log-audit audit # Audit log file sizes
drone @prax dashboard # Show dashboard
drone @prax --help # Full help
```
## Usage
### Logging
**Canonical import (use this):**
## Quick Start
```python
from aipass.prax import logger
@@ -36,9 +25,79 @@ logger.warning("Disk usage high")
logger.error("Connection failed")
```
This is Pattern A — the recommended way for all branches. Logs auto-route via two-tier placement: `system_logs/<branch>_<module>.log` (central aggregation) and `<branch>/logs/` (branch-local). No configuration needed — prax detects the caller via stack introspection.
Logs auto-route via two-tier placement:
- `system_logs/<branch>_<module>.log` — central aggregation at the repo root
- `<branch>/logs/<module>.log` — branch-local debugging
For prax handlers that need to bypass the event pipeline (watchdog threads, import-chain files):
## Commands
```bash
drone @prax # Show discovered modules
drone @prax --help # Full command list
drone @prax --version # Version string
```
### Monitor — Mission Control
```bash
drone @prax monitor # Show monitor architecture
drone @prax monitor run # Launch Mission Control (all branches)
drone @prax monitor run seedgo,cli # Monitor specific branches
drone @prax monitor --help # Monitor usage
```
Real-time unified console showing:
- File changes, log events, drone commands, agent activity
- **Caller attribution** — `CALLER → TARGET` for drone commands
- **Model tags** — `[BRANCH/model]` (e.g., `[DEVPULSE/opus]`, `[DEVPULSE/gpt-5.4]`)
- **Multi-CLI** — Claude Code (JSONL), Codex (JSONL), Gemini (JSON) session monitoring
- **Polling fallback** — automatic fallback when inotify watches are exhausted
- **Soft start** — only shows new activity after launch (seeks to EOF on startup)
Interactive commands inside the monitor: `help`, `status`, `quit`/`exit`.
### Status
```bash
drone @prax status # System health (modules, loggers, watcher state)
drone @prax status sync # Build STATUS.md from all branch STATUS.local.md
drone @prax status --help # Status usage
```
### Log Audit
```bash
drone @prax log-audit # Show audit module info
drone @prax log-audit audit # Scan system_logs/ for health + oversized files
drone @prax log-audit enforce # Truncate oversized logs to 1000 lines
drone @prax log-audit --help # Audit usage
```
### Dashboard
```bash
drone @prax dashboard # Show dashboard sections
drone @prax dashboard refresh --all # Refresh all branch dashboards from centrals
drone @prax dashboard refresh @flow # Refresh a specific branch
drone @prax dashboard status # Show dashboard status
drone @prax dashboard push-template # Push template to all branches
drone @prax dashboard diff-template # Diff template vs branch dashboards
drone @prax dashboard --help # Dashboard usage
```
## Logging API
### Pattern A — Canonical (use this)
```python
from aipass.prax import logger
logger.info("Processing started")
```
This works from any branch. Prax detects the caller via stack introspection and routes to the correct log file. If prax fails to import, a NullLogger fallback prevents crashes.
### Pattern B — Direct Logger (for prax internals)
```python
from aipass.prax.apps.modules.logger import get_direct_logger
@@ -47,94 +106,112 @@ logger = get_direct_logger()
logger.info("Direct log entry")
```
### Mission Control
Use this in prax handler files that run in watchdog threads or sit in the import chain. Resolves module/branch at creation time, bypassing the runtime event pipeline.
Real-time monitoring console for watching system activity across all branches and CLI tools.
### Programmatic Dashboard API
```bash
drone @prax monitor run
```python
from aipass.prax.apps.modules.dashboard import write_section
write_section(branch_path, "ai_mail", {"new": 3, "total": 5})
```
Features:
- File changes, log events, drone commands, agent activity — all in one console
- **Caller attribution** — shows `CALLER → TARGET` for drone commands
- **Model tags** — shows `[BRANCH/model]` (e.g., `[DEVPULSE/opus]`, `[DEVPULSE/gpt-5.4]`)
- **Multi-CLI** — monitors Claude Code (JSONL), Codex (JSONL), Gemini (JSON) sessions
- **Polling fallback** — when inotify is exhausted, falls back to PollingObserver automatically
- **Interactive filtering** *(not operational)* — `watch`, `filter` commands are deferred
Interactive commands inside the monitor:
```
help # Show available commands
status # Display current monitoring state
quit/exit # Stop monitoring
```
### CLI Commands
| Command | Description |
|---------|-------------|
| `drone @prax monitor run` | Launch Mission Control |
| `drone @prax monitor` | Show monitor introspection |
| `drone @prax status` | Show system status (modules, loggers, watcher state) |
| `drone @prax status sync` | Sync STATUS.md from all branch STATUS.local.md |
| `drone @prax log-audit audit` | Audit log file sizes and health |
| `drone @prax log-audit enforce` | Truncate oversized logs |
| `drone @prax dashboard` | Show system dashboard |
| `drone @prax dashboard refresh --all` | Refresh dashboard data from centrals |
## Architecture
```
prax/
├── __init__.py # Public API: exports `logger` (NullLogger fallback)
├── apps/
│ ├── prax.py # Entry point (CLI)
│ ├── modules/
│ │ ├── logger.py # SystemLogger (public API)
│ │ ├── monitor.py # Mission Control
│ │ ├── dashboard.py # System dashboard
│ │ ├── status.py # System status / STATUS sync
│ │ └── log_audit.py # Log file audit
│ └── handlers/
│ ├── central/ # Central file reader
│ ├── config/ # Configuration loading
│ ├── dashboard/ # Dashboard refresh and operations
│ ├── discovery/ # Module scanning and filtering
│ ├── json/ # JSON operations handler
│ ├── json_templates/ # JSON template definitions
│ ├── logging/ # Log setup, rotation, introspection
│ ├── monitoring/ # Event queue, branch detection, stream output
│ ├── registry/ # Module registry management
│ ├── status/ # STATUS sync handler
│ └── watcher/ # File and log watchers
├── templates/ # Dashboard templates
├── tests/ # Test suite (375 tests)
└── tools/ # Standalone utilities (inbox_watchdog.py)
│ ├── prax.py # Entry point — auto-discovers modules, routes commands
│ ├── modules/ # Business logic (5 command modules)
│ │ ├── logger.py # SystemLogger — auto-routing, two-tier logging
│ │ ├── monitor.py # Mission Control — 3-thread real-time monitoring
│ │ ├── dashboard.py # Dashboard — template management, refresh, write-through
│ │ ├── status.py # System status — health display, STATUS.md sync
│ │ └── log_audit.py # Log audit — scan, health summary, enforce limits
│ └── handlers/ # Implementation details (11 handler directories)
│ ├── central/ # Central file reader (.ai_central/*.central.json)
│ ├── config/ # Path resolution, log config, ignore patterns
│ ├── dashboard/ # Refresh, operations, template push/diff, agent status
│ ├── discovery/ # Module scanning, filtering, file watcher for new .py
│ ├── json/ # Auto-creating JSON handler (config/data/log per module)
│ ├── json_templates/ # Default JSON templates for auto-creation
│ ├── logging/ # Setup, rotation, introspection, override, direct logger
│ ├── monitoring/ # Event queue, branch detector, stream output, log watcher
│ ├── registry/ # Module registry load/save
│ ├── status/ # STATUS.md sync handler
│ └── watcher/ # Background system watchers
├── prax_json/ # Auto-created per-module config/data/log files
├── templates/ # Dashboard template schema (DASHBOARD.template.json)
├── tests/ # 375 tests across 16 files
└── tools/ # Standalone utilities (inbox_watchdog.py, verify_branch.py)
```
### Design Pattern
The entry point (`prax.py`) has zero business logic — it auto-discovers modules in `apps/modules/` and routes commands. Each module is a thin orchestrator over its handlers. Handlers are never imported by external branches.
### Command Routing
```
drone @prax monitor run
→ prax.py discovers modules (glob apps/modules/*.py)
→ calls monitor.handle_command("monitor", ["run"])
→ monitor.py delegates to handlers/monitoring/*
```
## How It Works
1. **Auto-routing** — When any module calls `logger.info()`, prax inspects the call stack to identify the caller and routes the log entry to the appropriate file.
2. **Two-tier logging** — Each log entry goes to both `system_logs/` (central aggregation) and `<branch>/logs/` (branch-local), both with rotation.
3. **Mission Control** — A multi-threaded monitoring console (display, file watcher, log watcher). Falls back to polling when inotify is exhausted. Shows caller attribution and model tags.
4. **Multi-CLI monitoring** — Watches Claude Code JSONL, Codex JSONL, and Gemini JSON session files for agent activity (thinking, tool use, responses).
5. **Dashboard** — Aggregates data from central files and branch status into per-branch dashboard views.
1. **Auto-routing** — `logger.info()` inspects the call stack to identify the caller's module, branch, and file path, then routes the log entry to the correct per-module log file.
2. **Two-tier logging** — Each log entry goes to both `system_logs/` (central, all branches) and `<branch>/logs/` (branch-local), both with size-based rotation.
3. **Self-healing** — Auto-creates missing log directories, falls back to `system_logs/external/` for unknown modules, provides NullLogger if prax itself fails to import.
4. **Mission Control** — Three threads: display worker (pulls from event queue), file watcher (watchdog on branch `apps/` dirs), log watcher (tails `system_logs/*.log`). Falls back to polling when inotify is exhausted.
5. **Multi-CLI monitoring** — Watches Claude Code JSONL, Codex JSONL, and Gemini JSON session files. Extracts agent activity (thinking, tool use, responses) with model detection and branch resolution.
6. **Dashboard** — Template-based per-branch dashboard files. Refreshes from central files (`*.central.json`). Write-through API for services to update sections directly.
7. **STATUS sync** — Scans all branch `STATUS.local.md` files, extracts State/Last update fields, builds aggregated `STATUS.md` at the repo root.
---
## Tests
375 tests across 16 files, covering all major components:
| Test File | Tests | Coverage |
|-----------|-------|----------|
| test_logger_module.py | 40 | Logger init, routing, lifecycle |
| test_monitoring_filters.py | 39 | Event filtering rules |
| test_config.py | 38 | Config loading, path resolution |
| test_event_queue.py | 35 | Thread-safe event buffering |
| test_log_watcher.py | 35 | Log file tailing |
| test_logging.py | 33 | Core logging system |
| test_discovery.py | 25 | Module scanning |
| test_operations.py | 24 | Dashboard operations |
| test_watcher.py | 23 | File watcher behavior |
| test_registry.py | 22 | Module registry |
| test_json_handler.py | 18 | JSON auto-creation |
| test_central.py | 14 | Central reader |
| test_monitor_module.py | 11 | Monitor commands |
| test_log_audit.py | 10 | Log audit |
| test_status.py | 8 | Status commands |
90/136 public functions tested (66%).
## Integration Points
### Depends On
- `aipass.cli` — Console output, headers, success/error formatting
- `aipass.drone` — Caller attribution via `[CALLER:BRANCH]` log markers
- Python stdlib (`pathlib`, `importlib`, `argparse`, `logging`)
- `aipass.trigger` — Optional event firing (module_discovered, error_detected)
- `watchdog` — File system monitoring (inotify + polling fallback)
- Python stdlib (`pathlib`, `logging`, `threading`, `argparse`, `importlib`)
### Provides To
- All 11 branches — Unified logging via `from aipass.prax import logger`
- All branches — Unified logging via `from aipass.prax import logger`
- All branches — Real-time monitoring via Mission Control
- System — STATUS.md sync, dashboard infrastructure
- All branches — Per-branch dashboard files
- System — `STATUS.md` sync, log audit enforcement
## Known Issues
- **inotify exhaustion** — System often near `max_user_watches` limit. Monitor uses polling fallback (functional but slower).
- **Interactive filtering deferred** — `watch`/`filter` commands in Mission Control are not operational.
---