@matt82198/aesop 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -1,4 +1,15 @@
-# Aesop — Fable-Fleet Orchestration Harness
+<p align="center">
+  <img src="https://raw.githubusercontent.com/matt82198/aesop/main/assets/logo.png" alt="Aesop" width="420">
+</p>
+
+<p align="center">
+  <em>Fable-Fleet Orchestration Harness</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@matt82198/aesop"><img src="https://img.shields.io/npm/v/@matt82198/aesop/beta" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@matt82198/aesop" alt="license"></a>
+</p>
 
 **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.
 
@@ -23,9 +34,12 @@ A filesystem-first orchestration system that:
 
 ### Option 1: npm (Recommended for quick scaffolding)
 
+**Note:** Aesop is currently in beta. Install the prerelease version:
+
 ```bash
 # Create a new aesop fleet directory
-npx @matt82198/aesop my-fleet
+# Using @beta tag to install the latest prerelease version (0.1.0-beta.1)
+npx @matt82198/aesop@beta my-fleet
 cd my-fleet
 
 # Configure
@@ -41,6 +55,12 @@ python ui/serve.py
 
 Open `http://localhost:8770` to monitor your fleet.
 
+Alternatively, install globally:
+```bash
+npm install -g @matt82198/aesop@beta
+aesop my-fleet
+```
+
 ### Option 2: git clone (For development or full customization)
 
 ```bash

package/docs/CARDINAL-RULES.md

@@ -2,16 +2,21 @@
 
 These are the foundational principles that guide all work in an Aesop-driven fleet. Violating these risks cost explosion, data loss, or orchestration breakdown.
 
-## 1. Dispatch model & cost
+## 1. Dispatch model & cost — Main Rule: subagents are ALWAYS cheap tier
 
-**Rule**: Subagents are ALWAYS Haiku (1/3 Sonnet cost). Orchestrator (Opus) runs on main thread only.
+**Rule**: Subagents are ALWAYS Haiku (1/3 Sonnet cost) — **the single most important cost lever**. Orchestrator (Fable/Opus) runs on main thread only, NEVER spawns as a subagent, performs final-catch review itself, and NEVER hand-writes files in normal flow.
 
-**Why**: Haiku at scale (6–8 agents in parallel) costs ~25% of all-Opus fleet while maintaining quality on tiny scoped tasks. Opus reserved for final validation, handoff, and orchestration.
+**Why**: Haiku at scale (6–8 agents in parallel) costs ~25% of all-Opus fleet while maintaining quality on tiny scoped tasks. Main thread orchestrator preserves context stability and keeps prompt cache warm across turns.
+
+**Watchdog & stalls**: The orchestrator's core job is detecting hung Haikus. Signs: agent transcript hasn't advanced for >200s, workflow phase isn't progressing, background task should have exited but hasn't. On detection, TaskStop + relaunch the hung agent. Workflows resume from cache via `resumeFromRunId`; standalone agents respawn fresh.
+
+**Retry cap**: 1st–3rd hang = TaskStop + relaunch automatically. On 4th hang, mark BLOCKED in BUILDLOG.md and surface to the user instead of respawning. Prevents infinite loops and ensures visibility.
 
 **Implementation**:
 - When spawning a new agent, default to Haiku.
 - If you need Opus-tier reasoning, consider decomposing into smaller Haiku tasks first.
 - Track token spend per subagent; alert if spend deviates >20% from baseline.
+- Watchdog monitors for stalls; never let a stuck Haiku silently block a pipeline.
 
 ## 2. TDD-first & parallel domains
 
@@ -28,15 +33,18 @@ These are the foundational principles that guide all work in an Aesop-driven fle
 
 ## 3. Reliability core: inputs always produce outputs
 
-**Rule**: Every input (request, event, cycle) must produce an output (brief/log/heartbeat/FAILED). Never wait silently; dispatch next work and offer ideas while waiting.
+**Rule**: Every input (request, event, cycle) must produce an output (brief/log/heartbeat/FAILED). **NEVER WAIT**: the orchestrator never goes idle while background work is in flight — dispatch the next unblocked work unit, extend the roadmap, stage ideas, queue facts, and always offer the user an idea for what to do next. "Waiting on X" must come with "meanwhile, doing/proposing Y."
+
+**Why**: Hangs hide cost waste, data loss, and orchestration confusion. Observable failure is better than silent lag. Idle time is token waste.
 
-**Why**: Hangs hide cost waste, data loss, and orchestration confusion. Observable failure is better than silent lag.
+**The pride bar**: Never ship known-broken. "An agent returned a brief" and "tests pass" are checkpoints, not completion. Done means: verified end-to-end, briefs cross-checked against reality, test artifacts cleaned, loose ends closed or explicitly logged, nothing known-broken shipped silently. If you'd hesitate to hand it over under your own name, keep going.
 
 **Implementation**:
 - Daemons emit heartbeats every cycle (even on error).
 - Logs are append-only; every action logged with timestamp.
 - If a subagent stalls >200s, watchdog respawns it.
 - Orchestrator briefs the user with findings while delegating to subagents (never idle).
+- Before marking work done, verify end-to-end and cross-check briefs against reality.
 
 ## 4. Orchestrator isolation: lean context
 
@@ -64,28 +72,30 @@ These are the foundational principles that guide all work in an Aesop-driven fle
 
 ## 6. Branch discipline & continuous push
 
-**Rule**: Feature branches only (never main/master). Continuously push green work to origin. Never amend; create new commits.
+**Rule**: Feature branches only (never main/master). Continuously push green work to origin. **Never amend; create new commits.** **Never force-push** (unless explicitly approved for a specific commit).
 
-**Why**: Main branch stays deployable. Continuous push distributes backup risk. Amending hides history.
+**Why**: Main branch stays deployable. Continuous push distributes backup risk. Amending hides history; force-pushing erases commits. New commits preserve a clear audit trail.
 
 **Implementation**:
 - Create feature/your-task at start.
 - Commit often (every 15–30 min of solid work).
 - Push after every commit (github mirrors your work).
 - Open PR when feature is ready for review.
-- Never force-push (unless explicitly approved for specific commit).
+- If you need to fix a commit, create a new commit with the fix (never amend).
+- Never force-push; if you must rebase, do it on a draft branch before opening a PR.
 
 ## 7. Control files & single-writer discipline
 
-**Rule**: MEMORY.md (keeper writes), STATE.md (orchestrator writes), BUILDLOG.md (append-only, orchestrator appends).
+**Rule**: Single-writer control files: MEMORY.md (keeper writes only), STATE.md (orchestrator writes only), BUILDLOG.md (append-only for everyone, never overwrite). Single-instance loops check heartbeat before starting; skip if a live one exists.
 
-**Why**: Contention on shared state causes data loss and confusion. Single-writer enforcement prevents races.
+**Why**: Contention on shared state causes data loss and confusion. Single-writer enforcement prevents races. Append-only-for-everyone prevents accidental overwrites. Single-instance heartbeats prevent duplicate work (e.g., two memory keepers or monitors running simultaneously).
 
 **Implementation**:
-- Designate one role per file.
-- Use heartbeats to detect live writers; skip if <200s.
+- Designate one writer per control file (keeper for MEMORY.md, orchestrator for STATE.md).
+- BUILDLOG.md is append-only; anyone can append, no one edits earlier entries.
+- Before starting a loop, check `~/.claude/loops/<loop-name>.heartbeat`; if exists and recent (<5 min old), skip and exit.
 - On resume, read from disk; never trust in-memory state.
-- Append-only logs never overwrite; oldest entries rotate to archives.
+- Append-only logs never overwrite; oldest entries rotate to archives when >200 lines/20KB.
 
 ## 8. Secret-scan & version control
 

package/docs/DISPATCH-MODEL.md

@@ -33,6 +33,19 @@ Total                              = 1,080 tokens
 = **90% savings** vs 10 Opus tasks
 ```
 
