@matt82198/aesop 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to Aesop are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+**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
+- **Windows daemons no longer flash a console window**: ad-hoc Scheduled Tasks launched `bash.exe` with Interactive logon, popping a visible console every watchdog interval (5 min). New `daemons/install-tasks.ps1` registers the watchdog/monitor tasks through a hidden `wscript` launcher (`daemons/run-hidden.vbs`) — same cadence, zero window flash.
+
+### Added
+- `daemons/install-tasks.ps1` — idempotent Windows task installer (install/uninstall/dry-run, configurable commands + intervals); shipped in the npm package.
+
 ## [0.3.1] - 2026-07-22 - Waves 28-31
 
 ### Added
@@ -373,6 +406,6 @@ This is the first public release of Aesop, a clean-room source-available impleme
 - Legacy TUI interface (bash + jq)
 - Configuration framework and examples
 - Comprehensive documentation and guides
-- MIT License (© 2026 Matt Culliton)
+- PolyForm Strict License 1.0.0 (source-available, © 2026 Matt Culliton)
 
 Aesop is production-ready and implements the complete cardinal rules for cost-optimized, durable multi-agent coordination.

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
 
@@ -48,7 +54,7 @@ python tools/health_score.py
 ```
 Outputs a scorecard of system readiness; --json for parsing.
 
-**Self-healing daemon** — Runs every 150s: backs up work, scans secrets, detects drift:
+**Self-monitoring daemon** — Runs every 150s: backs up work, scans secrets, detects drift:
 ```bash
 npx @matt82198/aesop watch
 ```
@@ -60,6 +66,10 @@ python tools/secret_scan.py --staged   # Blocks push if leak detected
 ```
 Exits with failure on file-read errors (not silently passing). CI validates every merge.
 
+**Parallel test battery** — Run all four test harnesses concurrently with isolated logs and enforced timeouts (`tools/test_battery.py` — ~5.4 min vs ~10 serial).
+
+**Windows CI green** — Full parity support on Windows-latest GitHub Actions: promoted to a required check after 6 consecutive green main runs.
+
 ## Proof Numbers
 
 Aesop builds itself. These numbers are live from git, verified by anyone who clones.
@@ -82,17 +92,21 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 223 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 880 <!-- metrics-verified: self_stats.py (git log) --> |
-| Project Age | 10 days <!-- 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 | 161,064 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 500 <!-- metrics-verified: self_stats.py (git log) --> |
-| Distinct Co-authors | 9 <!-- 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.*
+
+
+
 
 
 
@@ -101,17 +115,18 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 ## Why Haiku-First Works
 
