@matt82198/aesop 0.1.0-rc.1 → 0.2.0

package/CHANGELOG.md

@@ -5,7 +5,106 @@ 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).
 
-## [Unreleased]
+## [0.2.0] - 2026-07-21
+
+Minor release shipping multi-model orchestration portability and adaptive verification safety.
+
+### Added
+- **AgentDriver Phase 1-3 shipping** (wave-32+): Complete multi-model driver abstraction with three production drivers — Claude Code reference adapter, OpenAI-compatible backend (Ollama, OpenRouter, etc.), and Phase 3 wave bridge enabling any backend to drive coding tasks end-to-end with verified-honest verification tiers.
+- **Multi-instance identity & coordination** (wave-32): Instance ID tagging (hostname:pid:nonce) and lease-by-append claims enable multi-writer coordination without collisions (fail-closed). Foundation for team-scale Aesop.
+- **Honest verification-tier wiring** (wave-32): Weaker backends automatically trigger higher verification (tier 2→tier 4) — no code changes required; orchestrator transparently adapts rigor based on driver capabilities.
+- **OpenAI-compatible backend configuration** (wave-32): `aesop.config.json` backend section configures model, base_url, and API key for local Ollama or OpenRouter inference.
+- **Cost-ceiling enforcement** (wave-32): Per-wave spend ceiling enforced at dispatch time; blocks work if budget exceeded.
+- **Transcript-sampled benchmark Phase 1** (wave-32): Infrastructure to extract coding tasks from real Claude Code session transcripts, enabling dynamic benchmark growth beyond hand-written examples.
+- **Backend config & role resolution** (wave-32): `backend_config.py` for per-deployment model mappings (worker/setup/verify roles) without orchestrator changes.
+
+### Changed
+- **Verification policy transparent** (wave-32): Verification tiers now driven by `AgentDriver.probe_capabilities()` — config-free, capability-driven safety.
+
+### Fixed
+- **Authorization header cross-origin stripping** (PR #221): Blocks Authorization headers on cross-origin redirects to prevent credential leakage; security hardening for urllib transport.
+- **Secret-scan fail-closed on read errors** (PR #226): `secret_scan.py` now fails CLOSED when unable to read files or git data, blocking pushes instead of silently passing; P1 security.
+- **Driver subsystem in npm package** (PR #220): Multi-model AgentDriver backend abstraction now ships in the npm package, enabling production use of alternative backends.
+- **CI/publish Node version parity** (PR #225): Unified Node.js version across CI and npm publish workflows for reproducible builds.
+- **Adversarial-review safety fixes** (wave-32): Multiple orchestration loop hardening fixes identified and validated by external review (agent-grading-agent risks eliminated).
+
+### Security & Hardening (Post-Release Fixes)
+
+Critical hardening round integrated after 0.2.0 release-artifact preparation (fe6bb04, 2026-07-21):
+
+**AI & Prompt Security:**
+- **Codex prompt-injection hardening** (fix/codex-prompt-injection): JSON-wrapped framing prevents prompt injection in orchestration context; multi-layer escaping for task/dispatch boundaries (P1 AI-security).
+- **Codex frame integrity** (fix/codex-frame-integrity): SHA-256 digest + retry nudge for frame integrity verification across API boundaries; prevents frame corruption from in-flight mutations.
+- **Codex path containment** (fix/codex-driver-path-containment): Cross-platform path normalization (Windows: `resolve()` + `commonpath()`, Unix: realpath) blocks directory traversal in task file operations (P2 security).
+- **Codex escape-accounting** (fix/codex-prompt-injection): Measure `max_owned_bytes` post-escape to detect prompt-injection breakout payloads (P1 AI-security).
+
+**System & Daemon Hardening:**
+- **Daemon fail-closed on lock errors** (fix/daemons-lock-portability): Pre-push and coordination daemons now fail CLOSED on file-write errors, lock-acquisition timeout, or heartbeat stalls; prevents silently-skipped enforcements. CONDUCTOR_ROOT portability (Windows/Unix path handling).
+
+**Data & Audit Security:**
+- **Audit log JSON escaping** (fix/audit-log-repo-escape): Escape `repo_name` and payload fields in audit-log JSON emits to prevent injection attacks on durable audit trail (P1 security).
+- **Audit-tail verdict fix** (fix/audit-tail-verdict): Correct column index in wave_audit_tail.py verdict parsing and add validation whitelist to prevent misclassified wave outcomes.
+
+**Transcript & Observability Hardening:**
+- **Redaction-proof transcript digest** (verify_ui_trio.py): Single-source redaction patterns (`transcript_digest.py`) ensure sensitive data (API keys, internal tokens, paths) are consistently masked across all observability exports — dashboard, audit, and external integrations.
+
+**Pre-Push & CI Hardening:**
+- **Pre-push delete-refspec hardening** (fix/prepush-delete-refspecs): Enforce branch-protection policy on force-delete and fast-forward-only mutations; prevent refspec conflicts from stalling the merge train.
+- **Empty-stdin handling** (fix/prepush-delete-refspecs): Guard pre-push hook against stalled CI merge-wait (empty stdin → timeout → fail-closed block).
+- **Cost-ceiling fail-closed** (fix/cost_ceiling): Per-wave spend ceiling now enforced at dispatch time; fails CLOSED on file/git read errors. **Caveat:** Enforced at every dispatch gate on ALL backends: drivers reporting live token spend are metered directly; drivers that cannot observe per-instance spend (the Claude Code reference driver, by honest contract) return None and the ceiling reads the outcomes ledger itself with proper period windowing.
+
+### Documentation
+- **Multi-model configuration guide** (wave-32): docs/INSTALL.md now includes "Using Non-Claude Backends" section with Ollama example, verification-tier table, and troubleshooting.
+- **Driver domain map complete** (wave-32): driver/CLAUDE.md now lists all Files (openai_compatible_driver.py, backend_config.py) with descriptions for one-file-per-domain rule.
+- **State_store coordination modules** (wave-32): state_store/CLAUDE.md Module Layout now includes coordination.py and identity.py.
+
+## [0.1.1] - 2026-07-17
+
+Patch release with first-hour adopter fixes, orchestration performance improvements, and observability enhancements. Targets users deploying 0.1.0 to production and the fleet during active wave execution.
+
+### Adopter / First-hour Fixes
+- **Git init + --no-git scaffold flag** (wave-rc6): New `--no-git` scaffolder option for adopters integrating into existing repos without re-initializing version control.
+- **Port conflict detection** (wave-rc6): CLI and doctor now detect and report port-binding conflicts before dashboard startup; helpful error messages with conflict resolution steps.
+- **Next-steps ordering** (wave-rc5): Orchestration template ordering fixed so next-steps appear after state blocks, improving readability for first runs.
+- **Aesop doctor subcommand** (wave-rc4): New preflight check validates configuration, hooks, state store health, and port availability before wave startup.
+- **Executable bits in tarball** (wave-rc4): Vendored dispatch template + scripts now ship with correct execution bits set (CLI was inventing a standalone validator; real one now included).
+
+### Orchestration / Performance
+- **Wave-dispatch template latency** (wave-rc5): Targeted performance repairs — self-check parallelization, postBuild hooks, multi-testCmd batching for faster feedback cycles.
+- **Wave preflight validator** (wave-rc5): New structural validation before dispatch prevents malformed config from blocking the build.
+- **CI merge-wait fail-closed** (wave-rc3): `ci_merge_wait` timeout now blocks dispatch (fail-closed) instead of silently passing; prevents merging while CI is still running.
+
+### Observability / Instrumentation
+- **OUTCOMES-LEDGER producer** (wave-rc5): Append-wave ledger tracks per-wave execution outcomes (dispatch time, wave duration, merge timing) for fleet analytics.
+- **CI workflow linter** (wave-rc5): New `tools/ci_workflow_lint.py` statically validates GitHub Actions YAML (npm-ci lockfile presence, every package.json test script is invoked, file references resolve) — catches the green-means-never-ran class.
+- **Failure drilldown** (wave-rc3): Enhanced error reporting in dashboard drill-down view — inspect failure reasons, cost metrics, and agent transcript timestamps per-incident.
+- **Cost-economics dashboard** (wave-rc4): Wave-level cost analytics with model breakdown, per-day bar chart (pure SVG), verdict scorecard (success/failure/hung rates), pricing estimates from config.
+- **MCP cost tools** (wave-rc3): New read-only MCP cost-ledger and cost-ceiling tools expose spend tracking for external Claude integrations.
+- **Transcript digest + claudemd_lint** (wave-rc6-obs): New tools/artifact for post-wave transcript summarization and CLAUDE.md scope linting (3-line max per section, enforcement on drift).
+
+### Security & Reliability
+- **Gitignore-respecting secret scan** (wave-rc5): `secret_scan.py` now respects `.gitignore` patterns; skips ephemeral runtime files (state/, .env files, node_modules traces) to reduce false positives and scan time.
+- **Aesop fleet CLI** (wave-rc3): New `aesop fleet` subcommand suite for production fleet inspection (list agents, query costs, export telemetry).
+
+### Documentation & Portability
+- **ANY-REPO portability** (wave-rc4): Aesop now scaffolds into any existing Node/Python repo; setup guides, CONTRIBUTING.md, GitHub issue templates (SECURITY.md, CODE_OF_CONDUCT) included.
+- **Domain CLAUDE.md minification** (wave-rc6): All domain-specific documentation scoped to one file per Haiku task; root CLAUDE.md now a pure map for faster load and maintenance.
+- **CONTRIBUTING guide** (wave-rc6): Contributor workflow, test running, release process, branching discipline documented with examples.
+
+### Tests
+- **Full gate green** (all waves): npm run test:py && test:node + all shell suites + secret-scan pass without signature warnings.
+
+## [0.1.0] - 2026-07-17
+
+First stable release. This is the graduation of `0.1.0-rc.1` to a stable version with the
+same feature set — no code changes beyond the version/documentation promotion. It publishes to
+npm under the `latest` dist-tag. Highlights carried from rc.1: verified Opus audit (0
+hallucinated findings), kill-switch wired into the live dispatch path, cost-ceiling guardrail,
+a measured held-out benchmark (39 judgment tasks, Haiku on par with Opus at ~1/3 the cost),
+the state-reconcile primitive, browser-proven dashboard views (Wave PR Board + Agent
+Inspector), a source-available license, and a slim, reproducible ~409 kB npm package. See the
+[0.1.0-rc.1] entry below for the full itemized list, and RELEASE-NOTES.md for the honest-limits
+account (small-N benchmark, cost-ceiling not yet tied to live token spend, local-first).
 
 ## [0.1.0-rc.1] - 2026-07-17
 
@@ -239,7 +338,7 @@ package ships slim and reproducible from a clean clone.
 
 ## Initial Release
 
-This is the first public release of Aesop, a clean-room open-source implementation of the fable-fleet orchestration harness. The codebase includes:
+This is the first public release of Aesop, a clean-room source-available implementation of the fable-fleet orchestration harness. The codebase includes:
 
 - The complete orchestration engine with watchdog and monitor
 - Web dashboard for fleet observability

package/README.md

@@ -3,22 +3,24 @@
 </p>
 
 <p align="center">
-  <em>Fable-Fleet Orchestration Harness</em>
+  <em>Autonomous Developer for Any Repository</em>
 </p>
 
 <p align="center">
   <a href="https://github.com/matt82198/aesop/actions/workflows/ci.yml"><img src="https://github.com/matt82198/aesop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://www.npmjs.com/package/@matt82198/aesop"><img src="https://img.shields.io/npm/v/@matt82198/aesop/rc" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/@matt82198/aesop"><img src="https://img.shields.io/npm/v/@matt82198/aesop" alt="npm"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Strict%201.0.0-orange.svg" alt="License: PolyForm Strict 1.0.0 (source-available)"></a>
 </p>
 
-**Aesop** is a source-available orchestration harness for Claude Code that builds itself. It runs a `/buildsystem` wave cycle—ranking a backlog, fanning out parallel Haiku agents (1/3 the cost of Sonnet, 1/5 the cost of Opus), watchdogging them, verifying merges, then feeding the next wave via audit + ideation + fleet-ops monitoring. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
+**Aesop** is a source-available autonomous developer that crawls into any repository and orchestrates intelligent work—**ranking tasks, dispatching parallel Haiku agents, verifying merges, auditing the work, and feeding the next iteration.**
 
-As of **0.1.0-rc.1**, that loop has carried the project to an installable, tested, audited, and benchmarked release candidate—the fleet running the wave loop on its own, under a human who sets goals and owns the outward gates. The claims below are backed by committed artifacts you can check, not adjectives. See [Milestone: it shipped itself](#milestone-it-shipped-itself-010-rc1).
+What makes Aesop different: **durable state persists across multiple instances**, so your whole team uses one coordinated system. The state layer (`state_store/`) runs append-only events in SQLite (concurrent, transactional), rendered to git for checkpoints and hand-offs. Pair with [/power](#use-with-claude-code) (system init) and [/buildsystem](#core-concepts-and-operations) (the wave loop), and Aesop runs your delivery cycle—on any repository, any codebase shape, indefinitely. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
 
-What you get: **cost-optimized multi-agent dispatch** (Haiku-first subagents, lean orchestrator), **durable state** (git-committed checkpoints survive wipes), **observable machinery** (every agent run logged, every cost tracked), **live dashboard** (real-time fleet health at http://localhost:8770), and **security gates** (secret-scan blocks pushes, CI validates each merge).
+As of **0.1.0**, that loop has carried the project to an installable, tested, audited, and benchmarked stable release—the fleet running the wave loop on its own, under a human who sets goals and owns the outward gates. The claims below are backed by committed artifacts you can check, not adjectives. See [Milestone: it shipped itself](#milestone-it-shipped-itself-010).
 
-## Milestone: it shipped itself (0.1.0-rc.1)
+**Cost-optimized multi-agent dispatch** (Haiku-first subagents, lean orchestrator) · **Durable state** (SQLite events + git exports, survives wipes) · **Observable machinery** (every agent run logged, every cost tracked) · **Live dashboard** (real-time fleet health at http://localhost:8770) · **Security gates** (secret-scan blocks pushes, CI validates each merge).
+
+## Milestone: it shipped itself (0.1.0)
 
 Aesop reached its first release candidate by running its own wave loop—**audit → parallel build → verify → merge-train**—across the backlog that produced it. This is the version where the load-bearing claims stopped being illustrations and became measurements. The word "autonomous" has a precise, deliberately narrow meaning here.
 
@@ -36,9 +38,49 @@ The differentiator is not "an AI wrote code." It's that the credibility and safe
 
 **Nobody outside this project has reproduced these results yet.** The evidence is committed so a skeptical reader can check it — that transparency is the point, not a substitute for independent replication. For the full, unhedged account of what is and isn't proven, read [docs/autonomous-swe.md](./docs/autonomous-swe.md) and the ["Honest limits" section of the release notes](./RELEASE-NOTES.md#honest-limits).
 
+## Core Concepts and Operations
+
+### What /power Does
+
+`/power` initializes Aesop into a fresh repository. It:
+- Loads your orchestrator brain (cardinal rules, domain map, team memory, system state)
+- Verifies the system is healthy (filesystem, git, API keys, watchdog)
+- Outputs a health brief and next-step recommendations
+
+Run `/power` at the start of each session when using Claude Code. It's idempotent—safe to run multiple times. Setup once:
+
+```bash
+cp -r skills/power/ ~/.claude/skills/power/
+```
+
+Then in Claude Code, type `/power` to initialize.
+
+### What /buildsystem Does
+
+`/buildsystem` runs **one complete wave cycle** of the autonomous delivery loop. It:
+1. **Ranks** the backlog (priority, dependencies, team affinity)
+2. **Dispatches** parallel Haiku agents on file-disjoint domains (tests, build, docs, UI, review, etc.)
+3. **Verifies** each merge (CI, security scans, audit spot-checks)
+4. **Checkpoints** (STATE.md + BUILDLOG.md committed to git, survive wipes)
+5. **Audits** fleet health and feeds next backlog (monitor signals, signal collectors, findings)
+
+This is **not** a one-off fix or a single pass—it's the repeatable loop that runs your delivery cycle indefinitely, with each wave learning from the prior audit. You can run `/buildsystem` once per wave (typically 30 min–2 hours per wave depending on backlog size and scope).
+
+See [docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md) for a concrete walkthrough of one complete cycle.
+
+### Team State & Multi-Instance Vision
+
+**Current Status (0.1.0)**: Single-instance proven. A team uses Aesop by designating one operator who runs the wave loop. State is durably checkpointed in git (STATE.md, BUILDLOG.md, tracker.json exports).
+
+**In Design**: Multi-instance coordination via the state_store substrate. The event-sourced SQLite layer (`state_store/`) is production-ready but currently opt-in. A future release will enable multiple Aesop instances (e.g., per-team subgroups, geographic regions, or specialized fleets) to coordinate around a single source of truth—a Postgres-backed event log, with git as a diffable export. See [docs/TEAM-STATE.md](./docs/TEAM-STATE.md) (design in progress) for the vision and current architecture decisions.
+
 ## Why Aesop?
 
-Multi-agent AI fleets hit a wall: all-Opus orchestrators cost $10k+ per wave, and machine crashes lose state—losing work and context on restart. Aesop solves both: **Haiku-first** dispatch cuts costs to 1/3 of Opus, and **git-committed state** (STATE.md, BUILDLOG.md) survives machine wipes with zero data loss. See the wave cycle below: ranked backlog → parallel worktree-isolated fleet → merge train → checkpoint → audit feeds next wave.
+Multi-agent AI fleets hit two walls: all-Opus orchestrators cost $10k+ per wave, and machine crashes lose state—losing work and context on restart. Aesop solves both:
+
+- **Haiku-first dispatch** cuts costs to ~1/3 of Opus (Haiku subagents, Opus orchestrator).
+- **Durable state** (SQLite event log + git-rendered exports) survives machine wipes with zero data loss and enables team/multi-instance coordination.
+- **Portable orchestration** works on any repository; no custom agents per repo needed.
 
 ```
 ranked backlog
@@ -66,16 +108,18 @@ audit + fleet-ops monitoring
 - **Live web dashboard** — Real-time fleet health, security alerts, work-item kanban at `http://localhost:8770`.
 - **Secret-scan gates** — Pre-push hook blocks leaks; audit trail logged. Pair with GitHub branch protection for enforcement.
 - **Read-only MCP Fleet Server** — Expose fleet status, active agents, work items, and cost metrics to Claude Code (fleet_status, fleet_agents, fleet_tracker, fleet_cost tools). See [mcp/CLAUDE.md](./mcp/CLAUDE.md) for setup.
+- **Multi-model portability** — AgentDriver abstraction decouples the wave loop from Claude Code; drivers for Claude Code, OpenAI-compatible backends (Ollama, OpenRouter), and Codex. Honest verification tiers: weaker backends get more checking. See [driver/README.md](./driver/README.md).
 - **Self-diagnosing npm publish** — OIDC token generation and publish reliability verified on each release; workflow surfaces diagnostics inline.
+- **Verification & quality tooling** — mutation_test.py for test-quality assessment, defect_escape.py for first-try-green telemetry, held-out benchmark for robustness, and adversarial review to break and harden the orchestration loop.
 
 ## Get Started (3 steps, 5 min)
 
-**Note:** Aesop is at its first release candidate. Install the `@rc` tag for the latest prerelease (v0.1.0-rc.1); the `@beta` tag remains available for earlier prereleases.
+**Note:** Aesop's first stable release is `0.1.0`, published to npm under the `latest` tag — a plain `npx @matt82198/aesop` or `npm install @matt82198/aesop` pulls it. Earlier prereleases remain available under the `@rc` and `@beta` tags.
 
 ### Quickest path: npx scaffold
 
 ```bash
-npx @matt82198/aesop@rc my-fleet \
+npx @matt82198/aesop my-fleet \
   --name "my-api" \
   --repos "/path/to/repo1,/path/to/repo2"
 cd my-fleet
@@ -130,17 +174,23 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 170 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 556 <!-- metrics-verified: self_stats.py (git log) --> |
-| Project Age | 5 days <!-- metrics-verified: self_stats.py (git log) --> |
+| 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) --> |
 | Waves | 30 <!-- metrics-verified: self_stats.py (git log) --> |
-| Insertions + Deletions | 96,065 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 336 <!-- 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) --> |
 
 <!-- STATS:END -->
 
 
+
+
+
+
+
+
 ## Recommended Agents
 
 Aesop pairs well with the open-source catalog of ~130 community-authored specialized agent definitions (TDD orchestrators, security reviewers, performance engineers, etc.). For optimal results, install agents from the upstream source and pair them with Aesop's cost-optimized Haiku dispatch. This is optional; Aesop works standalone with general-purpose Claude Code agents.
@@ -269,6 +319,7 @@ The dev server proxies `/data`, `/api`, `/events`, `/agent`, `/submit` to the Py
 - [docs/PUBLISHING.md](./docs/PUBLISHING.md) — Release Aesop to npm
 - [docs/autonomous-swe.md](./docs/autonomous-swe.md) — The 0.1.0-rc.1 milestone told honestly: what "autonomous SWE" means here, the evidence behind each claim, and the limits the project owns
 - [docs/case-study-portfolio.md](./docs/case-study-portfolio.md) — How Aesop built its own portfolio site; full audit trail and cost breakdown
+- [docs/TEAM-STATE.md](./docs/TEAM-STATE.md) — Multi-instance and team coordination via state_store (design in progress)
 
 See [CHANGELOG.md](./CHANGELOG.md) and [RELEASE-NOTES.md](./RELEASE-NOTES.md) for release notes.
 
@@ -295,4 +346,4 @@ Copyright 2026 Matt Culliton.
 
 ---
 
-**Aesop**: Fable-fleet orchestration, built by Aesop itself. May your orchestrator be wise and your subagents swift.
+**Aesop**: Autonomous developer for any repository, built by Aesop itself. May your orchestrator be wise and your subagents swift.

package/bin/cli.js

@@ -11,8 +11,8 @@ const helpFlag = args.includes('--help') || args.includes('-h');
 const forceFlag = args.includes('--force');
 const yesFlag = args.includes('--yes');
 
-// Check for runtime subcommands (doctor, watch, dash, status)
-const runtimeCommands = ['doctor', 'watch', 'dash', 'status'];
+// Check for runtime subcommands (doctor, watch, dash, status, fleet, health-score)
+const runtimeCommands = ['doctor', 'watch', 'dash', 'status', 'fleet', 'health-score'];
 const isRuntimeCommand = runtimeCommands.includes(args[0]);
 
 if (isRuntimeCommand) {
@@ -20,7 +20,9 @@ if (isRuntimeCommand) {
     'doctor': '../tools/doctor.js',
     'watch': '../tools/watch.js',
     'dash': '../tools/dash.js',
-    'status': '../tools/status.js'
+    'status': '../tools/status.js',
+    'fleet': '../tools/fleet.js',
+    'health-score': '../tools/health-score.js'
   };
   // Load and run the appropriate runtime module
   // These modules run async code that sets process.exitCode and will cause Node to exit
@@ -71,6 +73,66 @@ function validatePort(port) {
   return !isNaN(p) && p > 0 && p < 65536 ? p : null;
 }
 
+// Test if a port is available (returns Promise<boolean>)
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const net = require('net');
+    const sock = net.createConnection({ port, host: '127.0.0.1', timeout: 500 });
+    let resolved = false;
+
+    const cleanup = () => {
+      try {
+        sock.destroy();
+      } catch (e) {
+        // Ignore cleanup errors
+      }
+    };
+
+    sock.on('connect', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(false);  // Port is in use
+      }
+    });
+
+    sock.on('error', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);  // Port is free
+      }
+    });
+
+    sock.on('timeout', () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);  // Assume free on timeout
+      }
+    });
+
+    // Fallback timeout
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);
+      }
+    }, 2000);
+  });
+}
+
+// Find next available port starting from basePort
+async function findAvailablePort(basePort = 8770) {
+  for (let port = basePort; port < basePort + 100; port++) {
+    if (await isPortAvailable(port)) {
+      return port;
+    }
+  }
+  return basePort;  // Fallback to basePort
+}
+
 // Parse named flags
 function getFlag(flagName) {
   const idx = args.findIndex(arg => arg === flagName);
@@ -91,12 +153,14 @@ Usage:
   npx @matt82198/aesop watch
   npx @matt82198/aesop dash
   npx @matt82198/aesop status
+  npx @matt82198/aesop fleet
 
 Commands:
   doctor                  Preflight readiness check (Node.js, Python, git, config, dirs, hook, port)
   watch                   Launch the watchdog daemon (spawns daemons/run-watchdog.sh)
   dash                    Launch the web dashboard (spawns python3 ui/serve.py or python fallback)
   status                  One-shot fleet status snapshot (heartbeats, dashboard port, git branch)
+  fleet                   One-shot fleet snapshot (agents, heartbeats, tracker lanes, orchestrator status)
   wizard                  Interactive onboarding (prompts for project name, repos, port)
 
 Arguments:
@@ -116,6 +180,7 @@ Examples:
   npx @matt82198/aesop watch                                # Launch watchdog daemon
   npx @matt82198/aesop dash                                 # Launch web dashboard (default localhost:8770)
   npx @matt82198/aesop status                               # Show fleet status (heartbeats, port, git)
+  npx @matt82198/aesop fleet                                # Show fleet snapshot (JSON agents, heartbeats, tracker, orchestrator)
   npx @matt82198/aesop                                      # Creates ./aesop-fleet/ with template
   npx @matt82198/aesop my-fleet                             # Creates ./my-fleet/ with template
   npx @matt82198/aesop wizard                               # Interactive onboarding (60-second setup)
@@ -314,7 +379,7 @@ function substituteTemplate(templateContent, projectName, domainsStr, reposStr)
   return result;
 }
 
-function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repoUrlsStr) {
+function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repoUrlsStr, port = 8770) {
   // Read example config
   const exampleConfigPath = path.join(templateRoot, 'aesop.config.example.json');
   let exampleConfig;
@@ -348,7 +413,8 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
       dashboard: {
         refresh_seconds: 1,
         enable_jq_parsing: true,
-        theme: 'dark'
+        theme: 'dark',
+        port: 8770
       },
       cardinal_rules: {
         subagent_model: 'haiku',
@@ -366,6 +432,8 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
   exampleConfig.scripts_root = '~/scripts';
   exampleConfig.temp_root = '~/.aesop-temp';
   exampleConfig.fleet_root = os.homedir();
+  exampleConfig.dashboard = exampleConfig.dashboard || {};
+  exampleConfig.dashboard.port = port;
   exampleConfig._generated_note = 'This config uses portable ~ paths which expand at runtime on all platforms. Config loaders in ui/config.py (Python) and monitor/collect-signals.mjs (Node.js) automatically expand ~ paths to your home directory.';
 
   // Parse repos if provided
@@ -392,14 +460,14 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
 
 // Print next steps and optionally run watchdog (returns a Promise)
 async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
-  console.log('\n🎯 Next 3 commands to get started:\n');
+  console.log('\n🎯 Next 2 commands to get started:\n');
   console.log(`  1. cd ${targetDir}`);
   console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
   console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${port})`);
-  console.log('\n📖 After that, review:');
-  console.log('  • CLAUDE.md (pre-filled with your project info)');
-  console.log('  • aesop.config.json (pre-configured for your repos)');
-  console.log('  • docs/MEMORY-TEMPLATE.md (edit ~/.claude/MEMORY.md with your facts)\n');
+  console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+  console.log('  mkdir -p ~/.claude/memory');
+  console.log(`  cp ${targetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+  console.log(`  cp ${targetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)\n`);
 
   return new Promise((resolve) => {
     rl.question('Run watchdog --once now? (y/N): ', (answer) => {
@@ -422,6 +490,37 @@ async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
   });
 }
 
+// Initialize git repo if it doesn't exist
+function initializeGitRepo(targetDir, noGitFlag = false) {
+  if (noGitFlag) {
+    return false;  // User explicitly requested no git
+  }
+
+  const gitDir = path.join(targetDir, '.git');
+  if (fs.existsSync(gitDir)) {
+    return false;  // Git already initialized
+  }
+
+  try {
+    // Initialize git repo
+    execSync('git init -q', { cwd: targetDir, stdio: 'pipe' });
+    console.log('✓ Initialized git repository');
+
+    // Create initial commit
+    execSync('git config user.email "aesop-scaffold@local"', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git config user.name "Aesop Scaffold"', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git add -A', { cwd: targetDir, stdio: 'pipe' });
+    execSync('git commit -q -m "Initial aesop scaffold"', { cwd: targetDir, stdio: 'pipe' });
+    console.log('✓ Created initial git commit');
+    return true;
+  } catch (e) {
+    // Git operations failed, continue anyway
+    console.warn('⚠ Warning: Failed to initialize git repo automatically');
+    console.warn('  Run manually: cd ' + targetDir + ' && git init && git add -A && git commit -m "Initial commit"');
+    return false;
+  }
+}
+
 function installPreCommitWaveguard(targetDir, templateRoot) {
   // Install the pre-commit waveguard hook to prevent commits during a wave
   // Try to locate .git directory
@@ -664,6 +763,7 @@ if (!isRuntimeCommand) {
     let finalTargetDir = targetDir;
     let configPath = path.join(targetDir, 'aesop.config.json');
     let dashboardPort = 8770;
+    const noGitFlag = args.includes('--no-git');
 
     let wizardRl = null;
 
@@ -704,7 +804,7 @@ if (!isRuntimeCommand) {
       }
       finalReposStr = selectedRepos;
 
-      // Q3: Dashboard port
+      // Q3: Dashboard port (with availability check)
       let port = '';
       while (!port) {
         port = await promptUser(wizardRl, 'Dashboard port', '8770');
@@ -713,7 +813,21 @@ if (!isRuntimeCommand) {
           console.log('  ✗ Invalid port. Must be a number between 1 and 65535.');
           port = '';
         } else {
-          dashboardPort = validPort;
+          // Check if port is available
+          const available = await isPortAvailable(validPort);
+          if (!available) {
+            console.log(`  ⚠ Port ${validPort} is in use. Trying next available port...`);
+            const nextPort = await findAvailablePort(validPort);
+            if (nextPort !== validPort) {
+              console.log(`  → Using port ${nextPort} instead`);
+              dashboardPort = nextPort;
+            } else {
+              dashboardPort = validPort;
+            }
+            port = validPort.toString();  // Exit loop
+          } else {
+            dashboardPort = validPort;
+          }
         }
       }
 
@@ -728,8 +842,15 @@ if (!isRuntimeCommand) {
       // Non-interactive defaults for wizard mode with --yes
       finalProjectName = 'my-fleet';
       finalReposStr = '';
-      dashboardPort = 8770;
+      // Find available port
+      dashboardPort = await findAvailablePort(8770);
       console.log('🪄 Running onboarding wizard with defaults (--yes)');
+    } else if (!wizardMode && finalProjectName) {
+      // Headless mode: check and find available port
+      dashboardPort = await findAvailablePort(8770);
+      if (dashboardPort !== 8770) {
+        console.log(`ℹ Port 8770 is in use, using port ${dashboardPort} instead`);
+      }
     }
 
     // Copy template files
@@ -767,8 +888,8 @@ if (!isRuntimeCommand) {
         // But if it does, warn and skip
         console.warn(`⚠ Warning: aesop.config.json already exists at ${configPath}`);
       } else {
-        // Generate aesop.config.json
-        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr, finalRepoUrlsStr);
+        // Generate aesop.config.json with the determined port
+        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr, finalRepoUrlsStr, dashboardPort);
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
         console.log('✓ Generated aesop.config.json (configured for your repos)');
       }
@@ -782,10 +903,13 @@ if (!isRuntimeCommand) {
       console.log('✓ Copied MEMORY-SEED.md (template for your facts)');
     }
 
-    // Install the pre-push hook
+    // Initialize git repo if needed (BEFORE installing hooks)
+    initializeGitRepo(finalTargetDir, noGitFlag);
+
+    // Install the pre-push hook (only works if .git exists)
     installPrePushHook(finalTargetDir, templateRoot);
 
-    // Install the pre-commit waveguard hook
+    // Install the pre-commit waveguard hook (only works if .git exists)
     installPreCommitWaveguard(finalTargetDir, templateRoot);
 
     console.log(`\n✅ Scaffolded aesop template into "${finalTargetDir}" (${copiedCount} files)`);
@@ -800,35 +924,34 @@ if (!isRuntimeCommand) {
       console.log(`  1. cd ${finalTargetDir}`);
       console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
       console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
-      console.log('\n📖 After that, review:');
-      console.log('  • CLAUDE.md (pre-filled with your project info)');
-      console.log('  • aesop.config.json (pre-configured for your repos)');
-      console.log('  • docs/MEMORY-TEMPLATE.md (edit ~/.claude/MEMORY.md with your facts)');
+      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('  mkdir -p ~/.claude/memory');
+      console.log(`  cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
       process.exit(0);
     } else if (finalProjectName) {
-      console.log('\nHeadless scaffolding complete! Next steps:');
+      console.log('\n✅ Headless scaffolding complete!\n');
+      console.log('🎯 Next 3 commands to get started:\n');
       console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. Review CLAUDE.md (pre-filled with your project info)');
-      console.log('  3. Review aesop.config.json (pre-configured for your repos)');
-      console.log('\nInitialize your brain (Claude Code team memory):');
-      console.log('  4. mkdir -p ~/.claude/memory');
-      console.log(`  5. cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (or review existing ~/.claude/CLAUDE.md)`);
-      console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
-      console.log('\nRun the daemon and dashboard:');
-      console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-      console.log('  8. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:8770)');
+      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
+      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
+      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('  mkdir -p ~/.claude/memory');
+      console.log(`  cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
     } else {
-      console.log('\nConfiguration steps:');
+      console.log('\n✅ Scaffold complete!\n');
+      console.log('🎯 Next 3 commands to get started:\n');
       console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. cp aesop.config.example.json aesop.config.json');
-      console.log('  3. Edit aesop.config.json with your configuration');
-      console.log('\nInitialize your brain (Claude Code team memory):');
-      console.log('  4. mkdir -p ~/.claude/memory');
-      console.log(`  5. cp ${finalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
-      console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
-      console.log('\nRun the daemon and dashboard:');
-      console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-      console.log('  8. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:8770)');
+      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
+      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
+      console.log('\n📖 Configuration steps (optional):\n');
+      console.log('  cp aesop.config.example.json aesop.config.json  (if not generated)');
+      console.log('  Edit aesop.config.json with your configuration');
+      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('  mkdir -p ~/.claude/memory');
+      console.log(`  cp ${finalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
+      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
     }
     console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
     process.exit(0);