+## MAIN RULE: Subagents are ALWAYS the cheap tier
+
+This is **the single most important cost lever** in the entire system. Every subagent spawned must default to Haiku, never Sonnet or Opus. This rule, more than any other, multiplies your savings at scale.
+
+**Why**: Haiku is 1/3 the cost of Sonnet with sufficient capability for scoped domain work. Scaling from 1 subagent to 6–8 in parallel multiplies the per-domain savings — what would cost 10× Opus now costs <1×. Violating this rule (spawning Sonnet/Opus subagents) erases the economic advantage of the entire dispatch model.
+
+**The exception**: Only use Sonnet/Opus for a subagent if:
+1. The task genuinely exceeds Haiku capability (rare for scoped domains), **AND**
+2. You've decomposed it as far as possible and still can't fit it into Haiku, **AND**
+3. You have explicit approval to do so.
+
+Even then, use Sonnet as a supervisor only (splits work into Haiku subdomains), never Opus as a subagent.
+
 ## Dispatch patterns
 
 ### Pattern 1: Fan-out (wide parallelism)
@@ -146,6 +159,20 @@ Is this task scoped to <5 min reasoning?
 2. **Respawn loop** (same domain 3+ times): subagent repeatedly failing; escalate to Sonnet or orchestrator review.
 3. **Serial bottleneck** (orchestrator >500 tokens): parallelism breaking down; split smaller or delegate.
 
+## Retry cap: Automatic recovery + escalation
+
+The orchestrator's watchdog automatically detects hung agents and relaunches them with the same scoped prompt:
+
+- **1st–3rd hang**: TaskStop + relaunch automatically. Workflows resume from cache via `resumeFromRunId`; standalone agents respawn fresh.
+- **4th hang**: Mark BLOCKED in BUILDLOG.md and surface to the user instead of respawning.
+
+**Why the cap?** Infinite retry loops waste tokens and hide systemic problems. After 3 attempts, a persistent hang indicates either:
+- Task is fundamentally unscopable (too large, too complex)
+- Subagent needs a larger model (escalate to Sonnet or Opus)
+- External dependency is broken (requires human intervention)
+
+Surfacing to the user after 3 retries ensures visibility and prevents silent cost bleed.
+
 ### Optimization levers
 
 - **Fan-out more tasks**: go from 2 Haiku to 5.

package/docs/GOVERNANCE.md

