Skip to content

feat: the dispatch coordinator runs as Claude Code through boat exec - #61

Merged
OmarAlex24 merged 1 commit into
dispatch/docsfrom
dispatch/boat-exec
Nov 17, 2026
Merged

OmarAlex24 merged 1 commit into
dispatch/docsfrom
dispatch/boat-exec

Conversation

@OmarAlex24

@OmarAlex24 OmarAlex24 commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Fifth layer of the kontext dispatch stack. Real Boat answers boat prompt with provider_not_configured unless an AI provider is connected on its Agents page, and the owner will not connect one. With that answer the stack still printed "coordinator prompted", exited 0 and left the sandbox billing until its time limit. In this PR the coordinator is headless Claude Code running inside the sandbox. Each turn is one boat exec --detach process, followed with boat exec --status. Nothing on the owner's machine holds a turn open any more.

What changed and why

  • The agent's credential (src/dispatch/credential.rs):

    • kontext dispatch credential set reads it from stdin, or from a hidden prompt on a TTY, and never from an argument. credential rm removes it. dispatch status says only whether it is set and which kind it is.
    • It lives in <config>/dispatch/.agent-credential, mode 0600. A project's name cannot start with a dot, so this name never collides with a project's folder.
    • sk-ant-oat… goes to the agent as CLAUDE_CODE_OAUTH_TOKEN and sk-ant-api… as ANTHROPIC_API_KEY. Anything else is refused at set.
    • Without a credential, dispatch refuses with exit 2 and one line that says how to set it. It also refuses any [dispatch] provider other than claude.
  • The credential reaches the sandbox only as a file, like the kontext token:

    • The start script sets it to 0600 at once, then moves it to /dev/shm (or to a 0600 file in ~/.kontext-dispatch/ when there is no /dev/shm).
    • Every clean-up does these steps in order: end the running turn (boat exec --kill), remove the credential (boat exec -- sh -c 'rm -f …'), stop the sandbox, revoke the token. If the rm fails, it says so and still stops the sandbox.
    • A clean-up never runs boat exec into a sandbox the state records as stopped. A turn whose start was already on its way when the run was stopped can still reach it; fix: dispatch's second review — no sandbox without an id, no turn deciding nothing, a way out of a clean-up that cannot finish #63 ends that turn and stops the sandbox again, and real Boat refuses boat exec on a stopped sandbox (409 machine_not_running).
  • The runner (~/.kontext-dispatch-turn.sh, sent with --file):

    • start <n> <uuid> runs claude -p in the repo's clone with --output-format json, --dangerously-skip-permissions, the model, and --session-id on turn 1 or --resume after.
    • The credential goes only into the environment of the one claude process.
    • It leaves result.json, stderr and exit in ~/.kontext-dispatch/turn-<n>/, and refuses to start the same turn twice (exit 90).
    • read <n> prints a short summary for one synchronous boat exec.
    • The prompts go as files too, so no command line carries prompt text or a secret.
  • Following a turn (src/dispatch/turn.rs, rewritten): the state keeps the session uuid and the turn's pid. turn::state asks --status <pid> and gets one of five answers:

    • running;
    • exited, and Claude Code said is_error: false: the turn ended, and the ledger decides as before;
    • exited with is_error: true, a non-zero exit, or no result it can read: the turn failed, and the run is stuck at once with the reason;
    • known: false or lost: the turn cannot be followed; the watcher says so once and leaves the decision to the ledger and the time limit;
    • the CLI could not be asked, or the read was cut or timed out: ask again on the next tick.

    Failure reasons have anything shaped like sk-ant-… redacted.

  • dispatch fails when the coordinator did not start: after starting turn 1 it watches it for 15 s. A turn that fails in that time fails the dispatch with its reason, everything is cleaned up, and the exit is non-zero. It never prints "coordinator started" for such a turn.

  • The start script also:

    • clones the code repo from [[repos]]' remote (as https, with the sandbox's GitHub login) when $REPO_DIR/.git has not appeared after 30 s;
    • sets a git author in the clone when there is none (<login> and <id>+<login>@users.noreply.github.com, from gh api user);
    • downloads install.sh to a file and checks both the download and kontext --version afterwards, so a failed install stops at once (review finding 11).
  • Provider trait: prompt is replaced by exec, detach, process and kill. Boat implements them with the shapes boat exec printed in the probe, which are pinned in a unit test.

  • Removed: the local turn-holding process, its lock, exit and started files, and the hidden dispatch turn command. With them go review findings 1 and 8.

  • The fake boat (tests/fixtures/fake-boat.sh) implements exec sync, --detach, --status and --kill with the captured shapes, and can be told to fail or lose each of them.

