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.
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/.
- 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.pywritesOne 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.mdandconvoys/<n>.mdare 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
| State | Means |
|---|---|
assembling | created; the skipper takes deliveries |
waiting | assembled with what was delivered; an expected vessel, or a convoy it depends on, is still missing |
ready | every expected vessel merged in convoy/<n> with main, migrations in order: waiting for the ok |
verifying | the ok is given with its level; the integrator runs the convoy’s one verify and fixes the combination |
sailed | pushed to main; hotspots released |
aborted | given up; its vessels may join another convoy |
| Command | What happens |
|---|---|
/harbor:adopt | Sets 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|status | Opens a convoy, adds a sealed vessel, shows what moved. |
/harbor:convoy assemble|verify|sail | Merges 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|defer | Gives a convoy up, or takes a late story out so the rest don’t wait. |
/harbor:log | The logbook: watch, convoys, workers, accounts. |
/harbor:harbormaster takeover|control | Takes 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>.tomlis Harbor’s record of one verify, green, red or partial.seals/<sha>.tomlis 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 themainof 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(changedorall) 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 nolevel, and the pre-push runs its verify.No second run
With the convoy policy,
build-storypushes the vessel’s branch and Keelokit’s pre-push runs the whole verify on that exact commit.harbor.py sealfinds 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.
| Hook | What it does | How often |
|---|---|---|
SessionStart | Fetches and prints whether it is fresh or how old the last fetch is. | every start |
UserPromptSubmit | Fetches 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 |
PostToolUse | The same, as context for the model. | at most every 2 min |
PreToolUse, Bash | Denies 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
assemblemergesorigin/mainintoconvoy/<n>and moves its base.ready or verifying
The ok is void, because its level was chosen for other contents.
assemblemergesmain, the convoy goes back to ready, and the harbormaster gives a new ok.sailrefuses whilemainisn’t the ok’s base.depending convoys
A convoy whose dependency hasn’t sailed stays waiting; when it sails, the next
assemblemerges the newmain.seals
A vessel’s seal stays valid as an entry ticket: it speaks for the vessel’s own part against the
mainit had. The combination is what the convoy’s verify covers.the record
Every move goes in
main.tomlwith 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.
| Keelokit | Harbor uses it for |
|---|---|
[landing] policy = "convoy" in state.toml | The switch. Under it build-story pushes only its branch and reports branch, full hash, tier and verify result. |
pnpm verify --since REF | The vessel’s own verify: its part only. |
pnpm verify --keep-going, --all, --preflight | The 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.history | One line per run. Harbor copies it into the seal, and reuses a whole green run instead of repeating it. |
[verify] shared_seals | Lets 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: trailer | The 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 wrong | What Harbor does |
|---|---|
| Two branches green on their own, red together | One verify of the combination; a fix is a sealed commit on convoy/<n>. |
| A branch’s “green” stopped matching its last commit | The seal belongs to the exact hash; a new commit has none. |
| Migration timestamps collided at integration | A migration check at assembly. |
| The board drifted from reality | The 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 pushed | Account pause and cap, and a handover with the pushed head. |
A loose push to main broke a branch in flight | Every move of main is recorded with its cause, and the ok is void when main moves. |
main was pushed after running too little | A 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 Harbor | The picture | What really happens |
|---|---|---|
| A small story with Keelokit alone | A sailboat that docks by itself | build-story (trivial or light tier) with a local verify, then a push to main (landing policy = direct). One verify per landing. |
| A big branch | A cargo ship | The 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. |
| convoy | A convoy of ships and small vessels | The branch convoy/<n> with main and the vessels merged, one verify, one push. |
main | The port | The branch main. Harbor touches it only in convoy sail. |
| vessel | A vessel, small or big | One session’s branch, entered with its exact hash and its seal. |
| skipper | The convoy’s skipper | The session that carries one convoy: takes deliveries, assembles, fixes the combination. |
| harbormaster | The harbormaster on watch | One at a time. Gives the ok and picks the verify level, with its reason. Doesn’t integrate or write code. |
| watch | The change of watch | last_control is the heartbeat; it expires after 180 minutes by default; the first commit wins. |
| logbook | The ship’s logbook | The orphan branch harbor/log: TOML with a fixed schema and generated pages. Only harbor.py writes it. |
| seal | The container seal | A verify result for one exact commit. A new commit has no seal. |
| hotspot | The narrow channel | Paths declared in [harbor.hotspots]. Two branches that touch one are never in open convoys together. |
| account cap | A crew with room for so many on deck | max_sessions and paused_until per account; at the limit, sessions hand over what they pushed. |
convoy approve | The owner signs for the cargo | Your yes from your own terminal, tied to the hash. Only with person_ok. |
main moves | The tide | The ok no longer holds; assemble merges the new main and another ok is given. Each move is in main.toml. |
| Fresh reads | The ship’s radio | Hooks 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. |