@@ -0,0 +1,162 @@
+# Governance & Control
+
+This guide covers the operational patterns that keep orchestration systems coherent, scalable, and auditable at production scale: single-instance loops, single-writer files, asynchronous inbox coordination, log rotation, branching discipline, and security gates.
+
+## Single-instance loops
+
+Standing loops (watchdog, monitor, memory keeper, cost tracker, QA verification) must not run in duplicate — that causes contention, conflicting writes, and wasted work.
+
+**Pattern**: Every loop checks its own heartbeat file before starting and skips the start if a live one exists.
+
+### Heartbeat protocol
+
+1. Before loop starts, check `~/.claude/loops/<loop-name>.heartbeat`
+2. If exists and recent (<5 min old), skip and exit
+3. If missing or stale, create/touch heartbeat file, run loop, delete heartbeat on exit
+
+**Example** (pseudo-code):
+```bash
+HEARTBEAT=~/.claude/loops/memory-keeper.heartbeat
+if [ -f "$HEARTBEAT" ] && [ $(($(date +%s) - $(stat -c %Y "$HEARTBEAT"))) -lt 300 ]; then
+  exit 0  # Live keeper running, skip
+fi
+touch "$HEARTBEAT"
+# ... run loop ...
+rm "$HEARTBEAT"
+```
+
+**Why**: Prevents duplicate work, keeps system coherent, and ensures idempotent restarts.
+
+## Single-writer control files
+
+Some files must have exactly one writer to prevent race conditions and data loss.
+
+**Writers by role**:
+- **MEMORY.md**: memory keeper only
+- **STATE.md**: active orchestrator only
+- **BUILDLOG.md**: append-only (anyone can append, no one edits earlier entries)
+- **Other loops**: append requests to an inbox file, never edit control files directly
+
+**Why**: Contention on shared state causes corruption. Single-writer enforcement makes all edits safe.
+
+## Inbox pattern for coordination
+
+Loops that need to request memory updates or signal decisions use an append-only inbox. The orchestrator reviews inbox entries on every `/power` cycle.
+
+### Inbox format
+
+1. Create `~/.claude/INBOX.md` (append-only, anyone can append)
+2. Format: `[TIMESTAMP] <loop-name>: <request>`
+3. On every `/power`, orchestrator reviews entries, acts on them, moves handled ones to an ACCEPTED/REJECTED log
+4. Clear INBOX.md when processed
+
+**Example**:
+```
+[2026-07-11 13:45] cost-loop: log monthly spend update to MEMORY.md
+[2026-07-11 14:00] qa-loop: mark feature X as verified, move to shipped log
+```
+
+**Why**: Decouples loop work from orchestrator; loops queue requests without blocking; orchestrator batches decisions on a predictable cadence.
+
+## Log rotation threshold
+
+Append-only control files grow over time. When a file exceeds **~200 lines or ~20 KB**, rotate the oldest entries into a dated archive.
+
+### Rotation procedure
+
+1. Copy oldest entries (typically oldest 50%) to `<FILE>-YYYY-MM.md`
+2. Keep only recent entries in the live `<FILE>.md`
+3. Commit both old and new files
+4. Update any references to point to the live file
+
+**Examples**:
+- `BUILDLOG.md` → `BUILDLOG-2026-06.md` (archive) + new `BUILDLOG.md` (live)
+- `COST-LOG.md` → `COST-LOG-2026-06.md` (archive) + new `COST-LOG.md` (live)
+
+**Why**: Keeps orchestrator context bounded and responsive. Orchestrator reads only recent ~20 entries; old data lives in archives.
+
+## Branch workflow: never straight to main
+
+**Production-grade branching** ensures code review, testing, and safety gates on all production merges.
+
+### Feature & fix branches
+
+- **Features**: `feat/<topic>` branches off main
+- **Fixes**: `fix/<issue-number>` branches off main
+- **All work**: Branches first, PR after implementation, merge after final-catch review
+
+**Never** push directly to main/master. All changes go through:
+1. Feature/fix branch
+2. Open PR
+3. Orchestrator final-catch review
+4. Merge into main
+
+### Session branches for infrastructure repos
+
+- Daily work on infrastructure repos (e.g., `~/.claude`): use `work/session-<date>` branches (e.g., `work/session-2026-07-11`)
+- Auto-commit hooks commit to the current branch, so housekeeping changes land on the session branch automatically
+- On checkpoint, open a PR from session branch → main
+- Orchestrator performs final-catch review and merges when ready
+
+### Backup branches
+
+Emergency backup snapshots use `backup/<snapshot-label>` branches. Never merge backups to main; recovery is via cherry-pick from backup → feature → PR → merge.
+
+**Why**: Main branch stays deployable. All work visible in PRs. History auditable. Accidental commits prevented.
+
+## Secret-scan gate on every push
+
+**Critical rule**: Every push (to any repo, any branch) is preceded by:
+
+```bash
+python ~/scripts/secret_scan.py --staged --repo <repo_path>
+```
+
+### Gate logic
+
+- **Exit code 0**: safe, proceed with push
+- **Exit code 1**: secrets detected, block push until resolved
+
+### What it detects
+
+- AWS/API keys, OAuth tokens, credentials
+- Private keys and SSH keys
+- Hardcoded passwords or session tokens
+- Sensitive file patterns
+
+### On blocked push
+
+1. Fix the staged files (remove secrets)
+2. Re-run secret_scan to verify clean
+3. Re-push (no `--no-verify` or workarounds)
+
+**Why**: Credentials leak → account/system compromise. Scanning + gating prevents accidents and keeps repos clean.
+
+## Version control for the brain
+
+Infrastructure repos (`~/.claude` for rules/hooks, `~/scripts` for shared scripts, handoff folders) are version-controlled and pushed to private remotes.
+
+**Discipline**:
+1. Every rule/hook/skill/memory change is committed and pushed as it lands
+2. On every `/power` session:
+   - Verify repos are clean (no uncommitted changes)
+   - Verify pushed to remote (no commits ahead)
+   - If unexpected changes found, restore from remote before continuing
+3. Never commit credentials, tokens, session data, or large binaries
+
+**Why**: Infrastructure is durable, recoverable, and auditable. Unexpected changes to rules are a Tier-1 incident.
+
+## Violations and escalation
+
+Governance violations are detected and escalated:
+
+1. **Watchdog daemon** enforces secret-scan gate and branch discipline
+2. **Monitor agent** auto-detects control-file violations and stages PROPOSALS.md or escalates
+3. **Orchestrator** reads STATE.md to verify governance compliance
+4. **Violations caught late** are logged and triaged; never silently ignored
+
+If a rule creates friction, propose a change via PROPOSALS.md (never work around it).
+
+---
+
+**Why these patterns matter**: They ensure your orchestration fleet operates **reliably** (inputs → outputs), **safely** (no secret leaks), **coherently** (no data loss from races), and **durably** (recoverable from failures). Together, they enable scaling from 1 orchestrator to dozens of parallel subagents without losing control or visibility.

package/monitor/CHARTER.md

@@ -9,26 +9,59 @@ A standing background monitor (Haiku subagent) that watches how the multi-agent
 > or invent new project goals. If it ever thinks the goal should change, it writes a note
 > in `PROPOSALS.md` and stops there.
 
-## What it watches
+## Standing checks (deterministic signal collection)
 