-The benchmark proves it: across 39 judgment tasks (code review, severity calibration, root-cause analysis, refactor equivalence, security spots), Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost. See [`bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md`](./bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md). Honest caveat: curated set (N=39), not real-transcript sampled; the benchmark found no task where Opus beats Haiku, proving sufficiency for this workload, not parity at the reasoning frontier.
+The benchmark proves it: across 39 judgment tasks (code review, severity calibration, root-cause analysis, refactor equivalence, security spots), Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost. See [`bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md`](./bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md). **Curated set, N=39** — Haiku 39/39 vs Opus 38/39; proves sufficiency for this workload, not frontier parity.
 
 ## 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  
 - **[docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md)** — 10 foundational principles  
 - **[docs/autonomous-swe.md](./docs/autonomous-swe.md)** — What "autonomous" means (and doesn't), evidence for all claims, honest limits  
-- **[RELEASE-NOTES.md](./RELEASE-NOTES.md)** — Version 0.3.0: non-Claude core proof (Codex wave), refinement-loop convergence, Windows-green CI
+- **[RELEASE-NOTES.md](./RELEASE-NOTES.md)** — Version 0.3.1 (the 0.3.0 milestone): non-Claude core proof (Codex wave), refinement-loop convergence, Windows-green CI
 
 ## Contributing
 

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/daemons/install-tasks.ps1

@@ -0,0 +1,193 @@
+param(
+    [string]$BashExe = 'C:\Program Files\Git\bin\bash.exe',
+    [string]$WatchdogCommand = '',
+    [string]$MonitorCommand = '',
+    [int]$WatchdogIntervalMinutes = 5,
+    [int]$MonitorIntervalMinutes = 20,
+    [string]$TaskPrefix = 'Aesop',
+    [switch]$Uninstall,
+    [switch]$DryRun
+)
+
+# Enable strict error handling
+$ErrorActionPreference = 'Stop'
+
+function ConvertTo-PosixPath {
+    param([string]$WindowsPath)
+    # Convert C:\foo\bar to /c/foo/bar
+    # Rejects UNC paths (\\server\share) — error out instead of mangling
+    if ($WindowsPath -match '^\\\\') {
+        Write-Error "UNC paths are unsupported (got: $WindowsPath). Pass -WatchdogCommand explicitly with a valid path."
+        exit 1
+    }
+    $posixPath = $WindowsPath -replace '\\', '/'
+    $posixPath = $posixPath -replace '^([A-Za-z]):', '/$1'
+    return $posixPath
+}
+
+function Get-WorktreeRoot {
+    # Derive worktree root from $PSScriptRoot (daemons/)
+    # $PSScriptRoot is C:\...\aesop\daemons
+    # Parent is C:\...\aesop
+    $daemonsDir = $PSScriptRoot
+    $aesopRoot = Split-Path -Parent $daemonsDir
+    return $aesopRoot
+}
+
+function Register-DaemonTask {
+    param(
+        [string]$TaskName,
+        [string]$Command,
+        [int]$IntervalMinutes,
+        [string]$RunHiddenVbs,
+        [string]$BashExe
+    )
+
+    # Build the action: wscript.exe //B //Nologo "path\to\run-hidden.vbs" "<bash>" -lc "<command>"
+    $action = New-ScheduledTaskAction `
+        -Execute 'wscript.exe' `
+        -Argument "//B //Nologo ""$RunHiddenVbs"" ""$BashExe"" -lc ""$Command"""
+
+    # Build the trigger: Once, starting in 1 minute, repeating every N minutes for 10 years
+    $startTime = (Get-Date).AddMinutes(1)
+    $trigger = New-ScheduledTaskTrigger `
+        -Once `
+        -At $startTime `
+        -RepetitionInterval (New-TimeSpan -Minutes $IntervalMinutes) `
+        -RepetitionDuration (New-TimeSpan -Days 3650)
+
+    # Build the settings: Hidden, IgnoreNew for multiple instances, 1-hour timeout
+    $settings = New-ScheduledTaskSettingsSet `
+        -Hidden `
+        -MultipleInstances IgnoreNew `
+        -ExecutionTimeLimit (New-TimeSpan -Hours 1) `
+        -StartWhenAvailable
+
+    if ($DryRun) {
+        # Print DryRun output
+        Write-Host "DRYRUN: $TaskName -> wscript.exe //B //Nologo ""$RunHiddenVbs"" ""$BashExe"" -lc ""$Command"" (interval=$IntervalMinutes`m, Hidden=True)"
+    }
+    else {
+        # Register the task (force overwrite if exists)
+        try {
+            Register-ScheduledTask `
+                -TaskName $TaskName `
+                -Action $action `
+                -Trigger $trigger `
+                -Settings $settings `
+                -Force `
+                -ErrorAction Stop | Out-Null
+            Write-Host "Registered task: $TaskName (interval=$IntervalMinutes minutes)"
+        }
+        catch {
+            Write-Error "Failed to register task $TaskName : $_"
+            exit 1
+        }
+    }
+}
+
+function Unregister-DaemonTask {
+    param([string]$TaskName)
+
+    try {
+        $task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue
+        if ($task) {
+            Unregister-ScheduledTask -TaskName $TaskName -Confirm:$false -ErrorAction Stop
+            Write-Host "Unregistered task: $TaskName"
+            return $true
+        }
+        else {
+            Write-Host "Task not found: $TaskName (already unregistered or never existed)"
+            return $true
+        }
+    }
+    catch {
+        Write-Error "Failed to unregister $TaskName : $_"
+        return $false
+    }
+}
+
+function Main {
+    # Resolve paths
+    $aesopRoot = Get-WorktreeRoot
+    $runHiddenVbs = Join-Path $PSScriptRoot 'run-hidden.vbs'
+
+    # VALIDATION: Check for double quotes in commands (contract violation)
+    # This check runs early and always, before any operations
+    if ($WatchdogCommand -like '*"*') {
+        Write-Error "WatchdogCommand contains double quotes, which are not allowed (vbs launcher contract violation)."
+        exit 1
+    }
+    if ($MonitorCommand -like '*"*') {
+        Write-Error "MonitorCommand contains double quotes, which are not allowed (vbs launcher contract violation)."
+        exit 1
+    }
+
+    # PATH VALIDATION: Only enforce file existence checks if not in DryRun mode
+    # In DryRun, downgrade to warnings so preview works on machines without Git Bash
+    if (-not $DryRun) {
+        if (-not (Test-Path $runHiddenVbs)) {
+            Write-Error "run-hidden.vbs not found at: $runHiddenVbs"
+            exit 1
+        }
+        if (-not (Test-Path $BashExe)) {
+            Write-Error "bash.exe not found at: $BashExe"
+            exit 1
+        }
+    }
+    else {
+        if (-not (Test-Path $runHiddenVbs)) {
+            Write-Warning "run-hidden.vbs not found at: $runHiddenVbs (DryRun mode)"
+        }
+        if (-not (Test-Path $BashExe)) {
+            Write-Warning "bash.exe not found at: $BashExe (DryRun mode)"
+        }
+    }
+
+    # Handle Uninstall mode
+    if ($Uninstall) {
+        $watchdog_ok = Unregister-DaemonTask -TaskName "${TaskPrefix}WatchdogDaemon"
+        $monitor_ok = Unregister-DaemonTask -TaskName "${TaskPrefix}RefinementMonitor"
+        if (-not $watchdog_ok -or -not $monitor_ok) {
+            exit 1
+        }
+        exit 0
+    }
+
+    # Derive default commands if not provided
+    if (-not $WatchdogCommand) {
+        $posixRoot = ConvertTo-PosixPath $aesopRoot
+
+        # P2: Detect apostrophe in derived path (breaks bash syntax if not escaped)
+        if ($posixRoot -like "*'*") {
+            Write-Error "Repository path contains apostrophe, which would break the derived command: $posixRoot`nPass -WatchdogCommand explicitly."
+            exit 1
+        }
+
+        $WatchdogCommand = "bash '$posixRoot/daemons/run-watchdog.sh' --once >> '$posixRoot/state/cron-watchdog.log' 2>&1"
+    }
+
+    # Register watchdog task
+    $watchdogTaskName = "${TaskPrefix}WatchdogDaemon"
+    Register-DaemonTask `
+        -TaskName $watchdogTaskName `
+        -Command $WatchdogCommand `
+        -IntervalMinutes $WatchdogIntervalMinutes `
+        -RunHiddenVbs $runHiddenVbs `
+        -BashExe $BashExe
+
+    # Register monitor task if command provided
+    if ($MonitorCommand) {
+        $monitorTaskName = "${TaskPrefix}RefinementMonitor"
+        Register-DaemonTask `
+            -TaskName $monitorTaskName `
+            -Command $MonitorCommand `
+            -IntervalMinutes $MonitorIntervalMinutes `
+            -RunHiddenVbs $runHiddenVbs `
+            -BashExe $BashExe
+    }
+
+    exit 0
+}
+
+Main

