How kiln-orca runs Kiln's work through agents in Orca
Reading the source of kiln-orca, Kiln's AI node connector: how it takes tasks from the server, starts Codex or Claude Code inside Orca, requests and revokes a git credential per transfer, and resumes from a journal after a crash.
中文版:kiln-orca 怎么让 Orca 里的 Agent 干 Kiln 的活 · Previous post: How Kiln turns an issue into a release
The previous post covered Kiln's whole automation chain: an issue is developed by an AI, reviewed by another agent, then merged, tagged and released. On the AI side it stopped at "the server hands the task to an AI execution node". This post goes one level down: what happens on that node, how Kiln gets a coding agent inside Orca to do its work, and how it keeps the agent from doing anything else.
I read the kiln-orca/ directory of kilnflow.dev (TypeScript, about 11.5k lines of source) at commit e3bff51. Source and tests only: nothing was installed or run. Orca itself is not open source; I only looked at how the connector calls its command line and at Orca output recorded in the tests. Paths are relative to kiln-orca/src/.
In one sentence: kiln-orca is a resident user service between the Kiln server and Orca. It takes tasks from the server, starts an agent in a one-shot Orca worktree, and writes each step to a local journal so it can carry on after a crash; the agent can only act by asking it through the kiln-orca task command, and git credentials are fetched from the server per transfer and handed back when done.
Who does what
Orca is a desktop app that manages agents' worktrees, terminals and orchestration (runs, dispatches, workers). How Orca divides work inside, and whether it spawns sub-agents, is its own business; Kiln does not care.
kiln-orca runs as a macOS LaunchAgent or a Linux systemd --user service, and one data directory is one node. The token a node enrols with decides whether it is a review node or a development node; a machine with both Codex and Claude Code installed can enrol one of each, each with its own data directory.
The life of one task on a node
1. Startup: check it can work before asking for work
On start, the connector reads its enrolment and private key, takes a single-instance lock, opens a socket at run/kiln-orca.sock in the data directory, then checks each dependency: Orca is open and at least version 1.4.258; Docker and Compose work; the bundled kiln-runner can prepare toolchains; the journal is writable; each agent answers --version; and the kiln-task skill is synced into each agent's skills directory.
This status, plus the protocol version (currently 10), goes to the server with every Acquire. When capacity is full (default max_tasks: 2), local drain is on, Orca is not ready, or the journal or skill has a problem, the node stays connected but declares it takes no new work. An unreadable journal record counts as one slot of capacity, because it may describe an agent still running in Orca that the connector cannot identify.
host/run.ts:132 · core/node.ts:176,473,728 · core/orca.ts:306
2. Prepare: clone, worktree, toolchain, test services
After taking a task, the connector prepares the repository's clone under repos/<repo id>/<name>. It asks the server for a read token (IssueCredential with an op_id), passes it to git as http.<url>.extraHeader through environment variables so it never appears in argv, and calls RevokeCredential as soon as the clone is done. The connector's own git ignores the global and system git config.
It then registers the repository with Orca, writes task files under tasks/<attempt>/ (work.json, candidates.json for development selection, and so on), runs kiln-runner toolchain ensure to prepare Go, Node and pnpm from the repository's .kiln/runtimes.lock, and, if the repository declares test services, brings up Postgres or Redis with docker compose up -d --wait.
core/attempt.ts:459,746 · core/git.ts:171,410 · core/credentials.ts:77 · core/toolchain.ts:167 · core/services.ts:305
3. Start the agent, never twice
Before starting, the connector writes this start's request id to the journal, and only then calls:
orca orchestration worker-start --worktree new-top-level --name kiln-a<attempt>-e<epoch> --base-branch <commit> --comment kiln:attempt=…;epoch=…;task=…;kind=… --agent <agent> --spec <prompt>
Orca creates a new top-level worktree and starts the agent in it. If the call's outcome is unclear (timeout, dropped connection), the connector does not retry; it asks request-show with the same request id whether Orca actually started it. If that cannot be settled, the task ends as infra.lost: failing is better than one task running two agents. The worktree's name and comment carry the attempt and epoch, which is how cleanup later proves "I created this".
core/attempt.ts:864,958 · core/orca.ts:611
4. Tracking: mailbox, heartbeat, timeouts
When the agent finishes it sends a worker_done message. The connector keeps a "mailbox" terminal of its own in Orca running orchestration check --types worker_done,escalation,question and writes each message to a file; if the agent asks a question mid-task, it gets a fixed reply telling it to decide according to its brief.
While a task runs, the connector checks the mailbox every 2 seconds, falls back to worker-show every 30 seconds, and sends the server a heartbeat with the current stage every 5 seconds. The heartbeat reply can carry a cancel request; exceeding the task's time limit, losing the server for 10 minutes, a stale epoch, or the node being revoked all make the connector stop the agent. When the connector itself restarts it simply stops tracking; the agent keeps running in Orca and is picked up again from the journal.
core/mailbox.ts:585 · core/attempt.ts:118-123,1000,1358
5. The agent's only door: kiln-orca task
The agent's brief contains a command of the form node cli.js task --home <data dir> --attempt <id>; its usage is documented in the kiln-task skill, which ships with the package and is synced into the agent's directory by the connector. The command hands each request over the unix socket to the running connector, which calls the server on its behalf.
| Subcommand | What it does | Who validates |
|---|---|---|
info | Basic task information | Local |
check-report | Review: validate report.json before finishing | Server ValidateReport; locally only file type and a 1 MiB cap |
claim | Development: claim the selected issues | Server ValidateReport + ClaimDevIssues |
deliver | Development: submit the delivery report | Server validates the report; locally: clean tree, HEAD contains the delivered commit, design phase Markdown-only |
ci | Latest CI result for a PR or commit | Server GetVerification |
doc | Read the frozen external design docs | Server, authorised from task relations |
exec | Run a command with the managed toolchain; git gets credentials via the connector | See the next section |
done | End the round: validate once more, then send worker_done to Orca from the agent's own process | Connector |
One detail in that last row: worker_done is sent by the agent's process, using the identity Orca set in that session's environment; the connector never impersonates the agent to report completion.
host/socket.ts:295 · core/attempt.ts:1412-1649 · core/done.ts:138
6. task exec: one token per git transfer
task exec -- <command> puts the toolchain first on PATH, points GIT_EXEC_PATH at a mirror directory where git-remote-http(s) is replaced by the connector's wrapper, and configures the connector's credential helper for the task repository's host.
Each time git goes over HTTP(S), the wrapper first checks whether the transfer would carry some other credential: a user or password in the URL, an http.extraHeader effective for that URL, netrc mentioning the host or default, or any of these being unreadable. Any one of them refuses the transfer. Otherwise it opens a read operation with the connector over the socket, and the connector asks the server for a token only if the URL is exactly the task repository or a declared dependency; when the connection closes, the token is revoked.
Write access is used only for delivery: the connector requests a separate write token for its own push of the attempt branch and returns it right after. The agent never gets a write credential.
host/cli.ts:306,365 · core/gitexec.ts:45,109 · core/credentials.ts:246,362 · core/attempt.ts:1468,1490
7. Finishing: confirm the result, then delete things
When the agent finishes, the connector first records the verdict in the journal (stage finishing). For a development task that delivered, it pushes the delivered commit to kiln/attempt-<id> with a write token and confirms with ls-remote; if nothing was delivered, it pushes the current changes to the same branch as a checkpoint, so the next round can continue on a different machine. Then it sends Complete, retrying for up to 30 minutes.
Only after the result is confirmed does cleanup start: stop test services, confirm the agent has stopped and its terminal is released, delete the worktree, checkout and local branch through Orca, verify that Orca, git and the disk no longer have them, and finally delete the journal record. Before deleting, it checks name, comment, path and git registration; anything the connector did not create is left alone. Unfinished reclaim is retried every minute and abandoned after 12 hours with a log entry explaining the manual fix.
core/attempt.ts:1159,1223,1256,1297 · core/git.ts:558 · core/reclaim.ts:185-411
What happens after a crash
This is the core of the design. Before every action that changes something outside the process, the connector records what it is about to do in journal/<attempt>.json: the start request id, the verdict, whether to push, the content of Complete. On restart it reads each record:
- a recorded
Completeis sent again; - a verdict without a confirmed push redoes the push;
- records stuck in
stopping,releasingorreclaimingare retried every minute; - an unreadable record is neither skipped nor deleted: the node stops taking new work and reports the file and the reason in the log,
doctorand the dashboard until a person deals with it.
The tests follow the same idea: about 580 cases using real git, a local git HTTP server, a real unix socket and multi-process lock races, plus many "epoch goes stale / process crashes in the middle of step X" cases.
Problems I found
No high-severity defects. Most of what is worth fixing only matters if "the agent and the connector run as the same user" is treated as a security boundary; Kiln's own docs call these guard rails, not a boundary.
| Problem | Effect | Where |
|---|---|---|
| The socket identifies callers by attempt id alone | With two tasks running, one agent can act as the other: get its credentials, claim issues, read docs. A random per-task secret in the task command would fix it | host/run.ts:202 |
| Fixed 10-minute git timeout on a full clone | On a large repo or slow link the clone times out, the next task starts from zero, and it can fail with infra.fetch indefinitely | core/git.ts:50,412 |
The shared clone's own .git/config and hooks still apply | A proxy or hook left by an earlier development agent affects later tasks' token-carrying git | core/git.ts:183 |
| Journal and state files are not fsynced | After power loss a record can be empty; an empty journal stops the node taking work until someone deletes it | core/journal.ts:215 |
| The clone path is built from the server-supplied repo name with no containment check before deletion | Only reachable if the server is buggy or compromised; the reclaim code already has this check, this path does not | core/attempt.ts:428 |
| A report file over 1 MiB is reported to the agent as "retry later" | The agent may keep retrying until the task times out | core/attempt.ts:1534 |
What is done well is just as clear: every child process is started with an argv array, never shell: true; tokens never appear in argv, the journal or logs, which record only fingerprints; external input is parsed as unknown and then validated, with not one as any in the source; and every external command has a timeout.