-1. **Heartbeat health** — are loop daemons alive? (watchdog ~300s, monitor ~3600s)
-2. **Security alerts** — any high/medium severity issues in the fleet?
-3. **Log rotation** — do append-only logs need archiving?
-4. **Memory staleness** — are project notes up to date?
-5. **Orchestration drift** — are agents following the cardinal rules?
+Each cycle, `collect-signals.mjs` runs these checks and emits `BRIEF.md` + `SIGNALS.json`:
+
+1. **Heartbeat liveness check** — read `.heartbeats/*` (epoch on line 1) + legacy beat files
+   (`.monitor-heartbeat`, `.watchdog-heartbeat`); flag any older than threshold (watchdog 300s,
+   monitor 3600s, others 1800s default) as stale loops; append warning to BRIEF.md.
+
+2. **Git state across repos** — for each repo in config: branch, last commit, uncommitted files,
+   commits ahead of remote. Identifies unpushed work and dirty state.
+
+3. **Memory freshness** — scan project memory files (excluding index/inbox); flag any >30 days old;
+   append summary to BRIEF.md ("N memories stale — keeper should re-verify").
+
+4. **Log rotation** — check append-only logs against max-lines/max-kb thresholds (configurable,
+   default 500 lines / 40 KB). If a log exceeds threshold, emit rotation signal (AUTO tier can
+   invoke rotate_logs.py if available); append rotation summary to BRIEF.md.
+
+5. **Junk-script sprawl detection** — scan temp/scratch roots for throwaway `.py`/.mjs`/`.js` files
+   older than 24 hours, not in a live session directory (avoid false-positives during active work).
+   Count total, estimate quarantinable, list oldest. AUTO tier quarantines confirmed junk into
+   `monitor/quarantine/` with manifest.
+
+6. **Stray scripts in repo roots** — scan recent commits (7d) to detect one-off `.py`/`.mjs`/`.sql`
+   scripts committed directly to repo root (not under proper src/scripts paths). Flag for cleanup.
+
+7. **Security alert review loop** — tail SECURITY-ALERTS.log for new HIGH/MED entries (skip suppressed);
+   each new alert noted in BRIEF.md. Monitor agent does semantic review (REAL vs FP) each cycle.
+
+8. **Respawn watch (Rule 6 retry cap)** — parse agent spawn records; normalize descriptions to
+   prompt-signatures (first ~40 chars, lowercased); count occurrences in recent window (last 50 rows).
+   Flag any signature appearing >3 times as probable hung-agent loop → rule 6 cap breached.
+   Limitation: heuristic may have false positives for intentional similar-task fan-outs.
+
+9. **Cost cadence tracking** — every 3rd cycle, harvest agent spawn ledger and append cost tick
+   to COST-LOG.md (cycle count, timestamp, model distribution). Flags non-haiku specializations.
+
+10. **Unreviewed agent prompts** — run fleet-prompt-extractor.py (if available) to collect NEW
+    spawns since last review; emit count in SIGNALS.json + note in BRIEF.md.
 
 ## Action tiers
 
 - **AUTO (apply immediately, then log to `ACTIONS.log`):**
   - Heartbeat freshness checks (read-only).
-  - Log rotation (invoke `rotate_logs.py` if available).
-  - Persist project memory updates (if applicable).
-  - Quarantine defunct scripts (if a quarantine directory exists).
+  - Log rotation (invoke rotate_logs.py if available; fail-open if not).
+  - Persist heartbeat write (`.monitor-heartbeat` update after cycle).
+  - Quarantine confirmed-junk scripts: move old temp `.py`/`.mjs` (not live session) into
+    `monitor/quarantine/` with manifest — never delete outright.
 
 - **PROPOSE (write to `PROPOSALS.md`, do NOT apply — needs user approval):**
   - Changes to cardinal rules or agent configuration.
-  - Alterations to agent behavior or model choice.
-  - Deletions of anything outside the monitor's own quarantine.
+  - Alterations to agent behavior, model choice, or push targets.
+  - Deletions of anything outside monitor's own quarantine.
   - Any change to orchestration policy.
 
 ## Hard guardrails (inviolable)
@@ -36,31 +69,48 @@ A standing background monitor (Haiku subagent) that watches how the multi-agent
 - Preserve the FIXED GOAL. Improve rules; never rewrite intent.
 - **Subagents are ALWAYS Haiku** (cost optimization). Orchestrator on main thread only.
 - NEVER push destructively or to restricted remotes as an AUTO action.
+- NEVER edit cardinal-rules files (CLAUDE.md, skills/, agent configs) — only PROPOSE changes.
 - Idempotent + additive: safe to run repeatedly; prefer append over overwrite.
 - Stay cheap: read the signal brief, not raw logs. One tight cycle, then sleep.
+- Robust to missing files: treat missing dirs/logs as empty, never crash.
 
 ## Outputs
 
-- `BRIEF.md` — human-readable status snapshot.
-- `SIGNALS.json` — machine-readable metrics and findings.
+- `BRIEF.md` — human-readable status snapshot (overwrite each cycle).
+- `SIGNALS.json` — machine-readable metrics and findings (overwrite each cycle).
 - `ACTIONS.log` — append-only record of AUTO actions taken (timestamped).
 - `PROPOSALS.md` — staged changes awaiting user approval.
-- `quarantine/` (optional) — parked suspect scripts + manifest.
+- `quarantine/` — parked junk scripts + `MANIFEST.tsv` (append-only).
+- `.monitor-heartbeat` — epoch timestamp (line 1) for liveness.
+- `.signal-state.json` — sidecar state (cycle count, seen prompts, etc.).
 
 ## Operating it
 
-1. **Deploy the monitor** under `/power` or as a continuous background task.
-2. **Arm the charter**: customize this file with your project names, repos, and thresholds.
+1. **Deploy the monitor** as a continuous background task (or invoke manually each cycle).
+2. **Customize via config**: populate `aesop.config.json` with your repo paths, thresholds.
 3. **Review PROPOSALS.md** periodically; approve changes or reject them.
 4. **Check ACTIONS.log** to see what was automated.
-5. **Archive BRIEF.md snapshots** if you want a historical record.
+5. **Monitor BRIEF.md** for drift signals; respond to findings.
 
 ## Customization
 
 Edit `collect-signals.mjs` to:
-- Add your own repo paths and project names.
-- Define custom signal collectors (e.g., junk-script detection).
+- Add/remove checks based on your project needs.
+- Configure paths via environment variables (AESOP_ROOT, BRAIN_ROOT, SCRIPTS_ROOT, TEMP_ROOT)
+  or load from aesop.config.json.
 - Set heartbeat thresholds appropriate to your workflow.
-- Integrate security scanners or compliance checks.
+- Integrate custom signal collectors (e.g., compliance checks, custom linters).
+
+See comments in `collect-signals.mjs` for extension points. **Keep it CRLF-safe** (no line
+continuations; maintain Windows+POSIX compatibility).
+
+## Single-instance guard
+
+Before running, check `.monitor-heartbeat` — if <300s old, skip cycle (another monitor is running).
+After cycle completes, update `.monitor-heartbeat` with current epoch.
+
+## Single-writer discipline
 
-See comments in `collect-signals.mjs` for extension points.
+- Only the monitor edits `BRIEF.md`, `SIGNALS.json`, `ACTIONS.log`, `.monitor-heartbeat`, `.signal-state.json`.
+- External processes (human, other agents) write to `PROPOSALS.md` (append or structured inbox).
+- Quarantine manifest is append-only; never edit entries, only add new ones.

package/monitor/collect-signals.mjs

@@ -4,14 +4,41 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 
+// === Configuration ===
+// Load from environment or aesop.config.json; fall back to safe defaults.
 const AESOP_ROOT = process.env.AESOP_ROOT || '.';
+const BRAIN_ROOT = process.env.BRAIN_ROOT || path.join(AESOP_ROOT, '..', '.claude');
+const SCRIPTS_ROOT = process.env.SCRIPTS_ROOT || path.join(AESOP_ROOT, '..', 'scripts');
+const TEMP_ROOT = process.env.TEMP_ROOT || path.join(AESOP_ROOT, '..', 'AppData', 'Local', 'Temp', 'claude');
 const MON = path.join(AESOP_ROOT, 'monitor');
+const STATE_DIR = path.join(AESOP_ROOT, 'state');
+
+// Optional: load aesop.config.json for repo list
+let repos = [];
+let logThresholds = { maxLines: 500, maxKb: 40 };
+try {
+  const configPath = path.join(AESOP_ROOT, 'aesop.config.json');
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  if (config.repos && Array.isArray(config.repos)) {
+    repos = config.repos.map(r => r.path);
+  }
+  if (config.monitor && config.monitor.log_max_lines) {
+    logThresholds.maxLines = config.monitor.log_max_lines;
+  }
+  if (config.monitor && config.monitor.log_max_kb) {
+    logThresholds.maxKb = config.monitor.log_max_kb;
+  }
+} catch {
+  // No config file or parse error; use defaults
+}
+
 const now = Date.now();
 const HOUR = 3600e3;
 const DAY = 24 * HOUR;
 
+// === Utilities ===
 const sh = (cmd, cwd) => {
   try {
     return execSync(cmd, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
@@ -34,103 +61,422 @@ const age = (ms) => {
   return `${(ms / DAY).toFixed(1)}d`;
 };
 
-// Main signal collection
-const signals = {
-  heartbeats: [],
-  rotations: [],
-  unreviewedPrompts: 0,
-  staleMemories: [],
-  respawnWatch: [],
+const walk = (dir, test, out = [], depth = 0) => {
+  if (depth > 6) return out;
+  let ents;
+  try {
+    ents = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of ents) {
+    const fp = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (/node_modules|\.git|target|\.venv|__pycache__/.test(e.name)) continue;
+      walk(fp, test, out, depth + 1);
+    } else if (test(e.name, fp)) {
+      out.push(fp);
+    }
+  }
+  return out;
 };
 
-const brief = [
-  `# Aesop Monitor Brief — ${new Date(now).toISOString()}`,
-  '',
-  '## Status',
-  'Orchestration monitor cycle complete.',
-  '',
-];
+// === Signal Collectors ===
 
 // 1) Heartbeat check
