Skip to content

fix: kontext dispatch review findings, and the docs for boat exec - #62

Merged
OmarAlex24 merged 3 commits into
dispatch/boat-execfrom
dispatch/review-fixes
Nov 17, 2026
Merged

OmarAlex24 merged 3 commits into
dispatch/boat-execfrom
dispatch/review-fixes

Conversation

@OmarAlex24

@OmarAlex24 OmarAlex24 commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Stacked on #61 (dispatch/boat-exec). It fixes the review findings on the dispatch stack that #61 does not already fix, and updates the docs for the boat exec flow. Each fix has a test that fails on #61's head (1e089c6) and passes here.

What changes

A dispatch killed at any step leaves nothing running unwatched and no secret on disk (findings 2, 3, 7)

  • dispatch starts the watcher right after the reservation, not at the end. It holds a per-epic lock (dispatching-<epic>.lock) while it works.
  • When a starting run's lock is free, the watcher takes it over:
    • setup done: it starts turn 1;
    • nothing was made: it ends the run and frees the epic;
    • setup failed or past its limit: the run is stuck;
    • the sandbox has not shown up after 2 minutes: the run is stuck.
  • A sandbox made by a new that was killed midway is found by its name (boat list --filter rp --json).
  • The local secret files sit in the dispatch folder's tmp/, mode 0600, named with the pid (src/dispatch/guard.rs).
    • A SIGINT/SIGTERM handler unlinks them.
    • The next dispatch, stop or watcher sweeps the files of dead pids.
  • The run stays starting until the turn's pid is saved with running. The runner refuses to start a turn twice (exit 90), and whoever started the second one adopts the first process, so a kill between detach and save never runs two coordinators.

A stop, or a close in the ledger, during the setup wait holds (finding 4)

  • Each run has a random id. Every write from dispatch goes through update_own, which writes only while the run still has that id and is live.
  • When the run changed underneath it, dispatch cleans up what it made and stops with "epic X was {state} while dispatch was starting it".

A run that was not cleaned up keeps its epic, its cap slot and the watcher (findings 5, 6)

  • A run that still bills (billing()) blocks a redispatch of its epic and counts toward max_sandboxes. The refusal says kontext dispatch stop X tries again.
  • The watcher leaves only when every run is settled.
  • It retries failed clean-ups with a backoff: 5 s, doubling, up to 5 min.
  • A clean-up lease (cleaning_until, 6 min) keeps stop and the watcher from cleaning up the same run at once.

A deadline on a stale ledger does not mark the epic stuck (finding 9)

  • When the pull is failing, a run past its time limit goes overdue. Its sandbox is still ended, because it bills.
  • The verdict waits for a fresh pull, which may say the epic closed. After 30 minutes of failing pulls the run is stuck.

