# Agent Valley
Give the Chief Director an intent, including an abstract business or product goal. It interprets the situation, looks for opportunities, combines Technical Director, Design Director and Marketing Director advice, and decides a strategy. It mobilizes Actors and installed OMA skills, examines actual outcomes and adjusts its approach. The user receives reports of decisions, reasons, results, lessons and next actions. The Chief owns judgment throughout the work within the original charter, available permissions and saved limits. Actors work in isolated Git worktrees; Linear/GitHub issues also support queued, parallel work.
Orders continue improving by default. Use `av order "Improve usability, reliability and revenue"`. Add `--once` to complete one goal and exit. The Chief selects successive goals using accepted changes, previous reports, measured outcomes and available tools. `av operations` shows progress; Ctrl-C pauses and `av order --resume ID` continues. See [continuous Chief operation](./docs/guides/chief-continuous.md) for limits, cloud/MCP access and recovery.
Optional [container observation](./docs/guides/chief-containers.md) supplies Docker/OrbStack and Kubernetes state, restart/OOM evidence and bounded logs. Changed incidents wake an idle Chief, and configured target health must pass a fresh check before mission completion. Setup can configure the targets without starting a container or contacting a cluster.
> Read this in: [한국어](./README.ko.md)
> **Token usage warning:** AV prioritizes your goal over token savings. Planning, persona consultation, Actor work, independent reviews, repairs, and replanning can consume substantial model usage and incur API charges. AV does not check or manage your subscription's remaining allowance. Reported usage is recorded; optional estimated-cost limits and execution limits still apply.
```
Linear Issue (Todo)
→ Webhook → Orchestrator → Git Worktree → Actor Session
→ Completion → Merge/PR → Done
```
Tracker mode manages lifecycle transitions (Todo → In Progress → Done/Cancelled) and delivers verified changes. Chief Director orders keep a local plan, task reviews, and verification results for a goal.
Built with **TypeScript + Bun**. Supports **Claude Code, Codex, Qwen Code, DeepSeek Harness (DSH), ZCode, Antigravity, Cursor, Grok, Kimi, and OpenCode** through the AgentSession interface.
See the [operability audit](./docs/reports/operability-audit-2026-10-03.md) for tested user journeys, fixes, and remaining limits.
---
## How It Works
1. Create an issue on Linear or GitHub (or `bun av issue "description"`)
2. The tracker sends a webhook to the dashboard
3. Orchestrator verifies HMAC signature, transitions the issue to In Progress
4. DAG scheduler checks dependencies — blocked issues wait until blockers complete
5. WorkspaceManager creates an isolated git worktree under `workspace.root`
6. AgentRunnerService starts the configured actor CLI
7. After verification: merge and push or create a PR, post a tracker summary, transition to Done
8. On failure: exponential backoff retry (60s × 2^n, max 3 attempts), then cancel with error comment
9. Slot refill: completed actors free up capacity, next waiting issue starts automatically
Multiple issues run in parallel up to `actor.max_parallel` (auto-detected from hardware).
---
## Quick Start
For agent-led setup, give a local shell-capable agent [AGENT_SETUP.md](./AGENT_SETUP.md) and the target repository. That user-facing initiating agent becomes the Chief Director, keeps its confirmed current model or saves the native default when the exact model is unknown, prepares AV/OMA/project MCP, and reports readiness without starting a mission. Delegating installation to a worker preserves the initiating session's vendor/model.
```text
/absolute/path/to/repo에 AV를 설치하고 설정해줘.
https://raw.githubusercontent.com/first-fluke/agent-valley/main/AGENT_SETUP.md 를 따라
너 자신을 Chief Director로 지정하고, 실제 완료 항목과 남은 조치를 보고해줘.
AV 설치, OMA 준비, 프로젝트 MCP 설정을 승인한다. 확인용 미션은 실행하지 마.
```
For interactive setup, run the installer from the Git repository you want actors to work on. It prepares Node.js 26.10.0 and Bun 1.4.2 when needed, installs `av`, and opens the setup wizard in an interactive terminal.
```bash
cd /absolute/path/to/repo
curl -fsSL https://raw.githubusercontent.com/first-fluke/agent-valley/main/scripts/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
```
The interactive wizard asks for the target repository and Chief Director CLI and model, and can save a trusted verification command. Agent-led setup passes the initiating agent's own runtime and model choice to `av setup --yes --json`. Setup guides provider preparation and prepares the latest OMA CLI and skills in the target repository. OMA preparation is the default. Browser sign-in and unsupported readiness checks remain concrete pending actions. The repository must have at least one commit. After setup is ready, give AV a goal with `av order "Fix the login failure"`. See the [installation, first-task and recovery guide](./docs/guides/environment-setup.md).
The Chief Director consults its Technical Director, Design Director and Marketing Director concurrently, turns the goal into success criteria and executable checks, creates 4–8 Actors including those advisers, and assigns work using available supported CLIs and installed OMA skills. Up to three independent Actors run in separate worktrees by default; reviewed changes are integrated before dependent work and final verification. Use `--parallel 1` for serial execution. The Technical Director focuses on cost, reuse, standardization and dependencies; the Design Director focuses on usability, user tests, data and retention, including a preference for dark patterns; the Marketing Director focuses on promotion, acquisition, revenue and ROI. The Chief Director reviews evidence and decides whether to repair, reassign, or replan when work fails. Each verified improvement produces a report with a plain-language explanation, checks, and remaining limits. Orders start without a tracker or daemon. `--actor` and `--model` override the saved Chief Director choice for one order; `--actors` supplies your own team. See [Chief Director orders and named actors](./docs/guides/chief-missions.md).
Without `--verify` or a saved command, the Chief Director designs fixed file, JSON, or explicit test checks bound to the original success criteria. A supplied command remains immutable. The foreground supervisor resumes child crashes and scheduled retries within saved limits; `--once --no-supervise` runs a single mission directly and `av missions --watch` restores eligible checkpoints after a stopped supervisor or machine. Worker authentication/environment failures and unavailable required observations return to Chief recovery. A Chief-selected wait resumes the same checkpoint when due. Missing authorization, credentials or trustworthy external-effect evidence remains an unmet prerequisite; uncertain external actions cannot be repeated or marked complete by guessing. Advanced single-mission resume can increase `--runs`, `--duration`, `--rounds`, and the configured-price estimate limit `--cost` without resetting spent budgets. Continuous orders retain the original child settings; their active decision checkpoint supports run, duration and cost adjustments described in the continuous guide. Unknown cost pauses when a cost limit is set; in-flight or subscription charges are not an exact billing cap.
The Chief Director owns execution and recovery decisions and reports actions, evidence and remaining prerequisites. The user retains operational responsibility for the goal and resulting actions. AV does not invent credentials, permissions or successful outcomes when evidence is missing.
Orders also record actual token usage, duration and review outcomes for routing, select different available CLI types for task review, reuse repository organization evidence and enforce configured business metric targets. User-configured Stripe revenue, HTTP JSON, or file sources provide real observations; orders wait for the measurement window and unmet targets remain incomplete. Optional reporting sends actual report, screenshot and video files through replaceable Slack, Discord, Telegram, Teams, Google Chat, Mattermost or webhook adapters. Aside MCP captures the configured browser target; MP4 encoding requires ffmpeg. See [operations and report attachments](./docs/guides/chief-integrations.md).
For issue tracker automation, use an Agent Valley source checkout containing `apps/dashboard`. Run `bun av setup --mode tracker`, then `bun av doctor` and `bun av up --dev` there. Set `workspace.root` to the repository actors should work on.
The CLI attempts automatic Linear webhook registration. For manual registration use `{url}/api/webhook`; GitHub uses `{url}/api/webhook/github`.
The default tunnel provider is ngrok; set `tunnel.provider: cloudflare` in `av.yaml` to use Cloudflare Tunnel (see Configuration below).
---
## CLI
```bash
bun av setup # Local orders: repository, Chief Director, login, OMA, verification
bun av setup --yes --actor codex --model '' --workspace /absolute/path/to/repo --json # Codex initiator, explicit user target
bun av setup --mode tracker # Linear/GitHub automation setup
bun av doctor # Validate configuration and runtime prerequisites
bun av dev # Start in foreground (file watching + auto-restart)
bun av up --dev # Start background daemon without a production build
bun av up # Build dashboard, then start background daemon
bun av down # Stop background daemon
bun av status # Query orchestrator status
bun av top # Live actor status monitor
bun av logs # Tail dashboard logs (-n for line count)
bun av login # Verify and save an opaque AV user team token
bun av logout # Logout from team
bun av invite # Copy team config to clipboard
bun av team --help # Central-server team administration and legacy data import
bun av order --help # Give a Chief Director a goal; --verify supplies an optional trusted command
bun av missions # List saved local Chief Director orders
bun av missions --watch # Resume eligible saved orders and scheduled observations
bun av reports list # Inspect third-party delivery receipts
bun av reports retry # Retry saved report files without running Actors
bun av integrations install # Install AV skills and MCP entries for Codex, Claude Code, Cursor, Qwen, and Antigravity
bun av mcp --workspace /absolute/project # Expose local Chief Director mission tools over stdio
```
To delegate goals from Codex, Claude Code, Cursor, Qwen Code, or Antigravity, install the project `av` skill and MCP server, then restart the client and complete its normal trust step. AV also exports [native plugin packages](./docs/guides/native-plugins.md) and supplies a [web OAuth gateway](./docs/guides/web-mcp.md) for ChatGPT and Claude. See [agent client integration](./docs/guides/agent-clients.md).
### Creating Issues
```bash
bun av issue "fix auth bug" # Create issue (Claude expands description)
bun av issue "fix auth bug" --raw # Create without expansion
bun av issue "fix auth bug" --yes # Skip confirmation
bun av issue "add tests" --parent ACR-10 # Create as sub-issue
bun av issue "migrate db" --blocked-by ACR-5 # Set dependency
bun av issue "refactor auth" --breakdown # Auto-decompose into sub-tasks
```
`--parent`, `--blocked-by`, and `--breakdown` require Linear. GitHub supports plain issue creation and `--scope`; `--raw` works with either tracker without Claude expansion.
---
## Configuration
### Config Files
Two YAML config files, merged at startup (project wins over global):
| File | Scope | Description |
| -------------------------------------- | ------------- | ----------------------------------------------------- |
| `~/.config/agent-valley/settings.yaml` | Global (user) | API key, actor defaults, team dashboard |
| `av.yaml` | Project | Team config, workspace root, prompt template, routing |
Run `av setup` to create both files interactively, or follow [agent-led setup](./AGENT_SETUP.md) for an unattended installation using the initiating agent as Chief Director. See `av.example.yaml` for format reference.
Project configuration uses only `av.yaml`; setup and edits save that file. Configuration uses `actor:`. Actor profiles use `director`, `actors`, and `actorType`; existing profile fields and CLI flags remain aliases.
### Global Config (`~/.config/agent-valley/settings.yaml`)
```yaml
linear:
api_key: lin_api_xxx
actor:
type: claude # Default actor: claude / codex / qwen / dsh / zcode / antigravity / cursor / grok / kimi / opencode
timeout: 3600
max_retries: 3
max_parallel: 3 # Max concurrent actor runs (default: hardware-detected recommendation)
logging:
level: info # debug / info / warn / error
format: json # json / text
server:
port: 9741
# Team Dashboard (optional)
team:
relay_url: https://av.example.com
id: 11111111-1111-4111-8111-111111111111
display_name: my-node
```
Workers receive the gateway URL, team UUID and an AV user token through `av login`.
The central server also configures `team.turso_url` and `team.turso_auth_token_env`
(default `TURSO_AUTH_TOKEN`). The database token stays on the central server or an
explicit administration machine. See [team ledger setup and migration](./docs/guides/team-ledger.md).
### Project Config (`av.yaml`)
```yaml
# Tracker selector (v0.2+). Defaults to `linear` when omitted.
tracker:
kind: linear # linear | github
linear:
team_id: ACR
team_uuid: uuid-xxx
webhook_secret: whsec_xxx
workflow_states:
todo: state-uuid
in_progress: state-uuid
done: state-uuid
cancelled: state-uuid
# comment_relay:
# enabled: false
# ignore_authors: []
# GitHub tracker (v0.2+) — used when tracker.kind = github.
# github:
# token_env: GITHUB_TOKEN
# owner: my-org
# repo: my-repo
# webhook_secret: whsec_xxx
# labels:
# todo: valley:todo
# in_progress: valley:wip
# done: valley:done
# cancelled: valley:cancelled
# comment_relay:
# enabled: false
# ignore_authors: []
workspace:
root: /absolute/path/to/target-repo
delivery:
mode: merge # merge (auto merge+push) or pr (create draft PR)
# pull_request_reviews:
# enabled: false
# webhook_secret: whsec_xxx # Linear tracker only; the GitHub tracker uses github.webhook_secret
# ignore_authors: []
prompt: |
You are working on {{issue.identifier}}: {{issue.title}}.
{{issue.description}}
Path: {{workspace_path}}
# Multi-Repo Routing (optional)
routing:
rules:
- label: "backend"
workspace_root: /path/to/backend
- label: "frontend"
workspace_root: /path/to/frontend
actor_type: codex
delivery_mode: pr
verify_command: "pytest && mypy ." # overrides verify.command below for this route
# Verification Gate (required for code tasks). Runs before delivery and before the
# issue transitions to Done; on failure the actor retries with the captured
# output as context. Set this to commands available in the target repository.
verify:
command: "bun run typecheck && bun run test"
timeout_sec: 600
# Score-Based Routing (optional)
scoring:
model: haiku
routes:
easy: { min: 1, max: 3, actor: antigravity }
medium: { min: 4, max: 7, actor: codex }
hard: { min: 8, max: 10, actor: claude }
# Actor Budget Caps (optional, v0.2+). Omit to disable (default).
# budget:
# per_issue:
# tokens: 2_000_000
# usd: 5.00
# per_day:
# tokens: 20_000_000
# usd: 50.00
# Webhook tunnel (optional, v0.3+). Omit to keep the v0.2 default (ngrok).
# tunnel:
# provider: cloudflare # cloudflare | ngrok | none
# cloudflare:
# mode: quick # quick (random *.trycloudflare.com URL) | named
# # name: av-webhook # required when mode: named
# # hostname: webhook.example.com # UI-only, used when mode: named
# Observability (optional, v0.2+). Both default to off.
# observability:
# otel:
# enabled: false
# endpoint: http://localhost:4318
# service_name: agent-valley
# prometheus:
# enabled: false
# path: /api/metrics
```
**Prompt template variables:** `{{issue.identifier}}`, `{{issue.title}}`, `{{issue.description}}`, `{{workspace_path}}`, `{{attempt.id}}`, `{{retry_count}}`
---
## Architecture
### Monorepo Structure
```
agent-valley/
├── apps/
│ ├── cli/ @agent-valley/cli — Commander CLI (bun av)
│ └── dashboard/ agent-valley-dashboard — Next.js 16 + PixiJS
├── packages/
│ └── core/ @agent-valley/core — Orchestration engine
│ └── src/
│ ├── config/ YAML config loader (settings.yaml + av.yaml)
│ ├── domain/ Pure types: Issue, Workspace, RunAttempt, DAG
│ ├── orchestrator/ State machine, actor runner, retry queue, DAG scheduler
│ ├── sessions/ Ten built-in Actor session adapters
│ ├── tracker/ Linear GraphQL client + webhook HMAC verification
│ ├── workspace/ Git worktree lifecycle + merge/PR
│ └── observability/ Structured JSON/text logger
├── docs/
│ ├── architecture/ LAYERS.md, CONSTRAINTS.md, enforcement/
│ ├── specs/ Symphony 7-component interface specs
│ ├── stacks/ TypeScript, Python, Go guides
│ └── harness/ SAFETY.md, LEGIBILITY.md, ENTROPY.md, FEEDBACK-LOOPS.md
├── scripts/
│ ├── dev.sh Dev environment bootstrap
│ ├── install.sh Harness installer (new + existing projects)
│ └── harness/
│ ├── validate.sh Architecture validation (secrets, layer violations)
│ └── gc.sh Worktree garbage collector
├── AGENTS.md Actor instructions (shared entry point)
├── AGENT_SETUP.md Agent-led installation and readiness procedure
├── CLAUDE.md Claude Code project instructions
└── av.example.yaml Project config template
```
### Clean Architecture Layers
```
Presentation dashboard route handlers (no business logic)
↓
Application Orchestrator (core / lifecycle / router / bus), AgentRunnerService
↓
Domain Issue, Workspace, RunAttempt, DAG, ParsedWebhookEvent (pure types)
+ ports: IssueTracker, WebhookReceiver, WorkspaceGateway, AgentRunnerPort
↓
Infrastructure Linear + GitHub adapters, git operations, actor sessions, observability
```
Dependency arrows point **downward only**. See `docs/architecture/LAYERS.md`.
### Domain Port Layer
Since v0.2 the Application layer talks to the outside world through four
domain ports so adapters can be swapped without touching the orchestrator:
| Port | Purpose | Current adapters |
| ------------------------- | --------------------------------------------------- | ------------------------------------------------ |
| `IssueTracker` | Fetch / update issues, post comments, attach labels | `LinearTrackerAdapter`, `GitHubTrackerAdapter` |
| `WebhookReceiver<TEvent>` | Verify signature + parse to `ParsedWebhookEvent` | `LinearWebhookReceiver`, `GitHubWebhookReceiver` |
| `WorkspaceGateway` | Per-issue worktree lifecycle + delivery | `FileSystemWorkspaceGateway` |
| `AgentRunnerPort` | Spawn actors + expose `RunHandle` for interventions | `SpawnAgentRunnerAdapter` |
### The 7 Symphony Components
| # | Component | Responsibility | Spec |
| --- | --------------------- | ----------------------------------------------------------------------------- | --------------------------------- |
| 1 | **Workflow Loader** | Prompt template rendering + input sanitization | `docs/specs/workflow-loader.md` |
| 2 | **Config Layer** | YAML config loader (settings.yaml + av.yaml) + Zod validation | `docs/specs/config-layer.md` |
| 3 | **Tracker Client** | Linear GraphQL — fetch issues, state transitions, comments, HMAC verification | `docs/specs/tracker-client.md` |
| 4 | **Orchestrator** | Webhook event handler, state machine, retry queue, DAG scheduler | `docs/specs/orchestrator.md` |
| 5 | **Workspace Manager** | Per-issue git worktree creation, merge/PR, cleanup | `docs/specs/workspace-manager.md` |
| 6 | **Actor Runner** | AgentSession abstraction, timeout enforcement, parallel execution | `docs/specs/agent-runner.md` |
| 7 | **Observability** | Structured JSON logs, system metrics, SSE status surface | `docs/specs/observability.md` |
### Actor Session Plugins
| Actor | Config value | Executable |
| ---------------- | ------------- | -------------- |
| Claude Code | `claude` | `claude` |
| Codex | `codex` | `codex` |
| Qwen Code | `qwen` | `qwen` |
| DeepSeek Harness | `dsh` | `dsh` |
| ZCode | `zcode` | `zcode` |
| Antigravity | `antigravity` | `agy` |
| Cursor | `cursor` | `cursor-agent` |
| Grok | `grok` | `grok` |
| Kimi | `kimi` | `kimi` |
| OpenCode | `opencode` | `opencode` |
Qwen, DSH, and ZCode use native one-shot protocols with `abort` support. See [Actor sessions](./docs/guides/actor-sessions.md) for installation, authentication, model selection, and verification limits.
Extensible via `registerSession()` — implement the `AgentSession` interface to add custom actors.
---
## Dashboard
PixiJS-rendered office scene showing real-time actor status:
- **Actor characters** at desks with issue identifier bubbles
- **Office visualization** — desks scale to `actor.max_parallel`, coffee machine, server rack, etc.
- **Operations panel** — dependency blockers, retry reasons and next retry times
- **System metrics** — CPU, memory, uptime
- **SSE real-time events** — instant updates on actor.start, actor.done, actor.failed
- **Team HUD** — multi-node view through the AV gateway and Turso ledger; the browser polls its local relay every five seconds
### API Endpoints
| Endpoint | Method | Description |
| --------------------- | ------ | ---------------------------------------------------------------------------------- |
| `/api/webhook` | POST | Linear webhook receiver (HMAC-SHA256 verified) |
| `/api/webhook/github` | POST | GitHub webhook receiver (HMAC-SHA256 verified) |
| `/api/events` | GET | SSE stream for real-time dashboard updates |
| `/api/status` | GET | JSON orchestrator status snapshot |
| `/api/health` | GET | Health check (503 if the orchestrator is unavailable or stopped) |
| `/api/intervention` | POST | Live actor intervention; local by default, token-authenticated when configured |
| `/api/metrics` | GET | Prometheus-format metrics (enabled via `observability.prometheus.enabled`) |
| `/api/team/ledger` | GET | Replayed team state for the local browser; dashboard status authentication applies |
| `/api/team/session` | GET | Validate an AV team bearer token for `team_id` |
| `/api/team/relay` | GET | Read team events after a sequence cursor using an AV team bearer token |
| `/api/team/relay` | POST | Publish a validated event using an AV team bearer token; enforces node ownership |
---
## Key Features
### GitHub Issues Support (v0.2+)
Alongside Linear, GitHub Issues can drive the orchestrator. Set `tracker.kind: github` in `av.yaml` and configure the GitHub section — the domain `IssueTracker` / `WebhookReceiver` ports swap transparently. Both trackers reuse the same orchestration, retry, and delivery pipeline.
### Comment relay
With `comment_relay.enabled: true` under the active tracker (`github:` or `linear:`), a new comment on an issue whose actor is running reaches that actor as an added instruction. GitHub relays repository owners, members and collaborators and needs the webhook subscribed to **Issue comments**; Linear relays workspace users (members and guests) and needs **Comment** events. Codex receives the comment in the running session; stateless actors such as Claude restart the attempt with it. Agent Valley's own comments (its hidden marker or the `Symphony:` prefix), bots and integrations, outside contributors, `ignore_authors`, edited or deleted comments and pull request comments are not relayed. `ignore_authors` accepts GitHub logins and Linear emails, user ids or names; add the account actors comment with when it is a person's token.
### Pull request review follow-up
PR delivery mode can answer review feedback whichever service tracks the issues. With `delivery.pull_request_reviews.enabled: true`, a submitted review of an open pull request on an Agent Valley branch becomes follow-up work for the issue in the branch name (`feature/ACR-42` → Linear `ACR-42`, `feature/my-org/my-repo#42` → GitHub issue #42). Issues and code can live in different places: Linear issues with GitHub pull requests, or GitHub issues in one repository delivered to another. Point a GitHub webhook on each code repository at `/api/webhook/github` with **Pull request reviews**; on repositories other than the GitHub tracker's, send only that event. With the GitHub tracker the endpoint verifies `github.webhook_secret`, so every webhook uses that secret; with Linear, set `delivery.pull_request_reviews.webhook_secret`. Repository owners, members and collaborators count; approvals, bots, `ignore_authors` (GitHub logins), fork branches and closed pull requests are skipped. The review summary and its inline comments, read through the authenticated `gh` CLI that PR delivery already uses, become the instruction. A running actor receives it like a relayed comment. A delivered (Done) issue is moved back to In Progress and retried with the review as context in its existing worktree, after the retry delay; delivery then pushes to the same pull request.
### Observability (v0.2+)
OpenTelemetry OTLP HTTP traces and Prometheus metrics ship built in but **default to off**. Enable per deployment via the `observability` section in `av.yaml`. When enabled:
- OTel spans are emitted for actor start/done/failed + webhook + DAG events.
- Prometheus metrics are served from `GET /api/metrics` (active actors, retry queue size, completion counts, failure counts, DAG cycle detections).
### Actor Budget Caps (v0.2+)
Per-issue and per-day token / cost caps prevent runaway actors. Budgets are evaluated before each spawn (`BudgetService.checkBeforeSpawn`) — when exceeded, the issue is cancelled with an actionable comment instead of spawning.
### Live Intervention (v0.2+)
Mid-run control from the dashboard via `POST /api/intervention`:
- `pause` / `resume` — Codex native (JSON-RPC)
- `append_prompt` — native on Codex / Antigravity ACP; cancel + respawn on stateless Claude
- `abort` — force-kill the session
Commands flow through `InterventionBus`. Without a configured intervention token, only local requests are accepted. Setting `SYMPHONY_INTERVENTION_TOKEN` requires a matching bearer token or browser session on every request, including local requests. The remote flag is not needed when a token is configured; setting `SYMPHONY_ALLOW_REMOTE_INTERVENTION=1` without a token rejects all requests. See [dashboard access](./docs/guides/environment-setup.md#dashboard-and-webhook-access).
### DAG Dependency Scheduling
Issues with `blocked_by` relations wait until all blockers complete. On blocker completion, the DAG scheduler cascades and dispatches unblocked issues. Cycles are detected and ignored.
### Retry Queue
Failed actor runs are retried with exponential backoff (`60s × 2^(attempt-1)`, max 3 attempts). Workspace creation failures and state transition failures are also retried. Max retries exceeded → issue cancelled with error comment.
### Safety Net
- Detects uncommitted actor work and auto-commits before delivery
- Creates safety-net draft PRs in PR mode
- Graceful shutdown on SIGTERM/SIGINT — stops all running actors
- Hot reload cleanup — previous orchestrator instance stopped before new one starts
### Startup Sync
On boot, the orchestrator fetches all Todo + In Progress issues from the configured tracker and reconciles the DAG cache. Existing in-progress issues resume automatically.
### Durable State
Everything the orchestrator must remember across a restart lives in one SQLite file, `.agent-valley/state.db` inside the workspace root: active attempts, the retry queue, pending finalizations, the DAG cache, budget usage and webhook delivery keys. Each store writes in a transaction, so a crash never leaves a half-written record, and a tracker redelivery after a restart is still rejected. The first boot after upgrading imports the earlier `run-state.json`, `dag-cache.json` and `budget-usage.json` snapshots and renames them `*.migrated`.
---
## Development
```bash
bun run test # Run the Vitest suite
bun run lint # Lint (biome)
bun run lint:fix # Auto-fix lint issues
./scripts/harness/validate.sh # Architecture validation
./scripts/dev.sh # Bootstrap dev environment
./scripts/harness/gc.sh # Garbage-collect stale worktrees
```
### Install Harness into Existing Project
```bash
cd your-existing-project
curl -fsSL https://raw.githubusercontent.com/first-fluke/agent-valley/main/scripts/install.sh | bash
```
### CI/CD
| Workflow | Trigger | Purpose |
| ---------------- | ------------------------- | ---------------------- |
| `ci.yml` | Push/PR to main | `validate.sh` + tests |
| `harness-gc.yml` | Weekly (Sunday 00:00 UTC) | Stale worktree cleanup |
---
## Security
- **HMAC-SHA256** webhook signature verification on all incoming Linear and GitHub events
- **Prompt injection defense** — prompt template in `av.yaml` is trusted, issue body is always sanitized at entry point
- **Least privilege** — actors operate only within their assigned worktree
- **Secret management** — secrets in `av.yaml` and `settings.yaml` (gitignored), pre-commit secret detection
- **Fetch timeout** — 30s timeout on all tracker API calls
- **Intervention access** — local by default. A configured `SYMPHONY_INTERVENTION_TOKEN` requires authentication for local and remote requests. Browser mutations require a matching Origin; a valid bearer token also authorizes API clients. The remote flag without a token rejects all requests.
- **Sandbox execution** — every spawned actor CLI runs inside an OS-level sandbox (`sandbox-exec` on macOS, `bwrap` on Linux); spawns fail closed if no sandbox is available unless `SYMPHONY_ALLOW_UNSANDBOXED=1` is explicitly set
- **Audit logging** — all actor actions logged in structured JSON
Full documentation: `docs/harness/SAFETY.md`
---
## Architecture Constraints
| # | Rule | Rationale |
| --- | -------------------------------------------- | ------------------------------------- |
| 1 | No framework imports in Domain layer | Domain stays pure and testable |
| 2 | No business logic in routers | Presentation delegates to Application |
| 3 | No hardcoded secrets | Config YAML only (gitignored) |
| 4 | Issue body is untrusted | Sanitize at boundary |
| 5 | Max 500 lines per file | Readability |
| 6 | No shared mutable state outside Orchestrator | Single state authority |
| 7 | Error messages must include fix instructions | Agents self-correct from errors |
Full list with examples: `docs/architecture/CONSTRAINTS.md`
---
## For AI Agents
If you are an AI actor reading this repository, see **[AGENTS.md](./AGENTS.md)** for detailed setup instructions, conventions, and implementation guidance.
Claude Code sub-agents are available in `.claude/agents/`:
- `symphony-architect.md` — Architecture decisions, SPEC interpretation
- `symphony-implementer.md` — Feature implementation with preflight checks
- `symphony-reviewer.md` — Code review using PR template framework
---
## Metrics
| Metric | Description |
| ---------------------- | ------------------------------------------------------- |
| **Time to PR** | Issue assigned → PR created |
| **CI pass rate** | PRs that pass CI on the first run |
| **Review time per PR** | Average human reviewer time per PR |
| **Doc freshness** | Days since `AGENTS.md` last updated (flag if > 30 days) |
---
## License
[AGPL-3.0](LICENSE)