Orca: coordinate coding agents without losing track of their work
Build a read-only Orca task ledger
Create a learning tool that records host, worktree and acceptance evidence without automating merges or deleting unfinished work.
What you will learn
- Record identity before progress
- Handle incomplete observations
- Test the learning outcome
Before you start
- Basic command-line and configuration reading
- Ability to work in a disposable authorized environment
Create a learning tool that records host, worktree and acceptance evidence without automating merges or deleting unfinished work.
Key takeaways
- Host identity belongs with the path.
- Acceptance needs evidence beyond agent status.
- The first ledger should remain read only.
Record identity before progress
Give each synthetic task an identifier and record its host, worktree path, branch and expected output. A path alone is ambiguous when local and remote machines use similar directory names.
Keep agent-reported completion separate from human acceptance. Attach a sanitized diff reference and check result before marking the task accepted. This teaches why a green agent status is not the same as integrated code.
Handle incomplete observations
Represent disconnected, awaiting review and unknown states explicitly. A lost connection should not turn into either success or automatic failure of the underlying code change. Preserve the last observation time.
Use read-only Git inspection or synthetic fixtures in the first version. Do not let the ledger merge branches, remove worktrees or restart remote runtimes. Each of those actions requires additional authority and recovery design.
Test the learning outcome
Cover two hosts with identical paths, an uncommitted diff, failed checks and a disconnected session. Acceptance requires that the interface identify the exact work and explain what evidence is still missing.
A task table and small host/worktree graph are sufficient. This is our independent exercise, not a claim that Orca ships the proposed schema or a future promise from its maintainers.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Record host, worktree and expected output.
- 2
Separate agent completion from accepted work.
- 3
Test ambiguous paths and missing observations.
Copy-ready example
{
"proposal": true,
"readOnly": true,
"host": "demo-host",
"worktree": "demo-path",
"agentComplete": false,
"humanAccepted": false,
"lastObservedAt": null
}Frequently asked questions
Can the ledger merge automatically?
That is outside this read-only exercise.
Is this schema part of Orca?
No. It is a proposed independent learning format.
Sources
- Orca / README.mdSource checked 2026-09-18
- Orca / docs/reference/headless-linux-server.mdSource checked 2026-09-18