@matt82198/aesop 0.1.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to Aesop are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+#### Dashboard Integrations
+- **`dash/dash-extra.mjs`**: Fleet agent detector scans transcripts for running agents, enables web dashboard agent panel. Detects agents in last 12 minutes, color-codes by alert severity, outputs JSON for REST endpoint or TUI text for terminal.
+- **`tools/secret_scan.py`**: Pre-push secret/credential detection gate with comprehensive pattern library (PEM keys, AWS/GitHub/Slack/OpenAI tokens, .env patterns, credential filenames). Supports `--staged`, `--history`, and direct path scanning. Pragma escape hatch for allow-pattern-docs. Exit 1 blocks push on findings.
+
+### Improved
+- Web dashboard now properly detects and displays running subagents via `dash-extra.mjs`
+- Secret-scan gate now active in watchdog cycle; blocks any push with unscanned credentials
+
+## [1.0.0] - 2026-07-11
+
+### Added
+
+#### Web Dashboard (Primary Interface)
+- Modern, responsive HTML dashboard replacing terminal UI
+- Real-time fleet monitoring with 3-second refresh cycles
+- Heartbeat liveness detection for daemon health
+- Security alerts panel with unreviewed event tracking
+- Inbox integration for direct orchestrator communication
+- Agent tracking with status and runtime hints
+- **Agent detail expansion**: Click agent rows to view full dispatch prompts, dispatcher, model, and message counts
+- **GET /agent endpoint**: RESTful query for agent metadata and full dispatch details
+- Repository synchronization status display
+- Recent events log with the latest 8 backup operations
+- Transcript integration showing main-thread conversation history
+- Configurable port (default 8770) via environment variables
+- Zero external dependencies (Python 3.10+ stdlib only)
+
+#### Orchestration Engine
+- Fable-fleet dispatch model (orchestrator + Haiku subagents)
+- Cost-optimized multi-agent coordination
+- Durable git-committed state (STATE.md, BUILDLOG.md)
+- Autonomous watchdog daemon with 150-second cycle
+- Secret-scan gate on every push (configurable via `tools/secret_scan.py`)
+- Heartbeat-based liveness detection (300s watchdog, 3600s monitor)
+- Append-only BUILDLOG for recovery and audit trails
+
+#### Refinement Monitor
+- Standing orchestration health monitor (Haiku loop)
+- Dual-action tier system (AUTO for immediate, PROPOSE for staged)
+- Signal collection and drift detection
+- Automated health checks and rule-friction analysis
+- Extensible signal collectors via `monitor/collect-signals.mjs`
+
+#### State Machine & Durability
+- Filesystem-first checkpoint design
+- Git-committed STATE.md and BUILDLOG.md
+- Recovery from machine wipes and interruptions
+- Single-writer control file discipline
+- Idempotent restart semantics
+
+#### Security & Observability
+- Configurable secret-scan gate (blocks pushes on policy violation)
+- Observable machinery (every agent run logged, every cost tracked)
+- Security alert collection and triaging
+- AV-resilience patterns for Windows environments
+- Support for dot-directory backup discovery
+
+#### Documentation
+- Cardinal Rules guide (10 principles for cost-optimized orchestration)
+- Dispatch Model documentation (cost analysis, parallel patterns)
+- State Machine guide (durability and recovery)
+- AV-Resilience guide (Windows security software compatibility)
+- Quickstart walkthrough and setup guide
+- Architecture deep-dives for extend points
+
+#### TUI Dashboard (Legacy Alternative)
+- Terminal-based dashboard via `dash/watchdog-gui.sh`
+- Real-time fleet status display
+- Agent activity tracking
+- Alert visualization
+- Optional jq dependency for JSON parsing
+
+### Configuration
+
+#### aesop.config.json Schema
+```json
+{
+  "aesop_root": "/path/to/aesop",
+  "state_root": "/path/to/state",
+  "scan_root": "/path/to/scan",
+  "transcripts_root": "/path/to/transcripts",
+  "repos": [
+    {
+      "path": "/path/to/repo",
+      "name": "repo-name"
+    }
+  ],
+  "watchdog_cycle_secs": 150,
+  "monitor_cycle_secs": 300,
+  "heartbeat_stale_threshold_secs": 300
+}
+```
+
+### Development & Extension
+
+- Plugin architecture for custom signal collectors
+- Hook points for watchdog customization
+- Dashboard extensibility via JavaScript injection
+- Secret-scan policy implementation examples
+- Support for Haiku-per-domain decomposition
+
+---
+
+## Initial Release
+
+This is the first public release of Aesop, a clean-room open-source implementation of the fable-fleet orchestration harness. The codebase includes:
+
+- The complete orchestration engine with watchdog and monitor
+- Web dashboard for fleet observability
+- Legacy TUI interface (bash + jq)
+- Configuration framework and examples
+- Comprehensive documentation and guides
+- MIT License (© 2026 Matt Culliton)
+
+Aesop is production-ready and implements the complete cardinal rules for cost-optimized, durable multi-agent coordination.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Culliton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,333 @@
+# Aesop — Fable-Fleet Orchestration Harness
+
+**Aesop** is an open-source orchestration harness for Claude Code, implementing a cost-optimized, self-healing multi-agent dispatch system. One orchestrator model (Opus/Sonnet) directs a fleet of cheap subagents (Haiku) across durable, observable machinery.
+
+The naming is a conceit: Aesop directs the Fables (the AI models). Like the tortoise and the hare, Aesop favors the slow, deliberate orchestrator directing a fleet of fast, cheap agents toward reliable outcomes.
+
+## Origin
+
+Aesop began as damage control: an endpoint-security agent kept deleting work mid-session, so everything was forced into git—committed continuously, pushed constantly, reconstructable from nothing but the remotes. What started as a survival mechanism against a machine that wiped itself grew into a full multi-agent orchestration system—and one worth sharing.
+
+## What it is
+
+A filesystem-first orchestration system that:
+
+- **Dispatch pattern**: Opus orchestrator on the main thread coordinates tiny scoped tasks to Haiku subagents (1/3 the token cost).
+- **Durable state**: git-committed checkpoints (STATE.md, BUILDLOG.md) survive machine wipes and interruptions.
+- **Observable machinery**: every agent run logged, every cost tracked, every security breach detected.
+- **Self-healing watchdog**: runs every 150s, backs up work, scans for secrets and drift, restores on reboot.
+- **Refinement monitor**: standing Haiku loop that watches orchestration health and auto-acts on rule friction.
+- **TUI dashboard**: real-time fleet status, security alerts, heartbeat liveness.
+
+## Install & Quick Start
+
+### Option 1: npm (Recommended for quick scaffolding)
+
+```bash
+# Create a new aesop fleet directory
+npx @matt82198/aesop my-fleet
+cd my-fleet
+
+# Configure
+cp aesop.config.example.json aesop.config.json
+# Edit aesop.config.json with your paths and repos
+
+# Start the daemon
+bash daemons/run-watchdog.sh --once
+
+# Launch the dashboard
+python ui/serve.py
+```
+
+Open `http://localhost:8770` to monitor your fleet.
+
+### Option 2: git clone (For development or full customization)
+
+```bash
+git clone https://github.com/matt82198/aesop ~/aesop
+cd ~/aesop
+cp aesop.config.example.json aesop.config.json
+# Edit aesop.config.json with your paths and repos
+
+# Start the daemon
+export AESOP_ROOT=$HOME/aesop
+bash $AESOP_ROOT/daemons/run-watchdog.sh --once
+
+# Launch the dashboard
+python ui/serve.py
+```
+
+## Architecture
+
+### Directory layout
+
+```
+aesop/
+  daemons/          # Watchdog daemon + backup scripts
+  dash/             # TUI dashboard (watchdog-gui.sh)
+  monitor/          # Orchestration monitor (collect-signals.mjs, CHARTER.md)
+  tools/            # Build utilities (stubs for extend)
+  docs/             # Migration guides, deep-dives
+  state/            # Durable checkpoints (created at runtime)
+  aesop.config.json # Your local configuration (git-ignored)
+```
+
+### Operating the harness
+
+#### 1. Bootstrap
+
+```bash
+git clone <aesop-repo> ~/aesop
+cd ~/aesop
+cp aesop.config.example.json aesop.config.json
+# Edit aesop.config.json with your paths and repos
+```
+
+#### 2. Start the watchdog daemon
+
+```bash
+export AESOP_ROOT=$HOME/aesop
+bash $AESOP_ROOT/daemons/run-watchdog.sh &
+```
+
+Runs every 150s: discovers changed repos, stashes uncommitted work, pushes backups to `backup/wip-*` branches, runs secret-scan gate.
+
+#### 3. Launch the Web Dashboard (Primary Interface)
+
+The web dashboard is the recommended way to monitor your fleet. It provides real-time observability, security alerts, and inbox integration in a modern, responsive interface.
+
+```bash
+python $AESOP_ROOT/ui/serve.py
+```
+
+Opens `http://localhost:8770` with:
+- Real-time daemon heartbeats and liveness
+- Active subagent tracking
+- Security alerts panel
+- Recent events log
+- Inbox for orchestrator communication
+- Repository sync status
+
+See `ui/README.md` for configuration, environment variables, and troubleshooting.
+
+#### (Optional) Legacy TUI Dashboard
+
+If you prefer a terminal-based interface:
+
+```bash
+# On Windows (in a dedicated terminal):
+Start-Process "C:\Program Files\Git\git-bash.exe" -ArgumentList '-c', 'bash /c/Users/you/aesop/dash/watchdog-gui.sh'
+
+# On Unix:
+bash ~/aesop/dash/watchdog-gui.sh &
+```
+
+Note: The TUI is maintained for backward compatibility but is not actively developed. The web dashboard is recommended for new deployments.
+
+#### 4. Arm the monitor loop
+
+```bash
+# If using Claude Code, add to your CLAUDE.md or invoke via /power:
+# Runs collect-signals.mjs every cycle, emits BRIEF.md + SIGNALS.json,
+# then acts on AUTO-tier findings or stages PROPOSE-tier changes.
+```
+
+## Cardinal Rules (abridged)
+
+Read `docs/CARDINAL-RULES.md` for the full text. Core principles:
+
+1. **Dispatch**: Haiku subagents only (cost lever). Opus orchestrates main-thread only.
+2. **TDD-first**: Fail tests before implementation. Tiny scoped domains; one Haiku per domain.
+3. **Reliability**: Every input produces output (brief/log/heartbeat/FAILED). Never wait.
+4. **Durable state**: STATE.md + BUILDLOG.md checkpoints survive wipes. Re-sync on resume.
+5. **Push discipline**: feature/branch → PR (never main). Continuously push green work.
+6. **Control files**: Single-writer discipline (STATE.md orchestrator, MEMORY.md keeper, BUILDLOG.md append-only).
+7. **Local execution**: Python runs locally only (no cloud runners). Reusable scripts in ~/scripts.
+8. **Secret gates**: `secret_scan.py` blocks every push. No credentials in repos.
+9. **Observability**: Every agent run logged, every cost tracked, every security event triaged.
+
+## Requirements
+
+- **Claude Code CLI** (v0.1+): the agent-spawning harness.
+- **Git** (v2.40+): version control for durable state.
+- **Bash** (v4+): scripting (Git Bash on Windows, bash on Unix).
+- **Node.js** (v18+): for monitor signal collection and dashboard extras.
+- **Python** (v3.10+): for log rotation, secret-scan, and custom tooling.
+- **jq** (optional): JSON parsing in TUI dashboard.
+
+## Setup Walkthrough
+
+### 1. Edit your configuration
+
+```bash
+cp aesop.config.example.json aesop.config.json
+```
+
+Edit `aesop.config.json`:
+- Set `aesop_root`, `brain_root`, `scripts_root`, `temp_root` to your paths.
+- List your project repos under `repos[]`.
+- Tune watchdog and monitor cycle times.
+- Disable secret-scan if you don't have `tools/secret_scan.py` yet.
+
+### 2. Create required directories
+
+```bash
+mkdir -p ~/aesop/state
+mkdir -p ~/.heartbeats
+```
+
+### 3. (Optional) Add your secret-scan script
+
+If you have a security scanner, drop it at `aesop/tools/secret_scan.py`. The watchdog will call it before pushing.
+
+Example stub:
+```python
+#!/usr/bin/env python3
+import sys
+sys.exit(0)  # TODO: implement secret scanning
+```
+
+### 4. Start the daemon
+
+```bash
+export AESOP_ROOT=$HOME/aesop
+bash $AESOP_ROOT/daemons/run-watchdog.sh &
+```
+
+Test mode: `bash $AESOP_ROOT/daemons/run-watchdog.sh --once`
+
+### 5. Launch the dashboard
+
+```bash
+bash ~/aesop/dash/watchdog-gui.sh
+```
+
+### 6. Arm the monitor (optional)
+
+If you're using Claude Code, add this to your orchestrator loop:
+```bash
+export AESOP_ROOT=$HOME/aesop
+node $AESOP_ROOT/monitor/collect-signals.mjs
+```
+
+The monitor will read `BRIEF.md` and `SIGNALS.json` each cycle and act on findings.
+
+## Usage Patterns
+
+### Dispatch model (how to scale cheaply)
+
+```plaintext
+Orchestrator (main thread)
+  ├─ Haiku subagent 1 (domain A: tests)
+  ├─ Haiku subagent 2 (domain B: build)
+  ├─ Haiku subagent 3 (domain C: review)
+  └─ Haiku subagent 4 (domain D: docs)
+```
+
+Each subagent is **tiny**, **scoped**, and **disposable**. Total cost: ~25% of all-Opus fleet.
+
+### Action tiers (AUTO vs PROPOSE)
+
+- **AUTO**: immediate + logged (read-only checks, appends to logs, heartbeat updates).
+- **PROPOSE**: staged in `monitor/PROPOSALS.md`, requires user approval before execution.
+
+### Heartbeat pattern
+
+Daemons write epoch-seconds to `.heartbeat` files. The dashboard reads these to detect stalls:
+- Watchdog: alert if >300s old.
+- Monitor: alert if >3600s old.
+- Custom loops: check before spawning (skip if <200s).
+
+## Security & Privacy
+
+**⚠️ Important**: This harness assumes a **private brain directory** (`~/.claude`) that is **NEVER committed** to this repo. Your cardinal rules, agent catalog, and memory belong in your private remote (e.g., `claude-config`).
+
+- `aesop.config.json` is git-ignored (keep your paths secret).
+- `state/` and `.log` files are git-ignored (keep runtime data local).
+- Implement `tools/secret_scan.py` with your own security rules.
+- Use `secret_scan.py` as a gate on every push (don't bypass).
+
+## Extension points
+
+### Add a custom signal collector
+
+Edit `monitor/collect-signals.mjs`:
+```javascript
+// Example: detect junk scripts
+function findJunkScripts() {
+  const junk = fs.readdirSync('/tmp').filter(f => f.endsWith('.py'));
+  return junk;
+}
+
+// Then add to signals:
+signals.junkScripts = findJunkScripts();
+```
+
+### Customize the watchdog
+
+Edit `daemons/backup-fleet.sh`:
+- Parse `aesop.config.json` to discover repos dynamically.
+- Add per-repo hooks (e.g., run linters before backup).
+- Implement your own secret-scan gate.
+
+### Extend the dashboard
+
+Edit `dash/watchdog-gui.sh`:
+- Add panels for CPU/memory/disk usage.
+- Integrate with your monitoring system.
+- Color-code alerts by severity.
+
+## Troubleshooting
+
+### Watchdog doesn't start
+
+Check `state/FLEET-BACKUP.log` for errors. Verify `AESOP_ROOT` is set correctly.
+
+### Dashboard shows "unavailable"
+
+- If you see `(agents/processes panel unavailable)`, `node` is missing or `dash-extra.mjs` is not in sync.
+- Install Node.js v18+ and re-run.
+
+### Secret-scan blocks a legitimate push
+
+Add a suppression to your `tools/secret_scan.py`. Aesop never auto-bypasses gates (by design).
+
+### Monitor doesn't start
+
+Ensure Node.js is on PATH and `collect-signals.mjs` has execute permissions. Check `monitor/BRIEF.md` for the latest cycle log.
+
+## Architecture deep-dives
+
+See `docs/` for detailed guides:
+- `CARDINAL-RULES.md` — full text of the 10 cardinal rules.
+- `DISPATCH-MODEL.md` — cost analysis and parallel orchestration patterns.
+- `STATE-MACHINE.md` — how STATE.md and BUILDLOG.md survive wipes.
+- `MONITOR-GOVERNANCE.md` — monitor AUTO/PROPOSE tiers and approval flow.
+
+## License
+
+MIT License. See `LICENSE` file.
+
+## Contributing
+
+Aesop is open-source and welcomes improvements. To contribute:
+
+1. Fork this repo.
+2. Create a feature branch: `git checkout -b feature/your-idea`.
+3. Add tests (TDD first).
+4. Commit with clear messages.
+5. Push to origin and open a PR.
+
+Maintain the cardinal rules: keep subagents cheap (Haiku), orchestrator lean, state durable, and machinery observable.
+
+## References
+
+- [Anthropic Claude API](https://docs.anthropic.com)
+- [Claude Code CLI](https://github.com/anthropics/claude-code)
+- [Git documentation](https://git-scm.com/doc)
+- Inspiration: "The Missing Memory Layer", "Agent Cost Trauma", "120 Words to Shipped" (publications on AI orchestration patterns).
+
+---
+
+**Aesop Contributors**  
+Built with the fable-fleet dispatch model in mind. May your orchestrator be wise and your subagents swift.

package/aesop.config.example.json

@@ -0,0 +1,47 @@
+{
+  "description": "Aesop configuration example. Copy to aesop.config.json and customize for your setup.",
+  "aesop_root": "/path/to/aesop",
+  "brain_root": "/path/to/your/brain",
+  "scripts_root": "/path/to/your/scripts",
+  "temp_root": "/path/to/temp/scratch",
+  "repos": [
+    {
+      "path": "/path/to/project1",
+      "name": "project1",
+      "primary_branch": "main",
+      "backup_branch": "backup/wip"
+    },
+    {
+      "path": "/path/to/project2",
+      "name": "project2",
+      "primary_branch": "main",
+      "backup_branch": "backup/wip"
+    }
+  ],
+  "watchdog": {
+    "cycle_seconds": 150,
+    "heartbeat_threshold_seconds": 200,
+    "enable_secret_scan": true,
+    "secret_scan_script": "tools/secret_scan.py"
+  },
+  "monitor": {
+    "enable": true,
+    "cycle_seconds": 3600,
+    "heartbeat_threshold_seconds": 3600,
+    "memory_staleness_days": 30,
+    "log_max_lines": 500,
+    "log_max_kb": 40
+  },
+  "dashboard": {
+    "refresh_seconds": 1,
+    "enable_jq_parsing": true,
+    "theme": "dark"
+  },
+  "cardinal_rules": {
+    "subagent_model": "haiku",
+    "orchestrator_model": "opus",
+    "tdd_first": true,
+    "never_push_main": true,
+    "secret_scan_gates_push": true
+  }
+}

package/bin/cli.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const helpFlag = args.includes('--help') || args.includes('-h');
+
+if (helpFlag) {
+  console.log(`
+aesop — Multi-agent orchestration template scaffolder
+
+Usage:
+  npx @matt82198/aesop [target-dir]
+
+Arguments:
+  target-dir    Directory to scaffold the template into (default: "aesop-fleet")
+
+Examples:
+  npx @matt82198/aesop                    # Creates ./aesop-fleet/
+  npx @matt82198/aesop my-fleet           # Creates ./my-fleet/
+  npx @matt82198/aesop /tmp/my-orchestrator  # Creates /tmp/my-orchestrator/
+
+Options:
+  --help, -h    Show this help message
+
+After scaffolding, cd into the directory and:
+  1. Copy aesop.config.example.json → aesop.config.json
+  2. Edit aesop.config.json with your paths and repos
+  3. Run: bash daemons/run-watchdog.sh --once
+  4. Launch dashboard: python ui/serve.py
+`);
+  process.exit(0);
+}
+
+const targetDir = args[0] || 'aesop-fleet';
+
+if (args.length > 1) {
+  console.error('Error: Too many arguments. Use --help for usage.');
+  process.exit(1);
+}
+
+// Validate target directory doesn't exist or is empty
+if (fs.existsSync(targetDir)) {
+  const contents = fs.readdirSync(targetDir);
+  if (contents.length > 0) {
+    console.error(`Error: Directory "${targetDir}" exists and is not empty.`);
+    console.error('Please choose a different target directory or remove the existing one.');
+    process.exit(1);
+  }
+} else {
+  fs.mkdirSync(targetDir, { recursive: true });
+}
+
+// Copy template files
+const templateRoot = path.join(__dirname, '..');
+const filesToCopy = [
+  'daemons',
+  'dash',
+  'monitor',
+  'tools',
+  'ui',
+  'docs',
+  'aesop.config.example.json',
+  'README.md',
+  'LICENSE',
+  'CHANGELOG.md'
+];
+
+let copiedCount = 0;
+
+function copyRecursive(src, dest) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    const entries = fs.readdirSync(src);
+    entries.forEach(entry => {
+      const srcFile = path.join(src, entry);
+      const destFile = path.join(dest, entry);
+      copyRecursive(srcFile, destFile);
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+    copiedCount++;
+  }
+}
+
+try {
+  filesToCopy.forEach(item => {
+    const src = path.join(templateRoot, item);
+    const dest = path.join(targetDir, item);
+    if (fs.existsSync(src)) {
+      copyRecursive(src, dest);
+      console.log(`✓ Copied ${item}`);
+    }
+  });
+
+  console.log(`\n✅ Scaffolded aesop template into "${targetDir}" (${copiedCount} files)`);
+  console.log('\nNext steps:');
+  console.log(`  1. cd ${targetDir}`);
+  console.log('  2. cp aesop.config.example.json aesop.config.json');
+  console.log('  3. Edit aesop.config.json with your configuration');
+  console.log('  4. bash daemons/run-watchdog.sh --once  (test run)');
+  console.log('  5. python ui/serve.py  (launch dashboard)');
+  console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
+  process.exit(0);
+} catch (err) {
+  console.error(`Error scaffolding template: ${err.message}`);
+  process.exit(1);
+}