Skip to content
Bernhard GötzendorferAI automation that runs on its own · Vienna
FoundationBehind the Scenes

The lead session takes the night shift

One lead session coordinates my parallel coding sessions with leases, constraints and a merge order. Open questions reach me in one queue. Now on npm, MIT.

TL;DR

On 7 October at 19:53 I hand the night to a lead session. It coordinates my coding sessions with a lease, constraints and a merge train. At 06:30 the train stops, and at 07:03 it hands over to the next lead session. What went wrong sits in the report right next to what worked. The tool is now on npm as lead-session-orchestrator.

Night shift from 19:53

It is 7 October, 19:53. A fresh lead session has just taken over from its predecessor. I send it a short brief. It should "take over everything" and "speed up every project". The last line reads: "take over the night shift".

The lead session is a Claude Code session with a role of its own. Other sessions and headless runs write the code in my repos. The lead keeps the overview, orders the merges and collects what I have to decide. I built Navigator for this. How it works with Sven and session-orchestrator during the day is in From iPhone to Coding Session.

Shortly before ten I send one more note. The interface of FotoDrop, my family album, should get a quick polish. From then on, the lead session is meant to manage without me.

In the morning I want to see two things. What ran, with evidence. And what only I can decide, collected in one place.

That doesn't take a smarter agent. It takes one that may do nothing without a rule.

Whoever leads holds a lease

Before a lead session starts anything, it needs a lease. The lease is its claim on the role. There is only ever one lead. The lease is acquired, renewed at regular intervals, handed over and finally released. Without a valid lease of its own, a lead starts nothing and gives no merge signal.

So there can never be two leads contradicting each other. If a crash leaves an orphaned lock behind, it can be removed on purpose.

The other sessions check in when they start. In return they get constraints. These say how merges work in their repo and which pipeline counts. They also say what has priority in the fleet right now, and where they would get in another session's way.

If no constraints arrive, no session waits forever. After ten minutes it carries on with conservative defaults. The lead and the sessions talk only through files. Nobody blocks while waiting for someone else's message.

A message from another session is never an approval. Approval comes from my brief or from a signed authority file. That file says, per repository, which actions are free, which need me every time and which never happen. Anything it doesn't explicitly allow counts as not allowed.

The train runs on rules, not on questions

That night the train runs. The train is my name for the order in which merge requests go to main. A session finishes and sends its announcement: merge request, head SHA, pipeline and diff. The lead checks it and gives its signal. Only then is it merged.

Four rules apply that night. Before every signal, the branch has to contain the current main. If a session resolves a conflict, a new review follows. Before the next signal, production is read back. And at 06:30 the train stops.

So nobody has to ask at night whether they may. The rules answered that beforehand. A session from a website audit for BuchhaltGenie took five merge requests to production this way, one after another. Each one was then checked again through its health endpoint. From the middle of the night, that session saved every review report to a file.

Before every production merge, a review with Opus is supposed to run. That night it caught real bugs. A merge request in Navigator itself would have silently deleted run data. In FotoDrop, a single loading error would have taken down the whole timeline. And an error boundary would have swallowed render errors without reporting them to Sentry.

The fail-closed principle held as well. A push without the pre-push check was refused. A round that could not measure anything wrote nothing either.

In the morning the new FotoDrop interface is live. The health endpoint reports the same commit as main.

What went wrong overnight

The morning report also lists what didn't work. I read that part first.

At 23:02 the loop that renews the lead's lease ends. It hits a timeout in the middle of a memory crisis on my Mac. For two hours and twenty minutes, the renewal does not run. If the lease runs out, the lead may not start anything else. It became an issue: after a timeout, the loop should start again.

The lead itself got things wrong several times too. It misread a finding from an audit. The finding said to delete a number, and it passed on "add". The lesson is now in the report: read finding texts word for word, don't retell them.

Another time it assumed a test had grown. The session measured it: 1.3 seconds locally.

The review wasn't infallible either. It reported that an alert was missing in one place. The caller had been reporting that error all along. The fix for it was dropped.

Twice an announcement came with only a self-check, or a first review by another model. The Opus reviews were done afterwards. The lesson for the next nights: the first Opus review belongs before every announcement for production.

New issues in Navigator hold the lessons that need code or rules. That doesn't mean they are done.

Handover at seven

At 07:03 the lead session hands over to the next one. The handover is a file with the current state and the open threads.

A file like that is a draft, not yet a change of lead. That night the rule was still: the mandate only changes when I confirm it in the outgoing session. The incoming session quotes my words for it. Since 19 October I confirm planned changes once, in advance. A lead session still cannot appoint itself.

In the morning a report is waiting for me. It says what was merged and checked again. What only I can decide waits in the owner queue, with options and a recommendation. I don't have to read the night's chat log for that.

That is what I like most about this night. I don't have to follow it live to know in the morning what happened, and why.

What of this is on npm

Since 5 October, Navigator has been available as lead-session-orchestrator on npm. The package is MIT licensed, version 0.x, tested on macOS. On 24 October the current version is 0.4.0. The source repository is private. The product page is at session-orchestrator.com/lead.

In the terminal the command is simply lso, and navigator still works as a second name.

The package comes in three stages. One person with a few sessions needs only the Inbox. According to the README, setup takes about five minutes. Then all open decisions sit in their own pane in the terminal. Stage two is a separate lead tab that coordinates the others. Stage three is the fleet: signed authority files, headless runs in worktrees and merge gates on GitLab.

The README states the limits too. It supports GitLab only, with no GitHub gates yet. Everything runs on one machine. There is no daemon and no listening port. Commands and formats may still change in 0.x.

The package never grants an approval either. An answer in the Inbox records a decision. It doesn't allow a merge or a release.

session-orchestrator stays the engine inside a single session. Each tool also runs on its own. Together they share the lease, the constraints and the check-in. What session-orchestrator now knows about its own numbers is in My orchestrator now only counts what actually ran.

If you run more than one coding session at a time, start with the Inbox. The night shift comes later, with rules you set yourself beforehand.

lead-session-orchestrator

Many sessions, one lead, and whatever only you can decide waits in one inbox.

The language model
runs the lead session: it reads the situation, orders the merges and bundles your decisions.
The code
sets the limits: only ever one lead, one rule file per repository, and whatever it cannot measure, it leaves alone.

session-orchestrator.com/lead (opens another website)Product page for lead-session-orchestratorWhat I build for you