Departures from the brief

  • The runner goes with --file; the start script does not write it. Both were allowed. Sending it as a file keeps the start script shorter and lets a test run the exact runner.
  • The runner refuses a second start of the same turn number (exit 90, via an atomic mkdir). A dispatch killed between --detach and saving the pid then cannot lead to two coordinators. PR B uses this.
  • The start script does not check claude on the login PATH. Doing that would mean running bash -l in the tests, which can reach a real claude on a Mac. Instead the runner reports "claude is not on the PATH" (exit 127), and the 15 s check turns that into a failed dispatch.
  • The 30 s wait for the service's clone before cloning is my reading of "a short wait".

Not verified (no boat command but --help was run)

  • That bash -lc 'exec sh "$HOME/.kontext-dispatch-turn.sh" …' keeps the pid Boat reports, and that --kill reaches claude through sh.
  • That boat exec runs a synchronous command from the home folder, so $HOME-based paths resolve.
  • That a sandbox's /dev/shm exists and is writable for user.
  • That git clone https://github.com/… works through the sandbox's credential helper, and that gh api user --jq .id answers.
  • Whether boat exec --kill on a process that already ended exits non-zero. Clean-up asks --status first and only kills a running process.

Test plan

  • cargo fmt --check and cargo clippy --all-targets -- -D warnings: clean
  • Full cargo test with KONTEXT_REQUIRE_SERVER_TESTS=1: 507 tests passed, 0 failed
  • tests/dispatch.rs, 17 tests against the fake boat and the local server, covering:
    • the credential: set from stdin, refused when it is something else, 0600, never printed, not in the kontext-home;
    • the refusals: no credential, a provider other than claude;
    • both secrets travel only as files: not in calls.log, the output, the state or the -e values; no prompt text in a command line;
    • the detach command's exact shape, and the session id and pid saved in the state;
    • a "Not logged in" first turn, and a runner exiting 127: each fails the dispatch, removes the credential before the stop, and revokes the token;
    • stop order kill → rm → stop; a failed rm still stops the sandbox;
    • a redispatch starts the new sandbox's own turn 1 (finding 1);
    • resume once with --resume <same uuid>, then stuck;
    • a failed turn is stuck at once with its reason in the pm's question;
    • lost and unanswerable turns decide nothing and are logged once;
    • the watcher, restarted past the time limit, marks the run stuck.
  • The start script and the runner, run here with a cleared environment and fakes of claude, gh and curl:
    • the credential moves to the memory dir, or to a 0600 file without one;
    • the repo is cloned from a local bare remote, and git's author comes from gh;
    • a turn gets the credential in its environment only and the right flags;
    • a second start is refused; resume, not logged in and missing credential each behave as above;
    • no secret is left in the sandbox's home;
    • a failed download and an install that installs nothing each stop the script within seconds (finding 11).

🤖 Generated with Claude Code

boat prompt needs an agent connected on Boat's Agents page, which the
owner will not do. The coordinator is now headless Claude Code inside the
sandbox: one detached process per turn (boat exec --detach), followed by
its pid with boat exec --status, so nothing on the owner's machine holds a
turn open.

- kontext dispatch credential set|rm: the agent's credential on this
  machine (<config>/dispatch/.agent-credential, 0600), read from stdin or a
  hidden prompt; dispatch refuses without it; status says only whether it
  is set.
- The credential reaches the sandbox only as a file; the start script sets
  it 0600 at once and moves it to /dev/shm (else a 0600 file in the home);
  every clean-up ends the turn, removes it and then stops the sandbox.
- A runner script runs claude -p with --session-id/--resume, every
  permission and --output-format json, refuses a second start of a turn,
  and leaves the result for boat exec to read.
- dispatch fails, and cleans up, when the first turn fails within 15 s.
- The start script clones the repo when the service did not, gives git an
  author from the sandbox's GitHub login, and stops at once when installing
  kontext fails (review finding 11).
- The turn files, their lock and the hidden dispatch turn command are gone
  (review findings 1 and 8).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@OmarAlex24
OmarAlex24 added this pull request to stack #59 November 17, 2026 00:18
@OmarAlex24
OmarAlex24 marked this pull request as ready for review November 17, 2026 14:30
@OmarAlex24
OmarAlex24 merged commit 27b7d92 into main Nov 17, 2026
1 check passed
@OmarAlex24 OmarAlex24 mentioned this pull request Nov 17, 2026
4 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant