@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.5

package/dash/dash-extra.mjs

@@ -1,18 +1,62 @@
 // Detect and render running Claude agents from transcripts.
 // Usage: node dash-extra.mjs [--json]
-//   --json: output JSON array of agents (for web dashboard /data endpoint)
+//   --json: output JSON array of agents with rich metadata (for web dashboard)
 //   (default): render TUI text output (for terminal dashboard)
+//
+// Enhanced JSONL parsing: extracts dispatch prompt, token counts, runtime, task label
+// Robust: tolerates malformed lines, caps read size on large files
 
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
+
+// Configuration: env var > config file > built-in default
+// Helper: load aesop.config.json if it exists
+function loadConfigFile(aesopRoot) {
+  try {
+    const configPath = path.join(aesopRoot, 'aesop.config.json');
+    if (fs.existsSync(configPath)) {
+      return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+  } catch {
+    // Parse error or file doesn't exist; ignore
+  }
+  return {};
+}
+
+// Helper: expand ~ and environment variables in paths for portability
+function expandPath(pathStr) {
+  if (!pathStr) return pathStr;
+  // Expand ~ to home directory
+  if (pathStr.startsWith('~')) {
+    return path.join(os.homedir(), pathStr.slice(1));
+  }
+  // Expand environment variables like $VAR or %VAR%
+  return pathStr.replace(/\$\{?([A-Z_]+)\}?/gi, (match, varName) => {
+    return process.env[varName] || match;
+  });
+}
 
-// Configuration from environment
 const AESOP_ROOT = process.env.AESOP_ROOT || path.join(process.env.HOME || '.', 'aesop');
+const config = loadConfigFile(AESOP_ROOT);
+
 const TRANSCRIPTS_ROOT = path.resolve(
-  process.env.AESOP_TRANSCRIPTS_ROOT || path.join(process.env.HOME || '.', '.claude', 'projects')
+  expandPath(
+    process.env.AESOP_TRANSCRIPTS_ROOT ||
+    config.transcripts_root ||
+    path.join(process.env.HOME || '.', '.claude', 'projects')
+  )
 );
-const SCAN_DIR = path.join(AESOP_ROOT, 'scan');
-const ALERTS_LOG = path.join(SCAN_DIR, 'SECURITY-ALERTS.log');
+
+// Resolve state_root: env var > config > default
+const STATE_ROOT = path.resolve(
+  expandPath(
+    process.env.AESOP_STATE_ROOT ||
+    config.state_root ||
+    path.join(AESOP_ROOT, 'state')
+  )
+);
+const ALERTS_LOG = path.join(STATE_ROOT, 'SECURITY-ALERTS.log');
 
 // ANSI colors for TUI output
 const c = {
@@ -29,6 +73,110 @@ const c = {
 const now = Date.now();
 const out = [];
 
+// Activity window: only include files modified within the last 12 minutes
+const ACTIVITY_WINDOW = 12 * 60 * 1000;
+
+// Depth limit to match monitor's equivalent (prevent unbounded recursion on growing tree)
+const MAX_DEPTH = 6;
+
+// Parse JSONL agent transcript and extract rich metadata
+function parseAgentJsonl(filePath) {
+  const metadata = {
+    promptFull: '',
+    taskLabel: '',
+    tokensUsed: 0,
+    startedAt: null,
+    lastActivity: null,
+    runtimeSeconds: 0,
+    project: ''
+  };
+
+  try {
+    // Derive project from path: transcripts_root/PROJECT/session/...
+    const relPath = path.relative(TRANSCRIPTS_ROOT, filePath);
+    const parts = relPath.split(path.sep);
+    if (parts.length > 0) {
+      metadata.project = parts[0];
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+
+    // Cap reading: first 50 + last 50 lines to avoid expensive parsing on huge files
+    const linesToRead = [];
+    if (lines.length <= 100) {
+      linesToRead.push(...lines);
+    } else {
+      linesToRead.push(...lines.slice(0, 50));
+      linesToRead.push(...lines.slice(-50));
+    }
+
+    let firstTimestamp = null;
+    let lastTimestamp = null;
+
+    for (const line of linesToRead) {
+      if (!line.trim()) continue;
+
+      try {
+        const obj = JSON.parse(line);
+
+        // Extract dispatch prompt from first user message
+        if (obj.type === 'user' && obj.message && !metadata.promptFull) {
+          const content = obj.message.content;
+          if (typeof content === 'string') {
+            metadata.promptFull = content;
+            // Extract task label: first line of prompt, capped at 80 chars
+            const firstLine = content.split('\n')[0];
+            metadata.taskLabel = firstLine.substring(0, 80);
+          }
+        }
+
+        // Track timestamps
+        if (obj.timestamp) {
+          const ts = new Date(obj.timestamp).getTime();
+          if (!firstTimestamp) {
+            firstTimestamp = ts;
+            metadata.startedAt = obj.timestamp;
+          }
+          lastTimestamp = ts;
+          metadata.lastActivity = obj.timestamp;
+        }
+
+        // (token accumulation is a separate FULL-file pass below — sampling
+        //  only 100 lines under-counts tokens badly on long transcripts)
+      } catch {
+        // Silently skip malformed JSON lines
+        continue;
+      }
+    }
+
+    // Token total: scan EVERY line (usage records are spread throughout the
+    // transcript, not just the sampled head/tail). Cheap substring pre-filter
+    // keeps this fast on huge files by JSON-parsing only candidate lines.
+    for (const line of lines) {
+      if (!line.includes('"usage"')) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.type === 'assistant' && obj.usage) {
+          const { input_tokens = 0, output_tokens = 0 } = obj.usage;
+          metadata.tokensUsed += input_tokens + output_tokens;
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    // Calculate runtime in seconds
+    if (firstTimestamp && lastTimestamp) {
+      metadata.runtimeSeconds = Math.floor((lastTimestamp - firstTimestamp) / 1000);
+    }
+  } catch {
+    // If file read fails, return empty metadata
+  }
+
+  return metadata;
+}
+
 // Read alerts log if present
 let slog = [];
 try {
@@ -37,14 +185,22 @@ try {
   }
 } catch {}
 
-// Recursively walk directory tree to find agent-*.jsonl files
-function walk(dir, accumulator) {
+// Recursively walk directory tree to find agent-*.jsonl files.
+// Respects depth limit. Activity window filtering happens per-file, not per-directory,
+// to avoid hiding active agents in dirs whose mtime was frozen at creation.
+function walk(dir, accumulator, depth = 0) {
+  // Stop recursion if depth exceeds limit
+  if (depth > MAX_DEPTH) return;
+
   try {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
       if (entry.isDirectory()) {
-        walk(fullPath, accumulator);
+        // Always descend into subdirectories (respecting depth limit only)
+        // Do NOT prune based on directory mtime, as directories don't update
+        // when files inside are appended to.
+        walk(fullPath, accumulator, depth + 1);
       } else if (/^agent-.*\.jsonl$/.test(entry.name)) {
         accumulator.push(fullPath);
       }
@@ -68,8 +224,13 @@ files = files
     return { f, mtime };
   })
   .filter(x => now - x.mtime < 12 * 60 * 1000)
-  .sort((a, b) => b.mtime - a.mtime)
-  .slice(0, 8);
+  .sort((a, b) => b.mtime - a.mtime);
+
+// True active total. The 8 below is a TUI terminal-space limit ONLY — not the
+// real count. The web (--json) emits ALL active agents; the TUI shows 8 + "N more".
+const totalActive = files.length;
+const runningCount = files.filter(x => now - x.mtime < 120 * 1000).length;
+const TUI_ROW_CAP = 8;
 
 // Extract description/hint from first ~60KB of agent transcript
 function label(filePath) {
@@ -93,14 +254,13 @@ function label(filePath) {
 // TUI output: render heading
 out.push(`${c.B}  FLEET AGENTS${c.X} ${c.D}(green=running · severity-colored if flagged)${c.X}`);
 
-if (files.length === 0) {
+if (totalActive === 0) {
   out.push(`    ${c.D}(no active fleet agents in last 12 min)${c.X}`);
 }
 
-let runningCount = 0;
-
-// Render each agent
-for (const { f, mtime } of files) {
+// Render each agent (TUI caps rows to TUI_ROW_CAP for terminal space; the counts
+// above are the true totals across all active agents)
+for (const { f, mtime } of files.slice(0, TUI_ROW_CAP)) {
   const basename = path.basename(f);
   const ageSeconds = Math.round((now - mtime) / 1000);
 
@@ -110,8 +270,6 @@ for (const { f, mtime } of files) {
   let statusColor = ageSeconds < 120 ? c.G : c.D;
   let statusText = ageSeconds < 120 ? 'running' : 'idle';
 
-  if (ageSeconds < 120) runningCount++;
-
   // Recolor based on alert severity
   if (alertsForAgent.some(l => l.includes('SUSPICIOUS'))) {
     statusColor = c.R;
@@ -140,8 +298,12 @@ for (const { f, mtime } of files) {
   );
 }
 
-if (files.length > 0) {
-  out.push(`    ${c.D}${runningCount} running, ${files.length - runningCount} idle (last 12 min)${c.X}`);
+if (totalActive > TUI_ROW_CAP) {
+  out.push(`    ${c.D}… +${totalActive - TUI_ROW_CAP} more active (showing ${TUI_ROW_CAP} of ${totalActive})${c.X}`);
+}
+
+if (totalActive > 0) {
+  out.push(`    ${c.D}${runningCount} running, ${totalActive - runningCount} idle (last 12 min)${c.X}`);
 }
 
 // Output
@@ -170,11 +332,22 @@ if (process.argv.includes('--json')) {
       .replace(/\.jsonl$/, '')
       .slice(0, 13);
 
+    // Parse JSONL for rich metadata
+    const metadata = parseAgentJsonl(f);
+
     agents.push({
       id: agentId,
-      age_s: ageSeconds,
+      project: metadata.project,
       status: status,
-      hint: label(f).slice(0, 60)
+      age_s: ageSeconds,
+      hint: label(f).slice(0, 60),
+      // New enriched fields
+      startedAt: metadata.startedAt,
+      lastActivity: metadata.lastActivity,
+      runtimeSeconds: metadata.runtimeSeconds,
+      tokensUsed: metadata.tokensUsed,
+      taskLabel: metadata.taskLabel,
+      promptFull: metadata.promptFull
     });
   }
   process.stdout.write(JSON.stringify(agents) + '\n');

package/dash/watchdog-gui.sh

@@ -21,6 +21,7 @@ SLOG="$AESOP_ROOT/state/SECURITY-ALERTS.log"
 HB="$AESOP_ROOT/state/.watchdog-heartbeat"
 REPOS_FILE="$AESOP_ROOT/state/.watchdog-repos.json"
 HB_DIR="$AESOP_ROOT/state/.heartbeats"
+CONFIG_FILE="$AESOP_ROOT/aesop.config.json"
 
 SPINNER=0
 FIRST_FRAME=1
@@ -29,15 +30,31 @@ FIRST_FRAME=1
 trap 'printf "\033[?25h"; exit 0' INT TERM
 printf '\033[?25l'
 
+# Load heartbeat thresholds from config; fallback to built-in defaults
+load_hb_thresholds() {
+  if [ -f "$CONFIG_FILE" ] && command -v jq >/dev/null 2>&1; then
+    HB_THRESHOLD_MONITOR=$(jq -r '.monitor.heartbeat_thresholds.monitor // 3600' "$CONFIG_FILE" 2>/dev/null || echo 3600)
+    HB_THRESHOLD_WATCHDOG=$(jq -r '.monitor.heartbeat_thresholds.watchdog // 300' "$CONFIG_FILE" 2>/dev/null || echo 300)
+    HB_THRESHOLD_DEFAULT=$(jq -r '.monitor.heartbeat_thresholds.default // 1800' "$CONFIG_FILE" 2>/dev/null || echo 1800)
+  else
+    HB_THRESHOLD_MONITOR=3600
+    HB_THRESHOLD_WATCHDOG=300
+    HB_THRESHOLD_DEFAULT=1800
+  fi
+}
+
 get_hb_threshold() {
   local name="$1"
   case "$name" in
-    *monitor*) echo 3600;;
-    *watchdog*) echo 300;;
-    *) echo 300;;
+    *monitor*) echo "$HB_THRESHOLD_MONITOR";;
+    *watchdog*) echo "$HB_THRESHOLD_WATCHDOG";;
+    *) echo "$HB_THRESHOLD_DEFAULT";;
   esac
 }
 
+# Load thresholds at startup
+load_hb_thresholds
+
 render_frame() {
   local FRAME=""
   FRAME="${FRAME}${B}${C}== FLEET WATCHDOG${X}\n"
@@ -122,8 +139,8 @@ while true; do
     WD="${R}STALE${X}"
   fi
 
-  HI=$(grep -v '^RESOLVED-FP' "$SLOG" 2>/dev/null | grep -c ' HIGH '); HI=${HI:-0}
-  ME=$(grep -v '^RESOLVED-FP' "$SLOG" 2>/dev/null | grep -c ' MED '); ME=${ME:-0}
+  set -- $(awk '/^RESOLVED-FP/ { next } / HIGH / { hi++ } / MED / { me++ } END { print hi+0 " " me+0 }' "$SLOG" 2>/dev/null || echo '0 0')
+  HI="$1"; ME="$2"
 
   if [ "$FIRST_FRAME" -eq 1 ]; then
     printf '\033[2J'
@@ -133,7 +150,7 @@ while true; do
   fi
 
   render_frame | while IFS= read -r line; do
-    printf '%b\033[K\n' "$line"
+    printf '%s\033[K\n' "$line"
   done
   printf '\033[J'
 

package/docs/BEHAVIORAL-PR-REVIEW.md

@@ -0,0 +1,86 @@
+# Behavioral PR Review Checklist
+
+For pull requests that modify operational rules, agent behavior, monitoring, or orchestration policy, follow this checklist **before merging**.
+
+## 1. Rule & Cardinal Alignment
+
+- [ ] Rule named explicitly (e.g., "Rule 3: Reliability core" or "Cardinal Rule 1: Dispatch model")
+- [ ] PR title and description clearly state which rule(s) are affected
+- [ ] Change aligns with (or explicitly updates) `docs/CARDINAL-RULES.md`
+- [ ] No contradictions with other cardinal rules or guardrails
+
+## 2. Blast Radius & Impact
+
+- [ ] Impact scope documented (e.g., "affects all new monitor cycles", "affects heartbeat thresholds only", "no impact on running agents")
+- [ ] Backward compatibility assessed (breaking changes require migration plan)
+- [ ] Dependent systems identified (e.g., if monitor behavior changes, does ACTIONS.log parsing break?)
+- [ ] Risk of silent failures assessed (e.g., does fallback-to-default mask issues?)
+
+## 3. Verification & Testing
+
+- [ ] Reproducible test steps provided (not "tested locally" — state what was tested)
+- [ ] Test output attached or described (e.g., "ran `node monitor/collect-signals.mjs` twice, no duplicate PROPOSALS.md entries")
+- [ ] Idempotency verified if applicable (safe to run multiple times in same cycle?)
+- [ ] Edge cases covered (what if config missing? what if file unreadable?)
+
+## 4. Rollback & Recovery
+
+- [ ] Rollback plan documented (e.g., "revert commit + clear `.signal-state.json` + restart monitor")
+- [ ] Rollback tested if possible (e.g., apply change, verify it works, revert, verify rollback works)
+- [ ] No irreversible side effects (don't delete files without append-only logging first)
+
+## 5. Single-Writer & Proposal Provenance
+
+- [ ] If PROPOSALS.md or ACTIONS.log touched: confirm monitor still writes atomically (append-only)
+- [ ] If new proposal emission logic added: confirm idempotency (no duplicate proposals from re-runs)
+- [ ] If proposal came from monitor-collected signal: CHARTER.md action tier justified (AUTO vs PROPOSE)
+- [ ] If proposal came from human: documented in PROPOSALS.md (what human, when, why)
+
+## 6. Documentation & Handoff
+
+- [ ] Related doc updated (CHARTER.md, CARDINAL-RULES.md, GOVERNANCE.md, etc.)
+- [ ] Code comments added for non-obvious rule enforcement logic
+- [ ] Affected stakeholders notified (e.g., if monitor behavior changes, note in CONTRIBUTING.md)
+
+---
+
+## Worked Example: Cost-cap-per-repo Change
+
+**PR Title:** `feat(dispatch): Enforce Haiku cost cap per-repo instead of global`
+
+**Rule affected:** Cardinal Rule 1 (dispatch model), Rule 6 (commit discipline)
+
+**Blast radius:** All new agent dispatches via claude-code-cli; existing running agents unaffected
+
+**Verification:**
+- Ran dispatch-test-harness.sh with 3 mock repos, 5 Haiku spawns per repo
+- Confirmed ledger recorded per-repo cost separately
+- Rolled back, confirmed ledger reverted to single global entry
+- No test script in package.json; test via integration harness
+
+**Rollback:** Revert commit, clear `~/.claude/projects/*/FLEET-LEDGER.md`, restart orchestrator
+
+**Documentation:** Updated DISPATCH-MODEL.md section "Cost tracking" with new per-repo tracking format
+
+**Result:** ✓ Merged after review
+
+---
+
+## When to Request Changes (🔴 Critical)
+
+- Missing verification or test steps
+- Rollback plan untested or implausible
+- Proposal came from monitor but action tier (AUTO/PROPOSE) unjustified
+- Change introduces hardcoded paths, secrets, or usernames
+- Backward-incompatible change with no migration documented
+- Cardinal rule contradiction or guardrail violation
+
+## When to Suggest (💡 Consider)
+
+- Minor documentation clarification
+- Additional edge case to test (not required, but good to consider)
+- Related code that could benefit from similar fix (out of scope for this PR, open separate issue)
+
+## Proposal lifecycle
+
+Use `node tools/proposals.mjs list` to review pending proposals in monitor/PROPOSALS.md. To approve a proposal, run `node tools/proposals.mjs accept <signal-key>` (moves block to PROPOSALS-LOG.md under `## ACCEPTED <timestamp>`); to decline, run `reject <signal-key>` instead. Both commands are idempotent: re-running on an already-moved proposal is a no-op.

package/docs/CHECKPOINTING.md

@@ -0,0 +1,100 @@
+# Durable Checkpointing & State Management
+
+**TL;DR**: Maintain STATE.md (intent, phase, NEXT STEPS) + BUILDLOG.md (append-only progress log). On resume after context loss, read both, verify from disk, then proceed. Survives session wipes, enables rapid context handoff, and keeps orchestrator cheap (no re-reading full history).
+
+---
+
+## STATE.md: Authoritative intent & decisions
+
+**Purpose**: Single source of truth for current intent, locked decisions, data model/contracts, key file paths, current phase, and explicit NEXT STEPS.
+
+**Structure**:
+- What we're trying to build (intent, not mechanism)
+- Locked decisions (technology choices, data models, architecture trade-offs)
+- Current phase (e.g., "Phase 2: API integration")
+- Explicit NEXT STEPS (enumerated, actionable, owner assigned)
+- Key paths (file locations, service boundaries, data contracts)
+
+**Discipline**: Hand-update STATE.md at phase boundaries. Never leave it stale; always update BEFORE moving to the next phase. An out-of-date STATE.md is worse than no STATE.md (it's actively misleading).
+
+**Recovery use case**: If context is lost or a session is interrupted, STATE.md is the first file to read. It answers "where were we?" and "what's next?" without re-reading logs or transcripts.
+
+## BUILDLOG.md: Append-only progress snapshots
+
+**Purpose**: Timestamped, immutable record of progress. Never overwrite or edit earlier entries (append-only discipline).
+
+**Pattern**: Each entry contains:
+- Timestamp (ISO 8601 or human-readable)
+- Work completed (features, bugs, integrations, tests)
+- Status (green / yellow / blocked / pending decision)
+- Next step or blocker (for orchestrator reference)
+
+**Example**:
+```
+[2026-07-11 13:00] Phase 1 complete: scaffolding + unit tests passing
+[2026-07-11 14:30] API integration: 2 endpoints done, 1 blocked on schema review
+[2026-07-11 15:45] BLOCKED: waiting for design review on request body format
+[2026-07-11 16:20] Design approved; resume API endpoint 3 implementation
+```
+
+**Append-only rule**: Agents and loops append one line per work unit. The orchestrator never edits earlier entries. This prevents accidental data loss and keeps the log auditable.
+
+## Recovery workflow: On context loss or resume
+
+When you resume work (context wipe, new session, task restart), follow this protocol:
+
+1. **Read STATE.md**: Understand intent, locked decisions, and current phase
+2. **Skim BUILDLOG.md**: Review recent progress and current blockers
+3. **Run git log**: Verify actual file state and recent commits vs. STATE.md
+4. **Sync**: If STATE.md is stale, update it before proceeding; if reality diverged from STATE.md, note the delta and surface it
+
+**Never invent state.** Verify everything from disk (git log, file timestamps, handoff files) before trusting in-memory recollection. Disk is the source of truth.
+
+## Dated archive strategy: Log rotation
+
+When BUILDLOG.md grows beyond **~200 lines or ~20 KB**:
+
+1. Identify the cut point (e.g., last entry from yesterday or the last "green" state marker)
+2. Move older entries to `BUILDLOG-YYYY-MM.md` (dated archive)
+3. Keep only recent entries in the live `BUILDLOG.md`
+4. Commit both files
+5. Update any orchestrator references to point to the live file
+
+**Why rotation?** The orchestrator reads the live BUILDLOG.md frequently; a 50-line log is faster and cheaper than 500 lines. Full history remains available in archives for auditing and debugging.
+
+**Example**:
+- Live file: `BUILDLOG.md` (entries from 2026-07-08 onward)
+- Archive: `BUILDLOG-2026-07.md` (entries through 2026-07-07)
+
+## Handoff metadata across team boundaries
+
+When handing off work to another team member or agent:
+
+- Include the git commit hash (anchors history)
+- Snapshot key file paths and their state
+- Document any external dependencies or waiting states
+- List any environment assumptions (database schema versions, external service versions, etc.)
+
+Example:
+```
+[2026-07-12 09:00] Handing off to feature-team: commit abc1234
+  - Database schema: v3.2 (see db/migrations/)
+  - API contracts frozen in openapi.yaml
+  - Waiting for design review on component layout
+  - Next: implement sign-up form based on design feedback
+```
+
+## Multi-session coordination
+
+For work spanning multiple people or sessions:
+
+1. **Orchestrator updates STATE.md** after each major decision or phase change
+2. **Subagents append to BUILDLOG.md** after each work unit
+3. **On session resume**, orchestrator syncs from disk and briefs the incoming worker
+4. **Hand-updates to STATE.md** happen only at phase boundaries (not every commit)
+
+This keeps overhead low (one STATE.md update per phase, one BUILDLOG line per work unit) while preserving a clear audit trail.
+
+---
+
+**Why STATE.md + BUILDLOG.md?** They ensure work survives context loss, enables rapid resume without re-reading history, and provides an audit trail for debugging. Together with git history and the heartbeat protocol, they form the **checkpointing core** that makes orchestration systems reliable and recoverable.

package/docs/DISPATCH-MODEL.md

@@ -1,5 +1,9 @@
 # Aesop Dispatch Model — Cost & Orchestration Patterns
 
+**TL;DR**: Spawn 5–8 cheap Haiku subagents in parallel (not serial Opus). Result: **lower cost (Haiku ~1/3 Sonnet) plus a parallel speedup** via parallelism. Rule: subagents ALWAYS Haiku unless scoped work genuinely exceeds its capability (rare).
+
+---
+
 ## The fable conceit
 
 In Aesop's Fables, Aesop (the narrator) directs the characters (tortoise, hare, fox, etc.) through moral tales. Here, **Aesop (the orchestrator)** directs a fleet of **Fables (the subagents)** toward reliable task completion.
@@ -21,7 +25,7 @@ The tortoise represents deliberate, resourceful thinking; the hare, quick speed.
 1 orchestrator (Opus, 5 min thinking)  = 5 × 60 = 300 tokens
 5 subagents (Haiku, 2 min each)        = 5 × 2 × 20 = 200 tokens
 Total                                   = 500 tokens/session
-= **83% savings** vs all-Opus
+= a large saving vs all-Opus (Haiku is 1/5 the per-token cost of Opus)
 ```
 
 ### Scaling to 10 parallel domains
@@ -30,14 +34,14 @@ Total                                   = 500 tokens/session
 1 orchestrator (Opus, 8 min)       = 480 tokens
 10 subagents (Haiku, 3 min each)   = 600 tokens
 Total                              = 1,080 tokens
-= **90% savings** vs 10 Opus tasks
+= a large saving vs all-Opus (most domains run on Haiku at 1/5 Opus cost)
 ```
 
 ## 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.
+**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 — most of the work runs on Haiku at 1/5 the per-token cost of Opus. 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**
@@ -79,7 +83,7 @@ Orchestrator → Phase 1
         └─ Haiku-4: Integration test
         
 Orchestrator reassembles + QA
-Total cost: still 1 Opus + 4 Haiku = **90% savings**
+Total cost: 1 Opus orchestrator + 4 Haiku implementers — the four implementers run at 1/5 the per-token cost of Opus
 ```
 
 ### Pattern 3: Hierarchical (supervisor + workers)
@@ -96,7 +100,7 @@ Orchestrator
 │  └─ Haiku-5: config module
 └─ (Sonnet synthesizes reviews into final report)
 
-Cost: 1 Opus + 1 Sonnet + 5 Haiku = ~$0.015 (still 75% savings)
+Cost: 1 Opus + 1 Sonnet + 5 Haiku = ~1/3 the cost of running every domain on Opus
 ```
 
 ## Decision flowchart
@@ -118,7 +122,7 @@ Is this task scoped to <5 min reasoning?
 
 ### ❌ All-Opus fleet
 
-**Cost**: 10× baseline. **Why**: throws CPU power at problems that are scoped.
+**Cost**: higher — Sonnet/Opus per-token rates. **Why**: throws CPU power at problems that are scoped.
 
 **Fix**: Decompose into Haiku-sized tasks.
 
@@ -204,4 +208,4 @@ Surfacing to the user after 3 retries ensures visibility and prevents silent cos
 
 ---
 
-**Summary**: Aesop's dispatch model trades a small amount of orchestration complexity for **10× cost savings** and **4× speed** (via parallelism). It works by keeping subagents small, orchestrator lean, and feedback constant.
+**Summary**: Aesop's dispatch model trades a small amount of orchestration complexity for **lower cost** (Haiku ~1/3 Sonnet) and **parallel speedup** (via parallelism). It works by keeping subagents small, orchestrator lean, and feedback constant.