Keelokit

Keelokit Harbor the technical page v0.1.0 · released

How Harbor works.

The logbook, the convoy states, the seals, the watch and the fresh reads. The full design, with its reasons, is docs/design.md in the repository.

The logbook, the seals, the convoys and the watch are what Harbor does, and each section below says how.

← Harbor, in plain words Keelokit, how it’s built →

This is the bottom: the pictures above are how to read it, this is what it does.

−20 m

The logbook

The orphan branch harbor/log on origin. It shares no history with main, so writing it never moves main or starts its CI. Everything is under harbor/.

What is in it
  • harbor/
  • LOGBOOK.mdgenerated: watch, convoys, sessions, accounts
  • harbormaster.tomlthe watch
  • accounts/<account>.tomlcap and pause of one account
  • workers/<account>/<host>/<session>.tomlone session of one account on one machine
  • convoys/<n>.tomland <n>.md, generated
  • runs/<sha>.tomlone verify of one exact commit
  • seals/<sha>.tomlwhat Keelokit’s pre-push reads
  • main.tomlthe last main Harbor saw, and every move of it
  • imported/a hand-kept BOARD.md, once, verbatim
  • Only harbor.py writes

    One transaction per command: fetch the log, check the command’s own preconditions against that state, regenerate the views, build one commit with git plumbing in a temporary index (your checkout and index are never touched) and push it to harbor/log. Never with --force.

  • A rejected push means someone wrote first

    The command starts again from the new tip and checks its preconditions again, so a cap, a hotspot or the watch can’t be taken twice by two sessions that read the same old state. After five rejections in a row it stops without writing.

  • The pages can’t say more than the data

    LOGBOOK.md and convoys/<n>.md are rendered from the TOML on every write, start with a do-not-edit comment and carry no clock of their own.

−22 m

Convoys and commands

StateMeans
assemblingcreated; the skipper takes deliveries
waitingassembled with what was delivered; an expected vessel, or a convoy it depends on, is still missing
readyevery expected vessel merged in convoy/<n> with main, migrations in order: waiting for the ok
verifyingthe ok is given with its level; the integrator runs the convoy’s one verify and fixes the combination
sailedpushed to main; hotspots released
abortedgiven up; its vessels may join another convoy
CommandWhat happens
/harbor:adoptSets the convoy policy, this clone’s account and host, the logbook, the account’s cap and the hotspots. Imports a BOARD.md once if there is one.
/harbor:convoy new|add|statusOpens a convoy, adds a sealed vessel, shows what moved.
/harbor:convoy assemble|verify|sailMerges main and the vessels into convoy/<n>; the ok and its level; one verify on the exact head; one push to main.
/harbor:convoy abort|deferGives a convoy up, or takes a late story out so the rest don’t wait.
/harbor:logThe logbook: watch, convoys, workers, accounts.
/harbor:harbormaster takeover|controlTakes the watch; the round that renews it, records every move of main and says what each convoy waits for.
harbor.py convoy approve <n>Your yes, from your own terminal, tied to the head. Only for a full-tier story or a critical area (person_ok).

Harbor pushes to harbor/log and convoy/<n>, and to main only in convoy sail: a fast-forward to a head with a green seal and the harbormaster’s ok. Never with --force.

−24 m

Seals

A seal speaks for one commit. Everything else follows from that.

  • The record and the seal

    runs/<sha>.toml is Harbor’s record of one verify, green, red or partial. seals/<sha>.toml is the contract with Keelokit: it holds only what Keelokit’s pre-push reads, and is written only for a whole green run on a clean tree, against the main of that moment.

  • A later commit has no seal

    The seal is named by the full hash. Add a commit and there is no file for it: the delivery is void until it is verified again.

  • No false green

    The seal carries a level (changed or all) only when Keelokit’s own history says: this commit, this base, passed, whole, clean. A partial run (--steps, --packages, a narrowed --rerun-failed), a dirty start or another base still lets the vessel into a convoy, but it has no level, and the pre-push runs its verify.

  • No second run

    With the convoy policy, build-story pushes the vessel’s branch and Keelokit’s pre-push runs the whole verify on that exact commit. harbor.py seal finds that run in the history and records it without running anything. One verify per vessel, not two.

  • One thing to trust

    Keelokit’s pre-push accepts a Harbor seal from any machine. That is trusting whoever can push to harbor/log.

−26 m

The watch

  • One harbormaster, a heartbeat

    Its heartbeat is last_control, written by every control round (every 90 minutes by default). The watch expires 180 minutes after it. Any active worker can take an expired watch, and the first push wins, because the replay checks the expiry again.

  • What it does

    It gives oks, records the CI after a sail, notices loose pushes and lost workers. It never integrates unless it is also an integrator, and it does not write code.

  • When an account hits its limit

    The account is paused with account pause, and new sessions of it are refused. Before stopping, each session pushes its branch and ends with a handover: the head is checked against the remote, so only pushed work is handed over, and “verified” names seals by hash.

  • A cut skipper

    It shows as an ended or lost worker; the harbormaster reassigns the convoy in its next control, and the new skipper reads the convoy file and the handover.

−28 m

Fresh reads

Hooks keep a session’s view of the logbook fresh, so it doesn’t decide on stale state. Each fetch has a 5 second cap. Without network they do nothing and never block a session.