boat calls have time limits, and runs are independent (finding 10)

  • Every boat call is killed past its limit: new 15 min, stop 5 min, the rest 2 min (KONTEXT_BOAT_TIMEOUT_MS in the tests).
  • No boat call runs under the state lock anymore. The watcher claims the run under the lock, cleans up outside it, then merges what it did.
  • A failure in one run is logged and does not stop the others.
  • A failing ledger write (the pm's question) no longer stops the clean-up. It is retried (pm_pending, end_pending).

Stuck questions stay separate (finding 12)

  • Each stuck run asks a new question naming its own sandbox, with no_merge.

Small ones (finding 13)

  • With --json, a failed dispatch prints {"error", "run"} on stdout, redacted.
  • The test harness's World::drop now kills a pid only when it is still this test's watcher: it checks the lock and the command line.

Docs:

  • DESIGN §12.5 is rewritten, along with the command row and the [dispatch] example (model claude-opus-5-5, provider claude only).
  • The README section is rewritten. It now has the claude setup-token → kontext dispatch credential set step and a note on what the coordinator can do.
  • kontext-orchestrate and kontext-pm are updated, with their new hashes in templates/skill-versions.txt.
  • The dispatch help is updated.
  • They say:
    • nothing is connected on Boat's Agents page;
    • the credential is set once on the owner's machine;
    • the coordinator runs with every permission inside its sandbox and with the owner's GitHub login;
    • the start script clones the repo.

Findings and tests

# Fixed in Test
1 #61: turns are processes keyed by the run's session, and turns/ is gone stop_ends_the_turn_removes_the_credential_stops_and_revokes (redispatch: a new turn 1 on the new sandbox)
2 here a_dispatch_killed_during_the_setup_wait_is_finished_by_the_watcher
3 here a_dispatch_killed_during_boat_new_leaves_no_secret_and_its_sandbox_is_found, a_dispatch_killed_before_boat_new_is_ended_and_its_token_revoked
4 here a_stop_during_the_setup_wait_holds, an_epic_that_closes_during_the_setup_wait_stays_closed
5, 6 here a_run_not_cleaned_up_holds_its_epic_and_the_watcher_stays
7 here an_empty_starting_run_is_ended_by_the_watcher, a_dispatch_killed_before_it_made_anything_frees_the_epic
8 #61: the turn runs in the sandbox, so a sleeping Mac loses nothing, and a restarted watcher follows it by pid a_restarted_watcher_picks_up_and_the_time_limit_marks_it_stuck
9 here a_time_limit_on_a_stale_ledger_waits_for_a_fresh_pull
10 here a_hung_boat_call_blocks_nothing_and_times_out, one_broken_run_does_not_stop_the_others, a_stuck_sandbox_stops_even_when_the_pm_cannot_be_asked
11 #61 a_failed_install_stops_the_start_script_at_once
12 here a_new_stuck_question_does_not_merge_into_an_old_one
13 here a_failed_dispatch_with_json_says_why_on_stdout; the World::drop change is in the harness itself and has no test of its own

Also added: a_dispatch_killed_after_starting_the_turn_does_not_run_two_coordinators, a guard for a window this PR opens (the run now stays starting until the turn's pid is saved), not a review finding; and a_closed_epic_is_refused, a gap the review listed. It already passed on #61.

On how the tests were shown red: I ran this branch's tests/dispatch.rs against #61's code. 15 of these tests failed there. Three of them (…before_it_made_anything…, …before_boat_new…, …after_starting_the_turn…) fail on #61 only because their pause hook (KONTEXT_DISPATCH_TEST_PAUSE) does not exist there; the findings they touch each have a hook-free red test too (3: the hang-new one; 7: the empty-run one). an_empty_starting_run_is_ended_by_the_watcher covers finding 7 without the hook, and it is red on #61.

Departures and choices

  • Clean-up lease and pending writes. These are new state fields on a run: id, pm_pending, end_pending and cleaning_until, all serde-default, so an older state.json still reads.
  • overdue is a new run state, as above.
  • boat list --filter rp --json is parsed loosely: any object with a matching name and an id, at any depth. I did not capture its real shape (I run no boat command beyond --help).
  • The 2-minute grace for a sandbox that has not shown up and the time limits per call are my picks. They are not measured.
  • An interrupted dispatch that the watcher ends also asks the pm a stuck question, so the pm knows the epic is free again.
  • The run's start journal entry is non-fatal: when it cannot be written, there is a warning and the sandbox runs.

Not verified without real Boat

  • That boat exec --detach's pid stays Claude Code's through bash -lc exec sh …, and that --kill reaches claude.
  • exec's working directory and HOME.
  • That /dev/shm is writable.
  • git clone and gh api user --jq .login/.id with the environment's login.
  • --kill on a process that already exited.
  • The output of boat list --json and its --filter groups.
  • Whether the time limits suit real calls.

Test plan

  • cargo fmt --check
  • cargo clippy --all-targets -- -D warnings (fresh target dir)
  • KONTEXT_REQUIRE_SERVER_TESTS=1 cargo test, full suite, fresh target dir: 525 passed, 0 failed
  • This branch's tests/dispatch.rs against feat: the dispatch coordinator runs as Claude Code through boat exec #61's code: the new tests fail as described above
  • templates/skill-versions.txt matches the changed skills (the install test)

🤖 Generated with Claude Code

OmarAlex24 and others added 2 commits November 16, 2026 18:46
…eaves a sandbox billing

- The watcher starts at the reservation and finishes or ends a starting
  run whose dispatch died (a per-epic lock says so); a sandbox made by a
  killed `new` is found by its name; the local secret files are swept
  and removed on SIGINT/SIGTERM.
- Each run has an id: a dispatch writes only while its run is unchanged
  and live, so a stop or a close during the setup wait holds.
- A run not cleaned up holds its epic and its cap slot, the watcher
  stays and retries with a backoff, and a clean-up lease keeps two from
  cleaning up the same run.
- A time limit on a stale ledger is `overdue`, not stuck, until a fresh
  pull; every boat call has a time limit and runs outside the state
  lock; one broken run no longer stops the others.
- Stuck questions never merge; `--json` prints why a dispatch failed;
  the tests' World::drop kills only its own watcher.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ner's credential

DESIGN §12.5, the README, kontext-orchestrate and kontext-pm (with
their hashes) and the dispatch help: no agent connected in Boat, the
credential set once with `claude setup-token`, every permission inside
the sandbox and the owner's GitHub login, the repo cloned by the start
script, the overdue state, leases and retries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@OmarAlex24
OmarAlex24 added this pull request to stack #59 November 17, 2026 00:46
…ode does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@OmarAlex24 OmarAlex24 changed the title fix: kontext dispatch review findings 2–13, and the docs for boat exec fix: kontext dispatch review findings, and the docs for boat exec Nov 17, 2026
@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
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