@matt82198/aesop 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **Version scheme**: Stable releases are `0.x.y`; `0.x.0-beta.N` / `-rc.N` are pre-releases; `0.1.0-wave.N` were internal wave-milestone previews.
 
+## [0.4.0] - 2026-07-25
+
+### Added
+- **Two-seat unified config** (HS-1): New `seats` configuration block allows swapping both worker AND orchestrator models from a single config block — eliminates split configuration and enables model experimentation without code changes. No-op default: existing installations remain unchanged (install-time safety).
+- **Live orchestrator-seat swap** (HS-2): Added `final_catch` gate in the wave loop with block/quarantine + crash-only degradation — orchestrator model can be swapped mid-flight without restarting the entire fleet. Failure path quarantines the wave and logs the incident.
+- **Microkernel architecture guide** (HS-3): New `docs/MICROKERNEL.md` explains the proof-of-concept model-swap seam, multi-model verification bounds, and a 60-second "swap a seat's model" quickstart for adopters.
+- **Scaffold completeness** (`npx aesop init`): driver/ directory now scaffolds on first run (was omitted, breaking adopter first-run experience). Added --force idempotent re-scaffold and child process timeout protection.
+
+### Security / Hardening
+- **IPv6 SSRF + DNS-resolution validation**: Requests to orchestrator's `base_url` now validate against IPv6 loopback and route-local semantics; DNS resolution blocked for external hostnames; `is_local` pinned to loopback only.
+- **API key environment variable allowlist** (primary enforcement): `api_key_env` rejects obvious secret patterns (AWS_SECRET, AZURE_KEY, etc.) and logs a loud NOTICE for non-standard names; fail-closed on read errors.
+- **Worker model field validation**: `worker.model` config field no longer silently ignored if orchestrator uses a non-Claude driver; now validated at load time.
+- **Wave execution timeouts**: Added `run_command` timeouts to prevent indefinite wave hangs on subprocess failures; child processes now respect explicit timeout boundaries (no more wave-level hard stops).
+- **CI merge-wait fail-closed**: `ci_merge_wait` gate now exits with explicit failure codes (not silent pass) on timeout or missing CI status, preventing accidental merges of untested code.
+- **Windows CI shard concurrency cap**: Reduced `max-parallel` for Windows runner to cut container contention flakes; Windows shard now stable on standard GitHub Actions.
+- **Path redaction completeness** (bench tooling): Bench results and logs redact full paths before reporting; `is_local` validation prevents accidental leakage of internal network topology.
+- **JSON-boundary fail-open holes patched**: Orchestrator/driver seam now validates JSON boundaries at worker<->orchestrator message crossings; malformed messages fail-closed (not skipped).
+
+### Fixed
+- **`npx aesop init` driver scaffolding**: Adopters running init on a fresh repo now get a complete driver/ directory tree; was silently omitting driver/, causing "module not found" on first wave.
+- **Scaffold idempotency + child timeouts**: Re-running init --force no longer corrupts existing templates; child scaffold processes timeout cleanly instead of hanging.
+- **Gate incumbent-validation**: Pre-gate validation of model incumbent (before swap attempt) catches incompatibilities early and logs them for forensics.
+
 ## [0.3.2] - 2026-07-23
 
 ### Fixed

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <em>Autonomous Developer for Any Repository</em>
+  <em>Crash-only multi-agent orchestration for any repository</em>
 </p>
 
 <p align="center">
@@ -14,7 +14,13 @@
 
 ## What It Does
 
