@matt82198/aesop 0.2.0 → 0.3.2

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/HOOK-INSTALL.md

@@ -1,82 +1,41 @@
-# Git Pre-Push Hook Installation Guide
+# Git Pre-Push Hook Setup
 
-**Ship a hook, not a memo.** The pre-push policy hook is **auto-installed during scaffold** (see below). This guide explains customization, verification, and org-wide distribution.
-
-## Security Model: Local Convenience Defense Only
-
-**IMPORTANT**: The pre-push hook is a **local-machine convenience defense** — it is **NOT cryptographic protection**. Any developer can bypass it with `git push --no-verify` or by editing/deleting `.git/hooks/pre-push`. The audit log (`SECURITY-AUDIT.log`) is stored locally and can also be edited by a user with file system access.
-
-**Real enforcement requires server-side branch protection.** See GitHub Configuration below.
+**TL;DR**: The hook is **auto-installed during scaffold**. Real enforcement requires server-side GitHub branch protection.
 
 ## What the Hook Does
 
-`hooks/pre-push-policy.sh` enforces two checks at git push time:
+`hooks/pre-push-policy.sh` enforces:
+1. **Branch Policy** — No direct pushes to `main`/`master` (feature branches only)
+2. **Secret Scan** — `tools/secret_scan.py --staged` blocks credentials
 
-1. **Branch Policy**: Blocks direct pushes to `main` or `master` branches (feature branches only).
-2. **Secret Scan**: Runs `tools/secret_scan.py --staged` to detect credentials before they reach the remote.
+## Security Model
 
-Both blocks append a JSON audit record to `state/SECURITY-AUDIT.log` with timestamp, repo, reason, and user — creating a reviewable trail of policy enforcement.
+**IMPORTANT**: Local hook is a **convenience defense only**—NOT cryptographic protection. Bypass with `git push --no-verify`.
 
-## Auto-Installation During Scaffold
+**Real enforcement**: Pair with GitHub branch protection (server-side). See below.
 
-**Default Behavior:** When you scaffold a new aesop fleet with `npx @matt82198/aesop [target-dir]`, the CLI automatically installs the pre-push hook into `.git/hooks/pre-push`.
+## Auto-Installation
 