package/daemons/run-hidden.vbs

@@ -0,0 +1,39 @@
+' run-hidden.vbs — VBScript launcher for Windows Scheduled Tasks
+'
+' Purpose: Execute a command with a hidden console window (window style 0) and
+' propagate its exit code.
+'
+' Usage:
+'   wscript.exe //B //Nologo run-hidden.vbs <bash-exe> -lc "<command>"
+'
+' The script rebuilds a quoted command line from WScript.Arguments and runs it
+' via WScript.Shell.Run with window style 0 (hidden). CRITICAL: The task
+' instance lives as long as the child process (shell.Run waits), so that
+' - MultipleInstances IgnoreNew can prevent concurrent runs
+' - ExecutionTimeLimit can kill hung processes
+' - LastTaskResult reflects the actual child exit code (not always 0)
+'
+' By contract, arguments never contain double quotes.
+
+Dim shell, cmd, i, arg
+Dim windowStyle, rc
+
+Set shell = CreateObject("WScript.Shell")
+
+' Build command line from arguments
+cmd = ""
+For i = 0 To WScript.Arguments.Count - 1
+    arg = WScript.Arguments(i)
+    If i > 0 Then cmd = cmd & " "
+    ' Arguments never contain quotes by contract; wrap in quotes for safety
+    cmd = cmd & """" & arg & """"
+Next
+
+' Window style 0 = hidden; wait for process exit (True = wait)
+windowStyle = 0
+
+' Execute the command and wait for it to complete, capturing exit code
+rc = shell.Run(cmd, windowStyle, True)
+
+' Exit with the child process's exit code
+WScript.Quit rc

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).
 
