orchestra/progress.md

Orchestra progress

Updated: 2026-07-26

Server implementation checklist

This is the implementation-oriented breakdown of the specification. It is a project checklist, not a replacement for the binding spec.

1. Complete the substrate — baseline complete

   • Done: append-only JSONL event log, replay projection, task schema, optimistic versions, lifecycle events, lease TTL groundwork, CAS artifacts, sortable ULID-like IDs, event payload validation, CAS-reference validation, durable atomic snapshots, corruption errors during replay, fsync-backed event writes, and API event metadata.
   • Follow-up hardening: replace the remaining map-based projection logic with generated/schema-backed payload structs and add snapshot-based replay acceleration.

2. Provider layer — complete

   • Done: Provider/Sink contracts and replay-safe JSONL adapter.
   • Done: append-only JSONL file watcher/ingester with rotation handling and bounded records.
   • Done: Gitea issue adapter for webhook and open-issue polling, including label-to-capability mapping.
   • Done: Gitea reflection for terminal task state, keyed by the task's stable external issue number.
   • Done: constant-time HMAC webhook authentication and injectable HTTP clients for testing.

3. Projects and machine registry — complete

   • Done: typed JSON project, machine, and herdr configuration with duplicate/reference validation.
   • Done: machine-bound herdr registry with per-herdr capabilities, endpoint override, and concurrency configuration.
   • Done: injectable reachability checks plus TCP reachability implementation.
   • Done: hard project machine-affinity resolution; candidates are restricted to configured, reachable herdrs on allowed machines.
   • Done: optional ORCHESTRA_CONFIG startup validation.

4. Router and leases — partial groundwork

   • Done: manual lease/release/complete/block endpoints and lease-expiry release.
   • Remaining:
     • Assignment on TaskCreated
     • Assignment on release/expiry
     • Capability matching
     • Availability and concurrency filtering
     • Importance ordering
     • Retry/backoff and eventual TaskFailed

5. Herdr integration — not started

   • Herdr socket client
   • Protocol-version check
   • Harness adapters for Claude, Codex, and opencode
   • Bootstrap prompts
   • Native occupancy measurement
   • Stop-hook/turn-boundary rotation
   • Worktree and anchor validation
   • Split-then-close rotation flow

6. Continuity — not started

   • Handoff schema and validator
   • CAS-backed handoffs/reports
   • Immutable TASK.md handling
   • Scratch-branch pickup contract
   • Shared Markdown change notifications

7. Authorization and surfaces — minimal groundwork only

   • Done: a basic notify-only guard for Telegram/ntfy-style requests.
   • Remaining:
     • Real bus-level authorization
     • TUI/web control surface
     • Telegram/ntfy read-only subscribers
     • Approval request/grant/deny flow
     • MCP gated writes
     • Maven gated control

8. Projections and operations — not started

   • Quota projection
   • Nightly/morning brief
   • Git sync state
   • Standup advisory events
   • Logging, metrics, service packaging, and deployment configuration

Completed

• Built the first Go server slice from orchestra-spec (1).md.
• Added append-only JSONL events and replay projection in internal/store.
• Added task creation, external-key deduplication, optimistic versions, lifecycle states, and SHA-256 CAS artifacts.
• Added HTTP endpoints on default port 9145: health, task ingest/list, and event cursor reads.
• Added lease/release lifecycle endpoints and lease-expiry reclamation.
• Finished the item 1 provider port: provider.Provider/Sink interfaces and a replay-safe JSONL adapter.
• Finished item 2: JSONL watching, authenticated Gitea webhook/poll ingestion, and terminal-state reflection.
• Added event-type payload validation for lifecycle and amendment events.
• Unit tests pass with go test ./....

Current API additions

• POST /v1/tasks/{id}/lease with {"harness_id":"...","ttl_seconds":1800}
• POST /v1/tasks/{id}/release
• POST /v1/tasks/{id}/complete
• POST /v1/tasks/{id}/block

Item 3 status

Item 3 (projects and machine registry) is implemented in internal/registry. Static JSON configuration is loaded and validated, projects resolve only to their explicitly configured machines, and candidate herdrs are filtered by registration and injected reachability. Set ORCHESTRA_CONFIG to validate a configuration file at server startup.

Item 2 status

Item 2 (provider layer) is implemented. internal/provider now includes JSONLWatcher, Gitea.Poll, Gitea.WebhookHandler, Gitea.IngestWebhook, and Gitea.ReflectTask. Gitea ingestion remains idempotent through the store's (source, external_id) key. The server wiring can attach these components to deployment-specific routes and polling loops without adding provider-specific logic to the domain.

Item 1 status

Item 1 (task schema + provider port + JSONL adapter) is implemented as the baseline slice. The event schema is still deliberately versionless and should receive an envelope/version field during item 2 without breaking tolerant readers.

Important limitations

• This is still a Layer 1 prototype. No router, project/machine/herdr registries, harness adapters, herdr socket integration, rotation, handoff validation, provider interface, Gitea adapter, approvals, TUI/web, quota projection, or morning brief exists yet.
• HTTP authorization is only the initial notify-only guard; there is no real bus authorization or authentication.
• Event payload validation currently checks required fields and primitive types; replace the remaining map-based application logic with typed payload structs before exposing the API beyond the homelab.
• Lease expiry currently releases tasks but does not yet implement retry counts/backoff or emit TaskFailed after a configured limit.

Next agent: recommended order

1. Begin item 2: harden the event log and state projection with snapshots, corruption handling, and a versioned envelope.
2. Add project, machine, and herdr registries from static TOML/JSON config.
3. Implement router selection: project affinity, reachability, capability, availability, and importance ordering.
4. Add retry policy and a background lease-expiry loop.
5. Implement handoff/report schemas and CAS reference validation.
6. Integrate herdr only after the substrate/router tests are stable.