-**Aesop** is a source-available orchestration harness that runs multi-agent workflows on any repository. It ranks backlog, dispatches parallel Haiku workers (scoped to disjoint file ownership), verifies merges with adversarial safety, and feeds learnings into the next wave. Durable state (SQLite + git-rendered checkpoints) survives machine wipes and enables team coordination. This repo's own 223 PRs across 880 commits were delivered by Aesop's own `/buildsystem` wave loop—a supervised loop under a human operator who sets goals and owns outward gates (npm publish, releases, history rewrites). The stack is portable: swappable backends (Claude Code reference, OpenAI-compatible Ollama/OpenRouter, Codex bridge), with auto-tuned verification safety calibrated per backend.
+**Aesop** is a **crash-recoverable orchestration harness** for multi-agent workflows on any repository. One-line theme: *stateless agent execution over git-backed durable memory*.
+
+Core idea: **agent behavior is source code.** Every decision lives in durable, human-diffable files—git history, plain-text STATE.md, append-only BUILDLOG.md, Python guardrails. When a machine fails, you re-read from disk. No vector DBs, no distributed consensus, no magic. This repo's own 251 merged PRs across 1088 commits were delivered by Aesop's own `/buildsystem` wave loop—a supervised loop under a human operator who sets goals and owns outward gates (npm publish, releases, history rewrites).
+
+**Why it matters:** crash recovery is not a special path; it is how the system *always* starts. Stateless workers, persistent filesystem brain, Haiku-first dispatch (4.3× cheaper than hierarchical design, proven by real A/B), fail-closed guardrails (pre-push secret gate, kill-switch, cost ceiling), and observable heartbeats. The result: 251 PRs in 11 days; Haiku at 39/39 on a 39-task benchmark vs Opus 38/39, at ~1/3 the cost.
+
+**Why it's built this way:** [The Aesop Hypothesis](./docs/THE-AESOP-HYPOTHESIS.md) — the design philosophy, the trade-offs, the cancelled architectures with published data.
 
 ## Feature Demo
 
@@ -86,16 +92,17 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 244 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 1065 <!-- metrics-verified: self_stats.py (git log) --> |
+| Merged PRs | 251 <!-- metrics-verified: self_stats.py (git log) --> |
+| Total Commits | 1088 <!-- metrics-verified: self_stats.py (git log) --> |
 | Project Age | 11 days <!-- metrics-verified: self_stats.py (git log) --> |
 | Waves | 30 <!-- metrics-verified: self_stats.py (git log) --> |
-| Insertions + Deletions | 185,174 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 541 <!-- metrics-verified: self_stats.py (git log) --> |
+| Insertions + Deletions | 186,587 <!-- metrics-verified: self_stats.py (git log) --> |
+| Files Tracked | 546 <!-- metrics-verified: self_stats.py (git log) --> |
 | Distinct Co-authors | 11 <!-- metrics-verified: self_stats.py (git log) --> |
 
 <!-- STATS:END -->
 
+
 *Wave: one complete build cycle (intake → dispatch → verify → ship) run by the orchestration engine.*
 
 