-const beatsDir = path.join(MON, '.heartbeats');
-let beatFiles = [];
-try {
-  const files = fs.readdirSync(beatsDir);
-  beatFiles = files.map((f) => path.join(beatsDir, f));
-} catch {}
-
-const legacyBeats = [
-  path.join(MON, '.monitor-heartbeat'),
-  path.join(AESOP_ROOT, 'state', '.watchdog-heartbeat'),
-];
+function checkHeartbeats() {
+  const staleLoops = [];
+  const beatsDir = path.join(MON, '.heartbeats');
+  const thresholds = { watchdog: 300e3, monitor: 3600e3, default: 1800e3 };
+  let beatFiles = [];
+  try {
+    beatFiles = fs.readdirSync(beatsDir).map(f => path.join(beatsDir, f));
+  } catch {
+    // no .heartbeats dir
+  }
+  const legacyBeats = [
+    path.join(MON, '.monitor-heartbeat'),
+    path.join(STATE_DIR, '.watchdog-heartbeat'),
+  ];
+  beatFiles = beatFiles.concat(legacyBeats.filter(f => fs.existsSync(f)));
+  for (const fp of beatFiles) {
+    try {
+      const content = fs.readFileSync(fp, 'utf8').trim();
+      const epoch = parseInt(content.split('\n')[0], 10);
+      if (!epoch) continue;
+      const beatAge = now - epoch * 1000;
+      const name = path.basename(fp);
+      let threshold = thresholds.default;
+      if (name.includes('watchdog')) threshold = thresholds.watchdog;
+      if (name.includes('monitor')) threshold = thresholds.monitor;
+      if (beatAge > threshold) {
+        staleLoops.push({ name, ageMs: beatAge, threshold });
+      }
+    } catch {
+      // skip invalid heartbeat file
+    }
+  }
+  return staleLoops;
+}
 
