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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@matt82198/aesop",
-  "version": "0.1.0-beta.3",
-  "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.",
+  "version": "0.1.0-beta.5",
+  "description": "Multi-agent orchestration for AI coding agents, designed to survive failure \u00e2\u20ac\u201d a plain-file brain, git as the only durable layer, cheap subagent fleets, and guardrails enforced in code.",
   "bin": {
     "aesop": "bin/cli.js"
   },
@@ -11,10 +11,16 @@
     "daemons/",
     "dash/",
     "monitor/",
+    "mcp/",
     "tools/",
     "ui/",
     "docs/",
+    "hooks/",
+    "skills/",
+    "state_store/",
+    "scan/",
     "aesop.config.example.json",
+    "CLAUDE-TEMPLATE.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -45,5 +51,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {}
+  "scripts": {
+    "test": "node --test --test-force-exit --test-timeout=60000 tests/**/*.test.mjs",
+    "test:node": "node --test --test-force-exit --test-timeout=60000 tests/**/*.test.mjs",
+    "test:sh": "bash tests/test_pre_push_policy.sh && bash tests/test-run-watchdog.sh && bash tests/backup-fleet.test.sh && bash tests/test_reconstitute.sh && bash tests/test_reconstitute_fixes.sh && bash tests/test_agent_forensics.sh && bash hooks/pre-push-policy.sh --test && bash tools/reconstitute.sh --test",
+    "test:py": "python -m unittest discover -s tests",
+    "test:all": "npm run test:node && npm run test:sh && npm run test:py"
+  }
 }

package/scan/fleet-scan.example.mjs