-- **On Unix/macOS/Git Bash**: Creates a symlink so hook updates are automatic
-- **On Windows**: Copies the hook directly (symlinks don't work reliably on all NTFS setups)
-- **Idempotent**: Re-running scaffold doesn't clobber a user-customized hook
-- **Preserve Existing**: If you have a different pre-push hook, scaffold warns and preserves it
-- **Force Replace**: Use `npx @matt82198/aesop [target-dir] --force` to replace any existing hook
-
-**Example:**
+Scaffold auto-installs the hook (symlink on Unix, copy on Windows):
 
 ```bash
-# Initial scaffold (creates and installs hook automatically)
-npx @matt82198/aesop my-fleet
-
-# Later: re-scaffold the same directory (preserves customizations)
 npx @matt82198/aesop my-fleet
-
-# Force replace (even if hook was customized)
-npx @matt82198/aesop my-fleet --force
 ```
 
-## Manual Installation
-
-If you're installing into an existing repo (not scaffolded), or you need to manually add the hook:
-
-### Option 1: Symlink (Linux / macOS / Git Bash on Windows)
-
-The cleanest method — hook stays in sync with repo updates:
-
+Manual install:
 ```bash
+# Option 1: Symlink (Unix/macOS/Git Bash)
 ln -s ../../hooks/pre-push-policy.sh .git/hooks/pre-push
-chmod +x .git/hooks/pre-push
-```
-
-### Option 2: Copy (Windows, or to break sync)
-
-Copy the hook directly into `.git/hooks/`:
-
-```powershell
-Copy-Item hooks\pre-push-policy.sh .git\hooks\pre-push
-```
 
-On Windows PowerShell, mark it executable if your git respects file mode:
-
-```bash
-git config core.filemode false
+# Option 2: Copy (Windows)
+cp hooks/pre-push-policy.sh .git/hooks/pre-push
 ```
 
-## Testing
-
-Before committing to org-wide deployment, verify the hook works:
-
+Test:
 ```bash
 bash hooks/pre-push-policy.sh --test
 ```
 
-Expected output: **PASS** for all three checks (branch policy, feature branch allowance, audit log format).
-
 ## GitHub Configuration (Server-Side Enforcement)
 
 To pair this local hook with real enforcement, enable branch protection on GitHub:

package/docs/INSTALL.md

@@ -283,11 +283,56 @@ 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 [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
-2. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
-3. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
+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
 
 For troubleshooting, see the [Aesop README](../README.md#troubleshooting) or [GOVERNANCE.md](GOVERNANCE.md) for operational policies.

package/docs/PORTING.md

@@ -0,0 +1,166 @@
+# Porting Aesop to Your Repository
+
+Guide for adopters porting the orchestration harness to a foreign repo. Step-by-step with prerequisites, scaffold, config, and the 10 likeliest failure modes from real deployments.
+
+---
+
+## Prerequisites
+
+Ensure you have:
+- **Node.js** ≥18 (from `package.json`, `.nvmrc`: v18.20.5)
+- **Python** ≥3.10 (for daemons, health checks, secret-scan)
+- **Git** ≥2.40 (worktree + pre-push hooks)
+- **Bash** v4+ (or Git Bash on Windows)
+- **Optional**: Playwright (for UI verification testing); jq (for dashboard JSON)
+
+Check versions:
+```bash
+node --version && python3 --version && git --version && bash --version
+```
+
+### OS Notes
+- **Windows**: Use Git Bash for all shell commands; paths use `/c/Users/...` POSIX style
+- **Linux/macOS**: Standard Bash; ensure `/usr/bin/bash` or equivalent exists
+
+---
+
+## 1. Scaffold & Install
+
+### Step 1: Create your harness
+```bash
+npx @matt82198/aesop my-fleet \
+  --name "my-project" \
+  --repos "/path/to/repo1,/path/to/repo2"
+```
+
+Creates `my-fleet/` with daemons, skills, config, and UI.
+
+### Step 2: Copy skills to Claude Code home
+```bash
+cp -r my-fleet/skills/power ~/.claude/skills/power
+cp -r my-fleet/skills/buildsystem ~/.claude/skills/buildsystem
+```
+
+### Step 3: Configure & test
+Edit `my-fleet/aesop.config.json`:
+```json
+{
+  "backend": "claude",
+  "aesop_root": "/path/to/my-fleet",
+  "brain_root": "~/.claude",
+  "repos": [
+    { "path": "/path/to/repo1", "name": "my-project" }
+  ],
+  "dashboardPort": 8770
+}
+```
+
+Test dashboard backend (Ollama example):
+```json
+{
+  "backend": "openai-compatible",
+  "base_url": "http://localhost:11434/v1",
+  "model": "mistral",
+  "is_local": true
+}
+```
+
+### Step 4: Install pre-push hook
+```bash
+mkdir -p my-fleet/.git/hooks
+cp my-fleet/hooks/pre-push-policy.sh my-fleet/.git/hooks/pre-push
+chmod +x my-fleet/.git/hooks/pre-push
+```
+
+### Step 5: Verify with health check
+```bash
+cd my-fleet
+python tools/health_score.py
+```
+Expected output: All checks ✓; port 8770 available; git hooks installed.
+
+---
+
+## 2. First `/power`, First Wave
+
+Run the orchestrator once to prime the brain:
+```bash
+cd my-fleet
+/power
+```
+Expected output: State created (STATE.md, BUILDLOG.md, .watchdog-heartbeat).
+
+Run one complete wave:
+```bash
+/buildsystem --one-turn
+```
+Expected verdicts: All items "PASS" or "REVIEW"; zero code defects. Health score should report ≥85/100.
+
+---
+
+## 3. The 10 Likeliest Failure Modes
+
+Each: symptom → cause → fix.
+
+### 1. Secret-scan blocks legit push
+- **Symptom**: `git push` fails: "secret detected" but code has no real secret
+- **Cause**: Test fixtures with dummy secrets (credit card, API key patterns) are parsed as real
+- **Fix**: Assemble secrets at runtime: `"key" + "_" + "123"` not `"key_123"`; use `---` delimiters in comments. Secret-scan only scans staged files, not .git.
+
+### 2. Worktree isolation violated
+- **Symptom**: Editing feature branch X; changes also appear in primary tree
+- **Cause**: Agents not using isolated worktrees; sharing same `.git/index`
+- **Fix**: Each agent task must use `git worktree add ../wt-item-slug -b feature/item-slug origin/main`; verify with `git worktree list`
+
+### 3. Heartbeat stale/missing
+- **Symptom**: Watchdog won't start; error: "unreadable state dir" or "stale heartbeat"
+- **Cause**: `state/.watchdog-heartbeat` missing/corrupted or directory unreadable (permissions)
+- **Fix**: `rm -f state/.watchdog-heartbeat && bash daemons/run-watchdog.sh --once` (re-creates it)
+
+### 4. Port 8770 conflict
+- **Symptom**: `python ui/serve.py` fails: "Address already in use"
+- **Cause**: Old dashboard process still bound, or another service using port 8770
+- **Fix**: `lsof -i :8770 | grep -v PID | awk '{print $2}' | xargs kill -9` (Mac/Linux); Windows: `netstat -ano | grep 8770`, kill the PID. Or change `dashboardPort` in config.
+
+### 5. Git identity placeholder
+- **Symptom**: Pre-push hook fails: "user identity invalid"; commits fail
+- **Cause**: Git config has template defaults (e.g., "John Doe") instead of your name
+- **Fix**: `git config user.name "Your Name" && git config user.email "you@example.com"`
+
+### 6. CRLF line endings corrupt scripts
+- **Symptom**: Bash script fails: "command not found" at line 50 (but line 50 exists)
+- **Cause**: Editor/Windows converted LF to CRLF; bash reads `\r` as part of command
+- **Fix**: `git config core.autocrlf false` locally; convert file: `dos2unix daemons/run-watchdog.sh`
+
+### 7. Test count drift in CI
+- **Symptom**: Health-check fails: "expected 127 tests, got 128"
+- **Cause**: Added new test file but didn't update baseline in tools/health_score.py or CI config
+- **Fix**: Run `python tools/health_score.py --json` to get true count; update baseline in CI gate
+
+### 8. UTF-8 encoding on Windows
+- **Symptom**: Pre-publish gate fails with encoding error in secret_scan.py
+- **Cause**: Python opens files in system encoding (cp1252) instead of UTF-8
+- **Fix**: Aesop tools now force UTF-8 internally; ensure `PYTHONIOENCODING=utf-8` if running external Python scripts
+
+### 9. Cost ceiling never triggers
+- **Symptom**: Cost ceilings configured; spending uncapped; halt never fires
+- **Cause**: Claude Code driver returns `get_tokens_spent()=None`; coerces to 0; ledger fallback skipped
+- **Fix**: For Claude Code, cost tracking integrates live API; for non-Claude backends, ledger fallback logs at end of wave
+
+### 10. Hook TTY behavior blocks CI pushes
+- **Symptom**: `git push` fails in CI/cron: "cannot read stdin"; interactive prompt hangs
+- **Cause**: Hook tries to detect TTY when stdin is `/dev/null` (non-interactive context)
+- **Fix**: Hook now handles empty stdin (rc=2 for delete-only, skip scan + log); use `hooks/pre-push-policy.sh --test` in CI (no-op validation)
+
+---
+
+## Next Steps
+
+1. **Read [INSTALL.md](./INSTALL.md)** — Full setup and environment variables
+2. **Run [health_score.py](../tools/health_score.py)** — Continuous readiness checks
+3. **Explore the [README](../README.md)** — Demo walkthrough and proof numbers
+4. **For troubleshooting**, check [GOVERNANCE.md](./GOVERNANCE.md) or open an issue on GitHub
+
+---
+
+**License**: PolyForm Strict 1.0.0 (source-available, noncommercial). See [LICENSE](../LICENSE) for details.