-beatFiles = beatFiles.concat(legacyBeats.filter((f) => fs.existsSync(f)));
+// 2) Git state check
+function checkGitState() {
+  const gitState = [];
+  for (const repoPath of repos) {
+    if (!fs.existsSync(repoPath)) continue;
+    const branch = sh('git rev-parse --abbrev-ref HEAD', repoPath);
+    const lastCommit = sh('git log -1 --pretty=%h·%cr·%s', repoPath);
+    const dirty = sh('git status --porcelain', repoPath)
+      .split('\n')
+      .filter(l => l.trim()).length;
+    const ahead = sh('git rev-list --count @{u}..HEAD', repoPath) || '?';
+    gitState.push({
+      repo: path.basename(repoPath),
+      branch,
+      lastCommit,
+      dirty,
+      ahead,
+    });
+  }
+  return gitState;
+}
 
-for (const fp of beatFiles) {
+// 3) Memory freshness check
+function checkMemoryFreshness() {
+  const memoryDir = path.join(BRAIN_ROOT, 'projects', '*', 'memory');
+  const staleMemories = [];
+  let memoryCount = 0;
   try {
-    const content = fs.readFileSync(fp, 'utf8').trim();
-    const epoch = parseInt(content.split('\n')[0], 10);
-    if (!epoch) continue;
-
-    const beatAge = now - epoch * 1000;
-    const name = path.basename(fp);
-    const thresholds = { watchdog: 300e3, monitor: 3600e3, default: 1800e3 };
-    let threshold = thresholds.default;
-    if (name.includes('watchdog')) threshold = thresholds.watchdog;
-    if (name.includes('monitor')) threshold = thresholds.monitor;
-
-    signals.heartbeats.push({
-      name,
-      ageMs: beatAge,
-      threshold,
-      ok: beatAge < threshold,
+    const baseDir = path.join(BRAIN_ROOT, 'projects');
+    if (!fs.existsSync(baseDir)) return { count: 0, staleMemories: [], staleCount: 0 };
+    const projDirs = fs.readdirSync(baseDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => path.join(baseDir, d.name, 'memory'));
+    for (const memDir of projDirs) {
+      if (!fs.existsSync(memDir)) continue;
+      const memFiles = fs.readdirSync(memDir)
+        .filter(f => f.endsWith('.md') && f !== 'MEMORY.md' && f !== 'INBOX.md')
+        .map(f => path.join(memDir, f));
+      memoryCount += memFiles.length;
+      for (const fp of memFiles) {
+        const st = stat(fp);
+        if (st && now - st.mtimeMs > 30 * DAY) {
+          staleMemories.push(path.basename(fp));
+        }
+      }
+    }
+  } catch {
+    // no memory dir
+  }
+  return { count: memoryCount, staleMemories, staleCount: staleMemories.length };
+}
+
+// 4) Log file status check
+function checkLogFiles() {
+  const logFiles = [
+    path.join(STATE_DIR, 'FLEET-BACKUP.log'),
+    path.join(STATE_DIR, 'SECURITY-ALERTS.log'),
+    path.join(MON, 'ACTIONS.log'),
+  ];
+  const logs = [];
+  for (const logPath of logFiles) {
+    const st = stat(logPath);
+    let sizeKb = 0;
+    let lineCount = 0;
+    if (st) {
+      sizeKb = (st.size / 1024).toFixed(1);
+      try {
+        const content = fs.readFileSync(logPath, 'utf8');
+        lineCount = content.split('\n').filter(l => l.trim()).length;
+      } catch {
+        // skip
+      }
+    }
+    logs.push({
+      name: path.basename(logPath),
+      exists: !!st,
+      sizeKb,
+      lineCount,
+      needsRotation: st && (lineCount > logThresholds.maxLines || st.size / 1024 > logThresholds.maxKb),
     });
-  } catch {}
+  }
+  return logs;
+}
+
+// 5) Junk-script sprawl detection
+function detectJunkScripts() {
+  if (!fs.existsSync(TEMP_ROOT)) return { total: 0, quarantinable: 0, bytes: 0, oldest: [], recentCount: 0 };
+  const sessionDirs = (() => {
+    try {
+      return fs.readdirSync(TEMP_ROOT, { withFileTypes: true })
+        .filter(d => d.isDirectory())
+        .map(d => path.join(TEMP_ROOT, d.name));
+    } catch {
+      return [];
+    }
+  })();
+  const liveDirs = new Set();
+  for (const root of sessionDirs) {
+    const files = walk(root, () => true);
+    const newest = Math.max(0, ...files.map(fp => (stat(fp) || { mtimeMs: 0 }).mtimeMs));
+    if (now - newest < 2 * HOUR) {
+      liveDirs.add(root.replace(/\\/g, '/'));
+    }
+  }
+  const inLiveDir = (fp) => [...liveDirs].some(d => fp.replace(/\\/g, '/').startsWith(d));
+  const tempScripts = walk(TEMP_ROOT, n => /\.(py|mjs|js)$/.test(n))
+    .map(fp => ({ fp, st: stat(fp) }))
+    .filter(x => x.st)
+    .map(x => ({
+      fp: x.fp,
+      ageMs: now - x.st.mtimeMs,
+      size: x.st.size,
+      quarantinable: now - x.st.mtimeMs > DAY && !inLiveDir(x.fp),
+    }));
+  const junk = {
+    total: tempScripts.length,
+    quarantinable: tempScripts.filter(x => x.quarantinable).length,
+    bytes: tempScripts.reduce((a, x) => a + x.size, 0),
+    oldest: tempScripts
+      .sort((a, b) => b.ageMs - a.ageMs)
+      .slice(0, 8)
+      .map(x => `${age(x.ageMs)} ${x.fp.split(/[/\\]/).slice(-2).join('/')}`),
+    recentCount: tempScripts.filter(x => now - x.ageMs < HOUR).length,
+  };
+  return junk;
+}
+
+// 6) Stray scripts in repo roots
+function detectStrayRepoScripts() {
+  const strayRepo = [];
+  for (const repoPath of repos) {
+    if (!fs.existsSync(repoPath)) continue;
+    const recent = sh('git log --since="7 days ago" --name-only --pretty=format: --diff-filter=A', repoPath)
+      .split('\n')
+      .map(s => s.trim())
+      .filter(Boolean);
+    for (const f of new Set(recent)) {
+      if (/^[^/\\]+\.(py|mjs|js|sql)$/.test(f)) {
+        strayRepo.push(`${path.basename(repoPath)}: ${f}`);
+      }
+    }
+  }
+  return strayRepo;
+}
+
+// 7) Security alert review
+function checkSecurityAlerts() {
+  const alertLog = path.join(STATE_DIR, 'SECURITY-ALERTS.log');
+  const st = stat(alertLog);
+  if (!st) return { count: 0, highMedCount: 0 };
+  try {
+    const content = fs.readFileSync(alertLog, 'utf8');
+    const lines = content.split('\n');
+    const highMedCount = lines.filter(l => /HIGH|MED/.test(l) && !l.includes('SUPPRESSED-FP')).length;
+    return { count: lines.filter(l => l.trim()).length, highMedCount };
+  } catch {
+    return { count: 0, highMedCount: 0 };
+  }
+}
+
+// 8) Respawn watch (Rule 6 retry cap)
+function detectRespawnWatch() {
+  const respawnWatch = [];
+  const ledgerPath = path.join(BRAIN_ROOT, 'FLEET-LEDGER.md');
+  if (!fs.existsSync(ledgerPath)) return respawnWatch;
+  try {
+    const content = fs.readFileSync(ledgerPath, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('|'));
+    const windowSize = 50;
+    const recentStart = Math.max(0, lines.length - windowSize);
+    const signatures = {};
+    const normalize = (desc) => (desc || '').substring(0, 40).toLowerCase().trim();
+    for (let i = recentStart; i < lines.length; i++) {
+      const line = lines[i];
+      const parts = line.split('|').map(s => s.trim());
+      if (parts.length >= 4) {
+        const description = parts[3];
+        const sig = normalize(description);
+        if (sig) signatures[sig] = (signatures[sig] || 0) + 1;
+      }
+    }
+    for (const [sig, count] of Object.entries(signatures)) {
+      if (count > 3) {
+        respawnWatch.push({
+          signature: sig,
+          count,
+          warning: `RESPAWN CAP: '${sig}' dispatched ${count} times — investigate hang or mark BLOCKED`,
+        });
+      }
+    }
+  } catch {
+    // fail-open on error
+  }
+  return respawnWatch;
+}
+
+// 9) Cost cadence tracking
+function trackCostCadence() {
+  const prevStateFile = path.join(MON, '.signal-state.json');
+  let prevState = {};
+  try {
+    prevState = JSON.parse(fs.readFileSync(prevStateFile, 'utf8'));
+  } catch {
+    // no prev state
+  }
+  const cycleCount = (prevState.cycleCount || 0) + 1;
+  let costTick = null;
+  if (cycleCount % 3 === 0) {
+    costTick = {
+      cycle: cycleCount,
+      ts: new Date(now).toISOString(),
+      summary: 'Cost cycle tick recorded',
+    };
+  }
+  return { cycleCount, costTick };
+}
+
+// 10) Unreviewed prompts count
+function checkUnreviewedPrompts() {
+  const seenFile = path.join(MON, '.fleet-prompts-seen.json');
+  let prevSeen = {};
+  try {
+    prevSeen = JSON.parse(fs.readFileSync(seenFile, 'utf8'));
+  } catch {
+    // no prev state
+  }
+  // Without fleet_prompt_extractor.py available, emit 0
+  // In production, invoke spawnSync('python', [...fleet_prompt_extractor.py...])
+  return 0;
+}
+
+// === Main ===
+const staleLoops = checkHeartbeats();
+const gitState = checkGitState();
+const memory = checkMemoryFreshness();
+const logFiles = checkLogFiles();
+const junk = detectJunkScripts();
+const strayRepo = detectStrayRepoScripts();
+const alerts = checkSecurityAlerts();
+const respawnWatch = detectRespawnWatch();
+const { cycleCount, costTick } = trackCostCadence();
+const unreviewedPrompts = checkUnreviewedPrompts();
+
+const signals = {
+  timestamp: new Date(now).toISOString(),
+  cycleCount,
+  heartbeats: { staleCount: staleLoops.length, details: staleLoops },
+  git: gitState,
+  memory,
+  logs: logFiles,
+  junk,
+  strayRepo,
+  alerts,
+  respawnWatch,
+  costTick,
+  unreviewedPrompts,
+};
+
+const brief = [];
+brief.push(`# Aesop Monitor Brief — ${signals.timestamp}`);
+brief.push('');
+brief.push('## Heartbeat check');
+if (staleLoops.length === 0) {
+  brief.push('✓ All heartbeats fresh (watchdog 300s, monitor 3600s, others 1800s).');
+} else {
+  brief.push(`✗ **${staleLoops.length} stale loop(s)** detected:`);
+  for (const sl of staleLoops) {
+    brief.push(`  - ${sl.name}: ${age(sl.ageMs)} (threshold: ${age(sl.threshold)})`);
+  }
 }
+brief.push('');
 
-brief.push('## Heartbeats');
-if (signals.heartbeats.length === 0) {
-  brief.push('No heartbeats detected yet.');
+brief.push('## Git state');
+if (gitState.length === 0) {
+  brief.push('No repos configured.');
 } else {
-  for (const hb of signals.heartbeats) {
-    const status = hb.ok ? '✓' : '✗';
-    brief.push(`- ${status} ${hb.name}: ${age(hb.ageMs)}`);
+  for (const g of gitState) {
+    const status = g.dirty === 0 && g.ahead === '0' ? '✓' : '⚠';
+    brief.push(`- ${status} **${g.repo}** [${g.branch}] — dirty: ${g.dirty}, ahead: ${g.ahead}`);
+    if (g.lastCommit) brief.push(`  ${g.lastCommit}`);
   }
 }
 brief.push('');
 
-// 2) Log file status
-brief.push('## Logs');
-const logFiles = [
-  path.join(AESOP_ROOT, 'state', 'FLEET-BACKUP.log'),
-  path.join(AESOP_ROOT, 'state', 'SECURITY-ALERTS.log'),
-];
+brief.push('## Memory');
+brief.push(`- ${memory.count} memory file(s)`);
+if (memory.staleCount > 0) {
+  brief.push(`  ⚠ **${memory.staleCount} stale** (>30d): ${memory.staleMemories.join(', ')}`);
+}
+brief.push('');
 
-for (const logFile of logFiles) {
-  const st = stat(logFile);
-  if (st) {
-    brief.push(`- ${path.basename(logFile)}: ${st.size} bytes`);
-  } else {
-    brief.push(`- ${path.basename(logFile)}: (not found)`);
+brief.push('## Log files');
+const needsRotation = logFiles.filter(l => l.needsRotation);
+if (needsRotation.length === 0) {
+  brief.push('✓ All logs within thresholds.');
+} else {
+  brief.push(`⚠ **${needsRotation.length} log(s) need rotation:**`);
+  for (const l of needsRotation) {
+    brief.push(`  - ${l.name}: ${l.lineCount} lines, ${l.sizeKb}kb`);
   }
 }
 brief.push('');
 
-// 3) Placeholder for future signal collectors
-brief.push('## Notes');
-brief.push('This is a template monitor. Extend collect-signals.mjs to add:');
-brief.push('- Junk-script sprawl detection');
-brief.push('- Memory gap detection');
-brief.push('- Rule friction analysis');
-brief.push('- Orchestration health checks');
+brief.push('## Junk-script sprawl (temp/scratch)');
+brief.push(`- ${junk.total} total scripts, ${(junk.bytes / 1024).toFixed(0)}kb`);
+brief.push(`  Quarantinable (>24h, not live): ${junk.quarantinable}`);
+if (junk.oldest.length > 0) {
+  brief.push('  Oldest:');
+  for (const o of junk.oldest) {
+    brief.push(`    ${o}`);
+  }
+}
+if (strayRepo.length > 0) {
+  brief.push('');
+  brief.push('## Stray repo scripts (7d)');
+  for (const s of strayRepo) {
+    brief.push(`- ${s}`);
+  }
+}
 brief.push('');
 
+brief.push('## Security');
+brief.push(`- Alert log: ${alerts.count} entries, ${alerts.highMedCount} HIGH/MED`);
+brief.push('');
+
+brief.push('## Respawn watch (Rule 6 retry cap)');
+if (respawnWatch.length === 0) {
+  brief.push('✓ No retry-cap breaches (all signatures ≤3 occurrences).');
+} else {
+  brief.push(`⚠ **${respawnWatch.length} signature(s) exceeded 3-attempt limit:**`);
+  for (const rw of respawnWatch) {
+    brief.push(`  - ${rw.warning}`);
+  }
+  brief.push('  (Note: distinguish legitimate fan-outs from identical retries; manual review recommended.)');
+}
+brief.push('');
+
+brief.push('## Cost tracking');
+brief.push(`- Cycle: ${cycleCount}${costTick ? ' — tick recorded' : ''}`);
+if (costTick) {
+  brief.push(`  ${costTick.ts}`);
+}
+brief.push('');
+
+brief.push('## Unreviewed prompts');
+brief.push(`- ${unreviewedPrompts} new prompt(s) awaiting semantic review`);
+brief.push('');
+
+brief.push('_Refinement points → act per CHARTER.md (AUTO safe, PROPOSE rule changes). Goal is fixed._');
+
 // Write outputs
 try {
   fs.mkdirSync(MON, { recursive: true });
   fs.writeFileSync(path.join(MON, 'BRIEF.md'), brief.join('\n'), 'utf8');
   fs.writeFileSync(path.join(MON, 'SIGNALS.json'), JSON.stringify(signals, null, 2), 'utf8');
-  console.log('Monitor signals collected. See BRIEF.md and SIGNALS.json.');
+  fs.writeFileSync(path.join(MON, '.monitor-heartbeat'), String(Math.floor(now / 1000)), 'utf8');
+  const summaryLine = `stale-loops: ${staleLoops.length}, repos-dirty: ${gitState.filter(g => g.dirty > 0).length}, stale-mem: ${memory.staleCount}, logs-need-rotation: ${needsRotation.length}, junk-quarantinable: ${junk.quarantinable}, stray-repo-scripts: ${strayRepo.length}, alerts-high-med: ${alerts.highMedCount}, respawn-watch: ${respawnWatch.length}, cycle: ${cycleCount}`;
+  console.log(summaryLine);
 } catch (e) {
   console.error('Failed to write signals:', e.message);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matt82198/aesop",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Multi-agent orchestration for AI coding agents, designed to survive failure — a plain-file brain, git as the only durable layer, cheap subagent fleets, and guardrails enforced in code.",
   "bin": {
     "aesop": "bin/cli.js"
@@ -45,6 +45,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-  }
+  "scripts": {}
 }