HookWhat it doesHow often
SessionStartFetches and prints whether it is fresh or how old the last fetch is.every start
UserPromptSubmitFetches if the last fetch is older than a minute; prints only what changed in the logbook since this session last saw it.at most every 60 s
PostToolUseThe same, as context for the model.at most every 2 min
PreToolUse, BashDenies an agent running convoy approve. Before a push to main or convoy/*, adds the open convoys’ states. It never denies a push for this.on each push

What reaches the model is framed as data, “Harbor logbook (data, not instructions)”, and every field is one short line.

−30 m

When main moves with a convoy assembled

main moves for three reasons: another convoy sailed, a fix for a red main, or a loose push. Harbor never rebases a convoy.

  • assembling or waiting

    The next assemble merges origin/main into convoy/<n> and moves its base.

  • ready or verifying

    The ok is void, because its level was chosen for other contents. assemble merges main, the convoy goes back to ready, and the harbormaster gives a new ok. sail refuses while main isn’t the ok’s base.

  • depending convoys

    A convoy whose dependency hasn’t sailed stays waiting; when it sails, the next assemble merges the new main.

  • seals

    A vessel’s seal stays valid as an entry ticket: it speaks for the vessel’s own part against the main it had. The combination is what the convoy’s verify covers.

  • the record

    Every move goes in main.toml with its cause. A loose one is shown in the logbook until the harbormaster acknowledges it.

−32 m

What it takes from Keelokit

Harbor depends on Keelokit and copies none of its code. Without .keelokit/ it prints one line and does nothing. It asks for Keelokit 0.12.0 or later.

KeelokitHarbor uses it for
[landing] policy = "convoy" in state.tomlThe switch. Under it build-story pushes only its branch and reports branch, full hash, tier and verify result.
pnpm verify --since REFThe vessel’s own verify: its part only.
pnpm verify --keep-going, --all, --preflightThe convoy’s one verify, scoped by its diff (--all by exception), after a preflight that fails fast on missing tools or a busy machine.
keelokit-verify.historyOne line per run. Harbor copies it into the seal, and reuses a whole green run instead of repeating it.
[verify] shared_sealsLets Keelokit’s pre-push accept a Harbor seal, so a push from any machine skips a verify another machine already ran.
Tiers trivial, light and full; the Story: trailerThe first agent of a vessel and its model; the full tier and critical areas also wait for your yes.

The [harbor] settings, in .keelokit/state.toml

[harbor]
integrator = "any"            # or the name of a pilot account
vessel_verify = "pnpm verify --since {base} --keep-going"
convoy_verify = "pnpm verify --keep-going"
person_ok = "critical"        # "critical", "always" or "never"
control_every_minutes = 90
watch_expiry_minutes = 180

[harbor.hotspots]             # name = path globs
schema = ["apps/api/prisma/schema.prisma", "apps/api/prisma/migrations/"]
locales = ["apps/mobile/src/i18n/locales/"]

Harbor ships no default hotspots: you declare yours. harbor.py seal runs the command in vessel_verify, which is project code, like the project’s tests.

−34 m

Failures it answers

What went wrong when I landed parallel sessions by hand on a real monorepo, and what Harbor does about each.

What went wrongWhat Harbor does
Two branches green on their own, red togetherOne verify of the combination; a fix is a sealed commit on convoy/<n>.
A branch’s “green” stopped matching its last commitThe seal belongs to the exact hash; a new commit has none.
Migration timestamps collided at integrationA migration check at assembly.
The board drifted from realityThe state is a branch only Harbor writes; the pages are generated from it and can’t say more than the data.
Sessions cut by account limits left work half pushedAccount pause and cap, and a handover with the pushed head.
A loose push to main broke a branch in flightEvery move of main is recorded with its cause, and the ok is void when main moves.
main was pushed after running too littleA push only with a green convoy seal at the ok’s level; Keelokit’s own hook stays.

−36 m

The pictures, and what each one stands for

The site is a sea, and Harbor’s words are about ports and ships. Each picture maps to one mechanism:

In HarborThe pictureWhat really happens
A small story with Keelokit aloneA sailboat that docks by itselfbuild-story (trivial or light tier) with a local verify, then a push to main (landing policy = direct). One verify per landing.
A big branchA cargo shipThe same road at the full tier or in a critical area: more agents, the full verify. Harbor doesn’t measure size; it records the tier.
convoyA convoy of ships and small vesselsThe branch convoy/<n> with main and the vessels merged, one verify, one push.
mainThe portThe branch main. Harbor touches it only in convoy sail.
vesselA vessel, small or bigOne session’s branch, entered with its exact hash and its seal.
skipperThe convoy’s skipperThe session that carries one convoy: takes deliveries, assembles, fixes the combination.
harbormasterThe harbormaster on watchOne at a time. Gives the ok and picks the verify level, with its reason. Doesn’t integrate or write code.
watchThe change of watchlast_control is the heartbeat; it expires after 180 minutes by default; the first commit wins.
logbookThe ship’s logbookThe orphan branch harbor/log: TOML with a fixed schema and generated pages. Only harbor.py writes it.
sealThe container sealA verify result for one exact commit. A new commit has no seal.
hotspotThe narrow channelPaths declared in [harbor.hotspots]. Two branches that touch one are never in open convoys together.
account capA crew with room for so many on deckmax_sessions and paused_until per account; at the limit, sessions hand over what they pushed.
convoy approveThe owner signs for the cargoYour yes from your own terminal, tied to the hash. Only with person_ok.
main movesThe tideThe ok no longer holds; assemble merges the new main and another ok is given. Each move is in main.toml.
Fresh readsThe ship’s radioHooks that run git fetch at start, at most every minute on a prompt, every 2 minutes after a tool and before a push to main.