BuddingPlanted Tended 10 min read

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

Kiln servertasks · credentials · results
airunner.v2 long-poll
kiln-orcaresident user service
Orca CLI
Orcaworktrees · terminals · orchestration
Orca starts the agent
Codex / Claude Codeworks in a one-shot worktree
↺ the agent reaches back only through kiln-orca task (local unix socket)
The connector does not run the agent itself, and the agent never talks to the server directly: every outbound request goes through the connector.

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

prepareclone · worktree · toolchain · services
request id recorded first
startorca worker-start
agent works
runningwaits for worker_done · 5s heartbeat
agent sends worker_done
finishingpush attempt branch · Complete
result committed
stopping / releasingstop agent · free terminal
both confirmed
reclaimingdelete worktree · journal
These stage names are the values of the stage field in a journal record; the connector writes the journal before each step and resumes from it after a restart.

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.

SubcommandWhat it doesWho validates
infoBasic task informationLocal
check-reportReview: validate report.json before finishingServer ValidateReport; locally only file type and a 1 MiB cap
claimDevelopment: claim the selected issuesServer ValidateReport + ClaimDevIssues
deliverDevelopment: submit the delivery reportServer validates the report; locally: clean tree, HEAD contains the delivered commit, design phase Markdown-only
ciLatest CI result for a PR or commitServer GetVerification
docRead the frozen external design docsServer, authorised from task relations
execRun a command with the managed toolchain; git gets credentials via the connectorSee the next section
doneEnd the round: validate once more, then send worker_done to Orca from the agent's own processConnector

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

Agent's gitrun through task exec
git-remote-https swapped for a wrapper
Transport wrapperchecks for other credentials first
opens a read operation
Connector → servertoken for this one repo
✓ transfer ends, connection closes: revoked at oncenetrc, extraHeader or password in URL found: transfer refused
Neither the agent nor the worktree holds a lasting git credential; every fetch is requested and revoked on its own.

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 Complete is sent again;
  • a verdict without a confirmed push redoes the push;
  • records stuck in stopping, releasing or reclaiming are 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, doctor and 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.

ProblemEffectWhere
The socket identifies callers by attempt id aloneWith 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 ithost/run.ts:202
Fixed 10-minute git timeout on a full cloneOn a large repo or slow link the clone times out, the next task starts from zero, and it can fail with infra.fetch indefinitelycore/git.ts:50,412
The shared clone's own .git/config and hooks still applyA proxy or hook left by an earlier development agent affects later tasks' token-carrying gitcore/git.ts:183
Journal and state files are not fsyncedAfter power loss a record can be empty; an empty journal stops the node taking work until someone deletes itcore/journal.ts:215
The clone path is built from the server-supplied repo name with no containment check before deletionOnly reachable if the server is buggy or compromised; the reclaim code already has this check, this path does notcore/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 outcore/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.