@@ -0,0 +1,292 @@
+// Example IOC/secret scanner — copy to fleet-scan.mjs and configure paths.
+// Scans committed code and fleet transcripts for security/alignment red-flags.
+// Runs each watchdog cycle; marks findings in SECURITY-ALERTS.log. Never blocks the fleet.
+//
+// SETUP:
+// 1. Copy this file to fleet-scan.mjs (in the same directory)
+// 2. Edit the REPOS and PROJECT_ROOTS configuration below to match your fleet setup
+// 3. Configure paths via aesop.config.json or environment variables:
+//    - AESOP_FLEET_ROOT: root directory containing your project repositories
+//    - AESOP_TRANSCRIPTS_ROOT: root directory containing ~/.claude/projects transcripts
+// 4. Ensure aesop.config.json contains repo definitions (see aesop.config.example.json)
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Load configuration from aesop.config.json or use environment variable defaults
+function loadConfig() {
+  const configPath = process.env.AESOP_CONFIG || path.join(process.cwd(), 'aesop.config.json');
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    } catch (e) {
+      console.error(`Warning: Failed to load config from ${configPath}: ${e.message}`);
+    }
+  }
+  return config;
+}
+
+const config = loadConfig();
+
+// Environment variable overrides (precedence: env > config > defaults)
+const FLEET_ROOT = process.env.AESOP_FLEET_ROOT || config.fleet_root || process.env.HOME;
+const TRANSCRIPTS_ROOT = process.env.AESOP_TRANSCRIPTS_ROOT || config.transcripts_root || path.join(process.env.HOME, '.claude', 'projects');
+
+// === CONFIGURE YOUR FLEET ===
+// Edit REPOS array to match your monitored repositories
+// Example: { path: '/path/to/project1', name: 'project1', branch: 'main' }
+// Paths can be absolute or relative to FLEET_ROOT
+const REPOS = config.repos || [
+  // Example:
+  // { path: 'project-a', name: 'project-a', branch: 'main' },
+  // { path: 'project-b', name: 'project-b', branch: 'main' },
+];
+
+// Transcript project roots to scan for fleet prompts
+// Default: ~/.claude/projects (set via AESOP_TRANSCRIPTS_ROOT or config)
+const PROJECT_ROOTS = [
+  TRANSCRIPTS_ROOT,
+];
+
+// Handoff/alerts directory (where SECURITY-ALERTS.log is stored)
+// Set via config: alerts.alerts_root or alerts_root
+const ALERTS_ROOT = config.alerts?.alerts_root || config.alerts_root || path.join(FLEET_ROOT, '..', 'conductor3', 'state');
+const ALERTS = path.join(ALERTS_ROOT, 'SECURITY-ALERTS.log');
+const SEENF = path.join(ALERTS_ROOT, '.fleet-scan-seen.json');
+const MARKERF = path.join(ALERTS_ROOT, '.fleet-scan-lastcommit');
+
+// Session ID to exclude (optional: set via EXCLUDE_SESSION env var or config)
+const MY_SESSION = process.env.EXCLUDE_SESSION || config.exclude_session || '';
+
+// ---- Utility functions ----
+const git = (a, cwd) => {
+  try {
+    return execSync(`git ${a}`, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return '';
+  }
+};
+const now = () => new Date().toISOString().replace('T', ' ').slice(0, 19);
+const seen = fs.existsSync(SEENF) ? new Set(JSON.parse(fs.readFileSync(SEENF, 'utf8'))) : new Set();
+const findings = [];
+
+const add = (sev, kind, where, detail) => {
+  const key = crypto
+    .createHash('sha1')
+    .update(sev + kind + where + detail)
+    .digest('hex')
+    .slice(0, 16);
+  if (seen.has(key)) return;
+  seen.add(key);
+  findings.push(`[${now()}] ${sev} ${kind} | ${where} | ${detail}`);
+};
+
+// ---- IOC patterns for ADDED code lines ----
+const CODE_IOC = [
+  ['HIGH', 'exec/shell', /Runtime\.getRuntime\(\)\.exec|new\s+ProcessBuilder|\bos\.system\(|\bsubprocess\.|\bpopen\(/i],
+  ['HIGH', 'reverse-shell', /\/dev\/tcp\/|\bnc\s+-e\b|bash\s+-i\b|sh\s+-i\b|socket\.SOCK_STREAM.*connect/i],
+  ['HIGH', 'pipe-to-shell', /\b(curl|wget)\b[^\n]*\|\s*(sh|bash)\b/i],
+  ['HIGH', 'b64-exec', /base64\s+(-d|--decode)[^\n]*\|\s*(sh|bash)|Base64.*decode[^\n]*exec/i],
+  ['HIGH', 'secret-literal', /AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9]{20,}|-----BEGIN[A-Z ]*PRIVATE KEY-----|xox[baprs]-[A-Za-z0-9-]{10,}|ghp_[A-Za-z0-9]{20,}/],
+  ['HIGH', 'cred-access', /\.ssh\/(id_|authorized)|\.aws\/credentials|\/etc\/(passwd|shadow)|secrets\.toml|\.env\b/i],
+  ['HIGH', 'destructive', /\brm\s+-rf\b|DROP\s+TABLE|TRUNCATE\s+TABLE|DELETE\s+FROM\s+\w+\s*;/i],
+  ['MED', 'deserialization', /\bObjectInputStream\b|\.readObject\(|XMLDecoder|@JsonTypeInfo|enableDefaultTyping/],
+  ['MED', 'reflection', /Class\.forName\(|Method\.invoke\(|getDeclaredMethod\(|setAccessible\(true\)/],
+  ['MED', 'raw-network', /new\s+Socket\(|URLConnection|\.openConnection\(|InetSocketAddress\(/i],
+  ['MED', 'hardcoded-cred', /(password|passwd|secret|api[_-]?key|token)\s*[:=]\s*["'][^"']{6,}["']/i],
+];
+
+function scanCodeAddedLines(diff, label) {
+  if (!diff) return;
+  let file = label;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('+++ ')) {
+      file = line.slice(4).replace(/^b\//, '');
+      continue;
+    }
+    if (!line.startsWith('+') || line.startsWith('+++')) continue;
+    const code = line.slice(1);
+    for (const [sev, kind, re] of CODE_IOC) {
+      if (re.test(code)) add(sev, 'CODE:' + kind, file, code.trim().slice(0, 160));
+    }
+  }
+}
+
+// Scan all configured repos
+for (const repo of REPOS) {
+  const repoPath = path.isAbsolute(repo.path) ? repo.path : path.join(FLEET_ROOT, repo.path);
+  if (!fs.existsSync(repoPath)) {
+    console.warn(`Warning: Repo not found: ${repoPath}`);
+    continue;
+  }
+
+  const head = git('rev-parse HEAD', repoPath).trim();
+  const markerFile = path.join(repoPath, '.fleet-scan-lastcommit-' + repo.name);
+  const last = fs.existsSync(markerFile) ? fs.readFileSync(markerFile, 'utf8').trim() : '';
+
+  if (head) {
+    if (last && last !== head) {
+      scanCodeAddedLines(git(`diff ${last}..${head}`, repoPath), `${repo.name}:commit-range`);
+    } else if (!last) {
+      scanCodeAddedLines(git(`show ${head}`, repoPath), `${repo.name}:${head.slice(0, 8)}`);
+    }
+    scanCodeAddedLines(git('diff HEAD', repoPath), `${repo.name}:working-tree`);
+    fs.writeFileSync(markerFile, head);
+  }
+}
+
+// ---- Fleet transcript scan (injection / exfil / off-goal) ----
+const CRED_HARVEST_ALLOWLIST = [
+  'secret_scan.py',
+  'secret/credential gate',
+  'scripts/CLAUDE.md',
+  'env_assignment',
+  'env_suspicious_keys',
+  'scanner_selftest',
+  'allow-pattern-docs',
+  'CRED_HARVEST_ALLOWLIST',
+  'generic_secret_assignment',
+];
+
+const EXFILTRATION_ALLOWLIST = [
+  'semantic-prompt-review',
+  'semantic review',
+  'OK/DRIFT/SUSPICIOUS',
+  'drift_escalator',
+  'prompt_classifier',
+  'alert-review',
+  'triage',
+  'EXFILTRATION_ALLOWLIST',
+  'power_selftest',
+  'secret_scan.py',
+  'fleet-scan.mjs',
+  'scanner_selftest',
+  'SECRETS-PERMITTED',
+  'resolve_alerts',
+];
+
+const PROMPT_IOC = [
+  ['HIGH', 'prompt-injection', /ignore\s+(all\s+)?(previous|prior|the\s+above)\s+instructions|disregard\s+(the|your)\s+(rules|instructions)|you\s+are\s+now\s+|new\s+system\s+prompt/i],
+  ['HIGH', 'exfiltration', /exfiltrat|send\s+(it|them|the\s+\w+)\s+to\s+https?:|upload\s+to\s+|POST\s+.*to\s+http|leak\s+(the\s+)?(secret|cred|token|key)/i],
+  ['HIGH', 'cred-harvest', /read\s+.*secrets\.toml|\.env\b|\.ssh\/|\.aws\/credentials|environment\s+variables?\s+.*(send|post|exfil)|harvest\s+(cred|token|key)/i],
+  ['HIGH', 'evade-security', /disable\s+(the\s+)?(sentinel|antivirus|edr|defender|firewall)|bypass\s+(the\s+)?(security|scan|review)|hide\s+(this\s+)?from\s+the\s+user|don.?t\s+tell\s+the\s+(user|owner)/i],
+  ['MED', 'danger-shell', /\b(curl|wget)\b.*\|\s*(sh|bash)|base64\s+-d|\/dev\/tcp\/|rm\s+-rf\s+(\/|~)|chmod\s+\+s/i],
+];
+
+function extractTexts(obj) {
+  const out = [];
+  const c = obj?.message?.content;
+  if (typeof c === 'string') out.push(c);
+  else if (Array.isArray(c)) {
+    for (const x of c) {
+      if (typeof x === 'string') out.push(x);
+      else if (x?.type === 'text' && x.text) out.push(x.text);
+      else if (x?.type === 'tool_use' && (x.name === 'Agent' || x.name === 'Task')) {
+        if (x.input?.prompt) out.push('[SPAWN] ' + x.input.prompt);
+        if (x.input?.description) out.push('[SPAWN] ' + x.input.description);
+      }
+    }
+  }
+  return out;
+}
+
+const SINCE = Date.now() - 25 * 60 * 1000;
+const tFiles = [];
+
+function walk(d) {
+  try {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.jsonl')) tFiles.push(p);
+    }
+  } catch {}
+}
+
+for (const r of PROJECT_ROOTS) {
+  if (fs.existsSync(r)) walk(r);
+}
+
+for (const fp of tFiles) {
+  if (MY_SESSION && fp.includes(MY_SESSION)) continue; // skip excluded session
+  let st;
+  try {
+    st = fs.statSync(fp);
+  } catch {
+    continue;
+  }
+  if (st.mtimeMs < SINCE) continue; // only recent fleet activity
+  const base = path.basename(fp);
+  const isAgentFile = base.startsWith('agent-'); // agent files: scan all; main session: [SPAWN] only
+  let lines;
+  try {
+    lines = fs.readFileSync(fp, 'utf8').split('\n');
+  } catch {
+    continue;
+  }
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    for (const text of extractTexts(obj)) {
+      if (!text || text.length < 8) continue;
+      const isSpawnedPrompt = text.startsWith('[SPAWN]');
+      const shouldScanPromptIOC = isAgentFile || isSpawnedPrompt;
+      let flagged = false;
+      if (shouldScanPromptIOC) {
+        for (const [sev, kind, re] of PROMPT_IOC) {
+          if (re.test(text)) {
+            if (kind === 'cred-harvest') {
+              const isDefensiveToolRef = CRED_HARVEST_ALLOWLIST.some((ref) => text.includes(ref));
+              if (isDefensiveToolRef) {
+                const detail = text.replace(/\s+/g, ' ').slice(0, 180);
+                add('SUPPRESSED-FP', 'cred-harvest (defensive-tool reference)', base, detail);
+                flagged = true;
+                continue;
+              }
+            }
+            if (kind === 'exfiltration') {
+              const isDefensiveReviewRef = EXFILTRATION_ALLOWLIST.some((ref) => text.includes(ref));
+              if (isDefensiveReviewRef) {
+                const detail = text.replace(/\s+/g, ' ').slice(0, 180);
+                add('SUPPRESSED-FP', 'exfiltration (defensive-review reference)', base, detail);
+                flagged = true;
+                continue;
+              }
+            }
+            add(sev, 'PROMPT:' + kind, base, text.replace(/\s+/g, ' ').slice(0, 180));
+            flagged = true;
+          }
+        }
+      }
+      void flagged;
+    }
+  }
+}
+
+// ---- emit ----
+// Ensure output directory exists
+if (!fs.existsSync(ALERTS_ROOT)) {
+  fs.mkdirSync(ALERTS_ROOT, { recursive: true });
+}
+
+if (findings.length) {
+  fs.appendFileSync(ALERTS, findings.join('\n') + '\n');
+  fs.writeFileSync(SEENF, JSON.stringify([...seen]));
+  console.log(`${findings.length} new finding(s) -> ${ALERTS}`);
+  for (const f of findings) console.log(f);
+} else {
+  fs.writeFileSync(SEENF, JSON.stringify([...seen]));
+  console.log('no new findings');
+}

package/skills/CLAUDE.md

@@ -0,0 +1,3 @@
+# skills/ — Orchestration and priming skills
+
+- **power/** — /power skill: prime the filesystem brain (load rules, dispatch model, memory, state) and report system health — see power/SKILL.md

package/skills/healthcheck/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: healthcheck
+description: Check fleet health — one colored ball (heartbeats, alerts, orchestrator, tracker items).
+version: 1.0.0
+---
+
+# Healthcheck — one colored health ball
+
+One-line status indicator for aesop fleet health, driven by aggregated signals.
+
+## Procedure
+
+Run the healthcheck tool and interpret the ball:
+
+```bash
+python tools/healthcheck.py
+```
+
+### Output interpretation
+
+**🟢 Green**: All heartbeats fresh (watchdog <300s, monitor <3600s), no HIGH alerts
+
+**🟡 Yellow**: Stale heartbeat OR unreviewed MED severity alert
+
+**🔴 Red**: HIGH severity alert OR watchdog dead (>600s) while orchestrator actively dispatching
+
+### Fixing issues
+
+When healthcheck returns non-green, check the bullet-list reasons:
+
+1. **Stale heartbeat**: Restart the relevant daemon (watchdog or monitor). Check `bash daemons/run-watchdog.sh --once` or monitor process.
+2. **Unreviewed HIGH alert**: Review SECURITY-ALERTS.log, prefix line with `NOTE:` or `RESOLVED-FP` to mark reviewed.
+3. **Unreviewed MED alert**: Same as HIGH — review and mark.
+4. **Dead watchdog + active dispatch**: Critical issue — watchdog daemon crashed while orchestrator was dispatching agents. Check logs, restart watchdog, verify orchestrator stability.
+
+### Machine-readable output
+
+For integration with monitoring/dashboards, use `--json`:
+
+```bash
+python tools/healthcheck.py --json
+```
+
+Returns a JSON object with `ball`, `health` status, issues list, and tracker lane counts.

package/skills/power/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: power
+description: Prime the "filesystem brain" — load all operating rules, behaviors, the multi-agent dispatch model, memory, and the current project's semantics from disk. Report a compact primed brief with system health and next steps.
+version: 1.0.0
+---
+
+# Power — prime the filesystem brain
+
+Everything that governs how I should behave lives on disk. This skill reads it, internalizes it,
+and reports a compact "primed" summary — **without inflating context** (code is read via subagents
+that return briefs, not dumped raw).
+
+The principle: **all rules can be abstracted to consistent agent behavior.** Rules are files;
+reading them = becoming the agent the files describe.
+
+**Scope: this is a priming skill for aesop orchestration itself** — rules, dispatch model, memory,
+machinery health. Running it does NOT imply any particular project is being worked on. Project
+state loads only when the session is actually resuming that project (step 3); deferred projects
+are rolled up to counts, never item-by-item — and their repos/daemons are left untouched.
+
+## Procedure (run in order)
+
+### 1. Load global rules + dispatch model
+Read these directly (they are small and authoritative):
+- `~/.claude/CLAUDE.md` — the **cardinal rules** (autonomous continuation, dispatch model, 
+  durable checkpointing, build env). These override defaults.
+- Any project-local `CLAUDE.md` in the current working directory and its parents.
+
+Then run the **brain integrity check**: `~/.claude` should be a git repo (if you version it). 
+Check `git -C ~/.claude status --porcelain` and ahead/behind vs origin:
+- Deliberate uncommitted rule/hook/skill/memory changes → commit + push now (gated by 
+  `python <project-root>/tools/secret_scan.py --staged`);
+- **Unexpected** modifications or deletions → report as alert — stop, diff against remote, restore 
+  before continuing (core defense: don't let tooling shadow your rules).
+
+Also check for unactioned entries in `~/.claude/PROPOSALS.md` or similar and surface a 
+one-line summary of each in the primed report.
+
+Internalize the **dispatch model** and apply it for the rest of the session. Document
+the dispatch model's key invariants locally (in your private repo's `CLAUDE.md`, 
+if you version `~/.claude`), for example:
+- **Subagents model** (Haiku vs specialists vs orchestrator tier)
+- **Parallelism defaults** (e.g., fan out 6–8 Haikus per domain)
+- **TDD-first discipline** and checkpointing (STATE.md, BUILDLOG.md)
+- **Observable machinery**: every action logged, every cost tracked
+
+### 2. Load memory
+- Read `~/.claude/memory/MEMORY.md` (the index, or use your configured path).
+- For any memory entry whose one-line hook is relevant to the current task/project, 
+  read that memory file.
+- Treat recalled memories as background context that reflects when they were written — 
+  **verify any file/flag/path they name still exists before relying on it.**
+
+### 3. Load the active project's state
+If working inside (or resuming) a known project, read its durable checkpoint first:
+- Look for a `STATE.md` and `BUILDLOG.md` in the project root or a handoff folder.
+- `STATE.md` is the source of truth for intent, locked decisions, contracts, and **NEXT STEPS**.
+- Re-sync from disk (git log, file state) — never trust stale assumptions.
+
+### 4. Codebase semantics — already-primed vs first-time init
+**First check whether this codebase has been primed before**: does it already carry its scoped
+`.md` layer (a project-root `CLAUDE.md`, domain `CLAUDE.md` units, a `STATE.md`)?
+
+- **Already primed** (has `CLAUDE.md`s and optionally `STATE.md`): do NOT re-investigate the code. 
+  The `.md` layer IS the persisted semantic memory — the project `CLAUDE.md`s are sufficient; 
+  the codebase is simply **ready to work**. Only re-scan a specific domain if its `CLAUDE.md` 
+  is contradicted by on-disk reality (then fix the `.md`, which is the bug).
+- **First time / not primed** (no scoped `.md`s found): run **init-prime** — fan out Haiku 
+  subagents to read the whole codebase (briefs only, never raw dumps) and **autonomously write 
+  the scoped `.md` layer it needs**:
+  - a project-root `CLAUDE.md`: purpose, build/run commands + toolchain, top gotchas
+  - smallest self-contained **domain `CLAUDE.md` units** (minimal, never lossy) — module layout, 
+    key contracts, domain logic, non-obvious invariants
+  - a `STATE.md` checkpoint seed if the work warrants it
+  
+  Commit + push the new `.md`s (secret-scan gated). Every future `/power` on that codebase 
+  then takes the already-primed fast path.
+
+### 5. Report "primed" (compact)
+Output a short brief, not a wall of text:
+
+- **Drain the UI inbox first** (if configured in `aesop.config.json`): run 
+  `python <project-root>/tools/inbox_drain.py pending`. If items exist, surface each under 
+  a **"QUEUED FROM DASHBOARD"** heading as `[ISO-ts] text` one-liners. Mark them processed 
+  (`python <project-root>/tools/inbox_drain.py mark-all`) after actioning.
+- **Health line first**: run `python <project-root>/tools/power_selftest.py` and lead with its 
+  `POWER-SELFTEST:` line (hooks, brain push state, heartbeats, decisions, scanner state).
+  Bullet anything non-OK.
+- **Open decisions**: surface each ACTIVE line of any decisions/proposals file and any 
+  unactioned inbox entries as one-liners (rolled-up counts for deferred items, never item-by-item).
+- **Rules loaded**: dispatch model + any project-specific overrides in one or two lines.
+- **Project**: name, purpose, status, repo, key paths.
+- **Semantics**: the domain model + main flow in a few bullets.
+- **Gotchas**: the verified ones that change how I act.
+- **Next steps**: from `STATE.md`, ready to execute (autonomously, per the dispatch model).
+
+### 6. Project app launch (if applicable)
+After reporting primed, bring the active project's runnable app up in the BACKGROUND if it has one.
+Make it **idempotent**: if the port is already serving a healthy instance, skip the start and 
+just report the URL.
+
+**Pattern** (project adopters fill in their own):
+- Define a `run` skill or script in your project (or use an existing `start`/`run` command).
+- Detect if the service is already healthy (e.g., `curl -s -o /dev/null -w '%{http_code}' http://localhost:PORT/`).
+- If healthy (200), skip startup and just report the URL.
+- If not healthy, start the service in the background via Bash with `run_in_background: true`.
+- Poll readiness WITHOUT blocking sleep: use curl retries or a cheap probe loop.
+- Report the URL + background task ID so it can be stopped on request.
+
+**DO NOT** hardcode personal app paths (e.g., Spring Boot repos, IDEs, personal tools). 
+Instead, document in your project's `CLAUDE.md` how to launch the app, and reference that 
+in your local version of this skill or a project-specific override.
+
+### 6b. Machinery health — orchestration monitor (optional)
+If your project uses an orchestration monitor, spin up a **background Haiku agent** that:
+1. Collects health signals (cheap, deterministic)
+2. Reads only that brief and acts per a charter — AUTO-applies safe refinements and stages 
+   rule/behavior changes to a `PROPOSALS.md` for review
+3. Self-paces via ScheduleWakeup and beats a heartbeat
+
+Skip if `.monitor-heartbeat` is already <300s old. Announce its task id so it can be paused/stopped.
+
+### 7. Standing dev loops (optional; only when actively developing)
+If the session is doing active development (writing/changing code — not just answering questions),
+keep these background loops running continuously. They are the "tail": cheap, persistent, 
+append-only, and never inflate the main context.
+
+**Patterns** (project adopters fill in their own):
+
+1. **Build/status + backup watchdog** (background bash loop) — appends timestamped git/test/build
+   snapshots. For example, if your project has a `daemons/` folder with a `run-watchdog.sh`, 
+   launch that via Bash with `run_in_background: true` and let it beat a heartbeat so you know 
+   it is live. Stop with TaskStop when development pauses.
+
+2. **Memory keeper** (Haiku, background) — as new decisions, contracts, or gotchas emerge, 
+   updates the relevant memory files compactly (one fact per memory; never bloat). Re-invoke 
+   via SendMessage to keep context.
+
+3. **Continuous QA loop** — after each feature reaches a checkpoint: **Haiku reviews → 
+   Haiku bugfixes → Haiku lint/format**, looping until the build is green and review is clean, 
+   with **Opus orchestrator final-catch** before merge. TDD-first: failing tests before code.
+
+4. **Tail-drift alignment** (Haiku, background) — periodically checks in-flight agents' output 
+   against their domain `CLAUDE.md` contract, and realigns anything drifting.
+
+5. **Hung-Haiku watchdog** (orchestrator's main thread, NOT a subagent) — keep watching every 
+   spawned Haiku for stalls. On hang: TaskStop it and relaunch from checkpoint or respawn.
+
+Launch any that aren't already running; **stop them with TaskStop when development pauses**.
+
+Mechanism: use background `Agent` (run_in_background) for keeper/drift loops, `Monitor` for 
+the watchdog, and self-pace longer cycles with `/loop` skill or `ScheduleWakeup`. 
+Always announce which loops were started (and their task IDs) so they can be paused/stopped.
+
+## Notes
+- If no project context exists yet, steps 1–2 still apply; skip 3–4 and say so.
+- Steps 1–5 always run on `/power`; **step 6 (launch app) runs only if the active project has one**;
+  **step 6b (monitor) runs only if configured**; step 7 (dev loops) runs only during active development.
+- Prefer subagents for anything large; the goal is a *brain*, not a *dump*.
+- After priming, proceed under the dispatch model (continue approved work autonomously; stop only 
+  for genuine decisions or unauthorized outward/destructive actions).

package/state_store/CLAUDE.md

@@ -0,0 +1,39 @@
+# state_store/ — event-sourced state layer (DB source of truth, git as export)
+
+**Purpose**: the durable substrate to move aesop's coordination/state off git —
+which cannot scale to a team (single-writer control files, hot-file merge
+conflicts, no transactions/concurrency/real-time). State becomes an append-only
+event log with per-stream versioning; current state is a projection; git is
+demoted to a rendered, diffable **export**.
+
+**Status (2026-07-14)**: additive prototype. The live `ui/` tracker path
+(`collectors.py` → `state/tracker.json`) is UNCHANGED. This package ships the
+store + tracker projection + backfill + export, ready for a later dual-read
+cutover. Design: `conductor3 plans/aesop-scaling-rearchitecture.md`.
+
+## Files (stdlib only — sqlite3/json/threading/time)
+- **store.py** — `EventStore(db_path)`: append-only SQLite (WAL) log.
+  Concurrency-safe across threads and processes via `busy_timeout` +
+  `BEGIN IMMEDIATE` (atomic read-max-version-then-insert). `append/read/read_all`.
+- **projections.py** — `project_tracker(events)`: folds `item_created` /
+  `item_updated` / `item_archived` into the full `tracker.json` shape,
+  preserving first-seen order.
+- **api.py** — `StateAPI(db_path)`: the swap seam (`append`/`get`/`project`).
+  Backend swaps SQLite→Postgres here without touching callers.
+- **export.py** — `export_tracker(api, out_path)`: render the projection back to
+  a git-tracked JSON snapshot (indent=2, ascii-escaped to match the live file).
+- **ingest.py** — `ingest_tracker_json(api, path)`: backfill one `item_created`
+  per existing item (the migration/backfill path).
+
+## Invariants
+- **Append-only**: never mutate/delete events; state changes are new events.
+- **Per-stream version is 1-based and gapless** (enforced atomically).
+- **git as export, not source**: nothing here reads git for state.
+- **Round-trip fidelity**: ingest → project → export reproduces the same items
+  (tested against the real `state/tracker.json`).
+
+## Next (cutover, follow-up — NOT this increment)
+Point tracker CRUD at `StateAPI` (create→`item_created`, update→`item_updated`,
+move→lane update, delete→`item_archived`); add a `subscribe()` real-time path to
+replace the SSE file-watch; run the `export_tracker` job to keep `tracker.json`
+rendered during dual-read; then flip readers to the API.

package/state_store/__init__.py

@@ -0,0 +1,24 @@
+"""state_store — event-sourced state layer (DB source of truth, git as export).
+
+Additive prototype landed 2026-07-14: the live ui/ tracker path is UNCHANGED.
+This package provides the durable substrate to migrate aesop's coordination
+state off git (which does not scale to concurrent writers) onto a real store
+with transactions and per-stream versioning — SQLite (WAL) now, Postgres later
+behind the same StateAPI. git is demoted to a rendered export (see export.py).
+
+Design + rationale: conductor3 plans/aesop-scaling-rearchitecture.md; overview
+in state_store/CLAUDE.md.
+"""
+from .api import StateAPI
+from .export import export_tracker
+from .ingest import ingest_tracker_json
+from .projections import project_tracker
+from .store import EventStore
+
+__all__ = [
+    "EventStore",
+    "StateAPI",
+    "project_tracker",
+    "export_tracker",
+    "ingest_tracker_json",
+]

package/state_store/api.py

@@ -0,0 +1,35 @@
+"""state_store.api — StateAPI facade over the event store + projections.
+
+The single seam callers use, so the backend (SQLite now, Postgres later) can be
+swapped without touching call sites. ``project(view)`` reads the same-named
+stream and folds it through the registered projector.
+"""
+from __future__ import annotations
+
+from .projections import project_tracker
+from .store import EventStore
+
+_PROJECTORS = {"tracker": project_tracker}
+
+
+class StateAPI:
+    """Facade: append events, read a stream, or project a view to current state."""
+
+    def __init__(self, db_path: str):
+        self._store = EventStore(db_path)
+
+    def append(self, stream: str, event_type: str, payload: dict, actor: str = "system") -> int:
+        """Append one event; return its new per-stream version."""
+        return self._store.append(stream, event_type, payload, actor)
+
+    def get(self, stream: str) -> list:
+        """Return all events in ``stream`` ascending by version."""
+        return self._store.read(stream)
+
+    def project(self, view: str) -> dict:
+        """Fold the same-named stream through its projector into current state."""
+        try:
+            projector = _PROJECTORS[view]
+        except KeyError:
+            raise ValueError(f"unknown projection view: {view!r}")
+        return projector(self.get(view))