@@ -283,12 +372,57 @@ To bypass during testing: `git push --no-verify` (not recommended for production
 
 ---
 
+## Windows: Register Daemons as Hidden Scheduled Tasks
+
+On Windows, the watchdog and refinement monitor daemons can run silently in the background without flashing a console window. Use the provided PowerShell installer:
+
+```powershell
+# Register watchdog daemon (every 5m)
+powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1
+
+# Register both watchdog and monitor daemons (monitor script is external, customize path as needed)
+powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1 `
+  -MonitorCommand "bash '/c/path/to/your/monitor/run-monitor.sh' --once"
+
+# Customize intervals and task names
+powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1 `
+  -TaskPrefix MyFleet `
+  -WatchdogIntervalMinutes 10 `
+  -MonitorIntervalMinutes 30 `
+  -MonitorCommand "bash '/c/path/to/your/monitor/run-monitor.sh' --once"
+
+# Uninstall tasks
+powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1 -Uninstall
+
+# Preview without registering (dry-run mode)
+powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1 -DryRun
+```
+
+**How it works**: The installer creates Scheduled Tasks that launch `wscript.exe` with a hidden VBScript launcher (`daemons/run-hidden.vbs`). This avoids the console window that appears when bash.exe is run directly as a Scheduled Task action.
+
+**Parameters**:
+- `-TaskPrefix AesopMyFleet` — Task names: `AesopMyFleetWatchdogDaemon`, `AesopMyFleetRefinementMonitor` (default: `Aesop`)
+- `-WatchdogIntervalMinutes N` — Watchdog cycle interval in minutes (default: 5)
+- `-MonitorIntervalMinutes N` — Monitor cycle interval in minutes (default: 20)
+- `-WatchdogCommand "bash '...' ..."` — Custom watchdog command (default: `run-watchdog.sh --once >> state/cron-watchdog.log`)
+- `-MonitorCommand "bash '...' ..."` — Custom monitor command; omit to skip registering the monitor task (default: empty)
+- `-Uninstall` — Remove all registered tasks
+- `-DryRun` — Preview task configuration without registering
+
+**Constraints**:
+- Commands (`-WatchdogCommand`, `-MonitorCommand`) must NOT contain double quotes (vbs launcher contract)
+- UNC paths (e.g., `\\server\share`) are not supported; use local Windows or POSIX paths only
+- `-DryRun` mode works even if `bash.exe` or run-hidden.vbs is missing (validation downgraded to warnings for preview)
+
+---
+
 ## Next Steps
 
 1. **Read [PORTING.md](PORTING.md)** — Step-by-step guide for adopting Aesop on a foreign repo (10 common failure modes)
 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.