@@ -113,6 +120,7 @@ The benchmark proves it: across 39 judgment tasks (code review, severity calibra
 ## Learn More
 
 - **[docs/INSTALL.md](./docs/INSTALL.md)** — Setup and first wave  
+- **[docs/MICROKERNEL.md](./docs/MICROKERNEL.md)** — The two swappable seats (worker + orchestrator), the invariant Report/state boundary, and a 60-second quickstart for swapping either seat's model  
 - **[docs/PORTING.md](./docs/PORTING.md)** — Adopter's guide: port Aesop to your repo (prerequisites, scaffold, 10 failure modes)  
 - **[docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md)** — Concrete walkthrough of a wave cycle  
 - **[docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md)** — Cost analysis and scaling  

package/aesop.config.example.json

@@ -46,6 +46,22 @@
   "cardinal_rules": {
     "subagent_model": "haiku"
   },
+  "seats": {
+    "_comment": "Unified two-seat model selection (0.4.0). ONE block swaps BOTH seats: 'worker' = the coding agents (AgentDriver), 'orchestrator' = the decision seat (OrchestratorBackend). The values below ARE the defaults -- Claude Code worker + live-harness orchestrator -- so this block as shipped changes nothing; deleting it changes nothing either. To swap a seat, replace its block with one of the _worker_examples/_orchestrator_examples. Keys are read from env vars named by api_key_env at CALL time, never stored in this file. 'is_local': true = LOOPBACK endpoint only (localhost/127.0.0.1/::1 -- rejected otherwise): no API key needed, honest verification tier 3. Separate surface: cardinal_rules.subagent_model (above) pins the model for LIVE-HARNESS Claude Code subagents; seats.worker swaps the AgentDriver worker seam itself.",
+    "worker": { "backend": "claude" },
+    "orchestrator": { "backend": "harness" },
+    "_worker_examples": {
+      "_note": "Asymmetry: worker openai-compatible seats REQUIRE base_url; the orchestrator seat may omit base_url (defaults to the hosted OpenAI endpoint).",
+      "codex_hosted_openai": { "backend": "codex", "model": "gpt-4o-mini" },
+      "openai_compatible_openrouter": { "backend": "openai-compatible", "base_url": "https://openrouter.ai/api/v1", "model": "openai/gpt-4-turbo", "api_key_env": "OPENROUTER_API_KEY" },
+      "openai_compatible_local_ollama": { "backend": "openai-compatible", "base_url": "http://localhost:11434/v1", "model": "mistral", "is_local": true }
+    },
+    "_orchestrator_examples": {
+      "harness_default": { "backend": "harness" },
+      "openai_hosted": { "backend": "openai-compatible", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY" },
+      "local_ollama": { "backend": "openai-compatible", "base_url": "http://localhost:11434/v1", "model": "mistral", "is_local": true }
+    }
+  },
   "limits": {
     "_comment": "Cost ceiling / kill switch (tools/cost_ceiling.py, tools/halt.py). null disables a given ceiling (feature opt-in). When spend meets or exceeds a configured ceiling, cost_ceiling.py trips tools/halt.py's .HALT sentinel, which daemons/run-watchdog.sh checks at the top of every cycle and refuses to do work (no backup, no push, no scan) until cleared via 'python tools/halt.py --clear'.",
     "max_wave_tokens": null,

package/bin/cli.js

@@ -259,7 +259,7 @@ const repoUrlsStr = getFlag('--repo-urls');
 if (fs.existsSync(targetDir)) {
   const contents = fs.readdirSync(targetDir);
   // Allow .git and aesop scaffolded files to already exist (for idempotency)
-  const aesopDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui', 'docs', 'state_store', 'skills', 'mcp', 'scan', 'hooks', '.git', 'state'];
+  const aesopDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui', 'docs', 'state_store', 'skills', 'mcp', 'scan', 'hooks', 'driver', '.git', 'state'];
   const aesopFiles = [
     'aesop.config.example.json',
     'aesop.config.json',
@@ -317,6 +317,7 @@ const filesToCopy = [
   'mcp',
   'scan',
   'hooks',
+  'driver',
   'aesop.config.example.json',
   'README.md',
   'LICENSE',
@@ -421,8 +422,10 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
         port: 8770
       },
       cardinal_rules: {
+        // NOTE: orchestrator_model was RETIRED in 0.4.0 (HS-1): it was written
+        // here but read by nothing. The orchestrator seat's model now lives in
+        // seats.orchestrator.model (see aesop.config.example.json).
         subagent_model: 'haiku',
-        orchestrator_model: 'opus',
         tdd_first: true,
         never_push_main: true,
         secret_scan_gates_push: true

package/docs/INSTALL.md

@@ -200,19 +200,103 @@ export DEBUG=1
 
 By default, Aesop uses Claude Code (the orchestration harness) as its backend. You can configure it to use other models via the **AgentDriver abstraction**—enabling Ollama, OpenAI-compatible endpoints, OpenRouter, and more.
 
-### Configure a backend in aesop.config.json
+For the conceptual picture (the two swappable seats, what's proven vs. bounded about swapping them, and a 60-second copy-paste quickstart), see **[MICROKERNEL.md](MICROKERNEL.md)**. The rest of this section is the config-mechanics reference.
 
-Add or modify the `backend` section:
+### The unified two-seat config (0.4.0)
+
+One namespaced `seats` block in `aesop.config.json` selects BOTH seats:
+
+- **`seats.worker`** — the coding agents (AgentDriver). Same fields as the
+  legacy flat block below; takes precedence over it when both are present.
+- **`seats.orchestrator`** — the decision seat (`OrchestratorDriver.decide()`).
+  `"harness"` (default) means the live Claude Code session itself makes
+  decisions; `"openai-compatible"` routes decisions to an API model.
+
+**Swap a seat's model** — change just its block:
+
+```json
+{
+  "seats": {
+    "worker": {
+      "backend": "openai-compatible",
+      "base_url": "http://localhost:11434/v1",
+      "model": "mistral",
+      "is_local": true
+    },
+    "orchestrator": {
+      "backend": "openai-compatible",
+      "model": "gpt-4o-mini",
+      "api_key_env": "OPENAI_API_KEY"
+    }
+  }
+}
+```
+
+That is a local-Ollama worker fleet with a hosted `gpt-4o-mini` decision seat.
+To swap the worker to OpenRouter, replace `seats.worker` with
+`{"backend": "openai-compatible", "base_url": "https://openrouter.ai/api/v1",
+"model": "openai/gpt-4-turbo", "api_key_env": "OPENROUTER_API_KEY"}` — nothing
+else changes. API keys are read from the env var named by `api_key_env` at
+call time and are never stored in the config; `"is_local": true` endpoints
+need no key at all — and for exactly that reason `is_local` is only accepted
+with a loopback `base_url` (`localhost`, `127.0.0.1`, `::1`).
+
+`api_key_env` is checked with a **best-effort heuristic**, allowlist-primary:
+known LLM-provider key names (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`OPENROUTER_API_KEY`, `TOGETHER_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`,
+`DEEPSEEK_API_KEY`, `FIREWORKS_API_KEY`, `OLLAMA_API_KEY`,
+`AZURE_OPENAI_API_KEY`, `GOOGLE_API_KEY`) are accepted silently; names that
+don't look like key env vars or contain obvious non-LLM secret fragments
+(`SECRET`/`TOKEN`/`PASSWORD`/`ACCESS`/...) are rejected; any other
+key-shaped name (custom LLM gateways) is **allowed but prints a loud
+NOTICE** — the env var's value will be sent as a Bearer token to your
+`base_url`, so that NOTICE is the real signal: review it whenever a
+non-provider name shows up at load time.
+
+Asymmetry worth knowing: a **worker** `openai-compatible` seat REQUIRES
+`base_url`; the **orchestrator** seat may omit it (defaults to the hosted
+OpenAI endpoint).
+
+**No `seats` block? Nothing changes.** Existing installs keep today's exact
+behavior: Claude Code workers + harness orchestrator, no OpenAI backend
+constructed, no key required. A pre-0.4.0 **legacy flat** backend block
+(`{"backend": "codex", ...}` at the top level) also changes nothing by
+itself: it still parses and validates, but it stays **inert** in the wave
+scheduler's default path until you migrate it to `seats.worker` — on older
+installs that block was documented but consumed by nothing, so activating it
+silently would change behavior under you. (`cardinal_rules.orchestrator_model`
+from older scaffolds was write-only and is retired; the orchestrator seat's
+model now lives in `seats.orchestrator.model`.)
+
+Consumers: `driver/wave_scheduler.py` builds its worker driver from this
+config (CLI `--driver claude|codex` remains an override), and
+`tools/shadow_adjudication.py` / `tools/seated_shadow_adjudication.py` build
+their live orchestrator backend from `seats.orchestrator` (CLI `--model`
+remains an override).
+
+### The legacy flat block (parse-compatible, but migrate it)
+
+Pre-0.4.0 docs described a flat top-level block:
 
 ```json
 {
   "backend": "openai-compatible",
   "model": "ollama-mistral",
   "base_url": "http://localhost:11434/v1",
-  "api_key_env": "OLLAMA_API_KEY"
+  "api_key_env": "OLLAMA_API_KEY",
+  "is_local": true
 }
 ```
 
+It still parses and validates (and direct `build_driver()` callers honor
+it), but the wave scheduler's default path treats it as **inert** and keeps
+the Claude Code worker: to actually activate a configured worker there, put
+the same fields under `seats.worker` (`{"seats": {"worker": { ...this
+block... }}}`).
+
+Set `"is_local": true` for local/small models (Ollama etc.) — it raises the
+verification tier honestly (tier 3 instead of hosted tier 2).
+
 Supported backends:
 - `"claude"` (default) — Claude Code CLI harness
 - `"openai-compatible"` — OpenAI Chat Completions API (Ollama, OpenRouter, etc.)
@@ -229,17 +313,22 @@ ollama serve
 # 2. In another terminal, pull a model
 ollama pull mistral
 
-# 3. Configure Aesop to use it
+# 3. Configure Aesop to use it (seats.worker is the opt-in surface)
 cat > aesop.config.json <<EOF
 {
-  "backend": "openai-compatible",
-  "model": "mistral",
-  "base_url": "http://localhost:11434/v1",
-  "api_key_env": "OLLAMA_API_KEY"
+  "seats": {
+    "worker": {
+      "backend": "openai-compatible",
+      "model": "mistral",
+      "base_url": "http://localhost:11434/v1",
+      "api_key_env": "OLLAMA_API_KEY",
+      "is_local": true
+    }
+  }
 }
 EOF
 
-# 4. Start Aesop (it will use Mistral for subagent dispatch)
+# 4. Start Aesop (components that dispatch through the AgentDriver seam will use Mistral)
 npx @matt82198/aesop my-fleet --name "my-api"
 ```
 
@@ -250,16 +339,16 @@ The AgentDriver framework applies **honest verification tiers** — weaker backe
 | Backend | Accuracy | Verification Tier | What it means |
 |---------|----------|-------------------|---------------|
 | Claude Code | ~0.99 | 1 (minimal) | Orchestrator trusts output; spot-check tests |
-| OpenAI (GPT-4) | ~0.95 | 2 | Validate all JSON, run full test suite |
-| Ollama (Mistral) | ~0.70 | 4 (maximum) | Validate all JSON, adversarial review, expensive repair cap |
+| Hosted OpenAI-compatible (codex / OpenRouter) | ~0.92 | 2 | Validate all JSON, ~50% spot-check, adversarial review |
+| Local small model (`"is_local": true`, e.g. Ollama) | ~0.80 | 3 | Validate all JSON, heavy spot-check, adversarial review |
 
-Lower tiers cost less but require more orchestrator work. See [driver/README.md](../driver/README.md) for full verification-policy details.
+Higher tiers mean MORE orchestrator verification work: weaker backends raise, never lower, the orchestrator's burden. See [driver/README.md](../driver/README.md) for full verification-policy details.
 
 ### Troubleshooting
 
 **Backend won't connect**: Check `OLLAMA_API_KEY` (or your backend's API key env var) is set and the `base_url` is reachable.
 
-**Verification tier too strict**: If your backend is over-verified (tier 4 when it should be tier 2), update `probe_capabilities()` in the driver to report higher accuracy scores honestly.
+**Verification tier too strict**: The tier comes from the driver's `probe_capabilities()` honesty contract — never inflate accuracy to lower it. For hosted-quality models, leave `"is_local"` unset (tier 2); reserve `"is_local": true` (tier 3) for genuinely small local models.
 
 For more details, see [driver/README.md](../driver/README.md).
 
@@ -333,6 +422,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1 -D
 2. **Read [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
 3. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
 4. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
-4. **Explore the dashboard** — `python3 ui/serve.py` then open http://localhost:8770
+5. **Read [MICROKERNEL.md](MICROKERNEL.md)** — Swap the worker or orchestrator seat to a non-Claude model
+6. **Explore the dashboard** — `python3 ui/serve.py` then open http://localhost:8770
 
 For troubleshooting, see the [Aesop README](../README.md#troubleshooting) or [GOVERNANCE.md](GOVERNANCE.md) for operational policies.