# Cockpit

One screen for every coding session OCTYN has open at once, built because the hard part stopped being the work and became knowing which session was waiting on a person.

Domain: Our own · Cockpit
Label: Running (our own)
For your engineering team. Inside: session monitor · waiting-on-a-person alerts · one screen

## Dated figures

- In build. The working prototype is what is pictured (recorded 2026-09-14)
- Around 18 sessions at once across 21 codebases (recorded 2026-09-14)
- Local daemon on 127.0.0.1, no remote surface (recorded 2026-09-14)
- No timing instrumentation yet (recorded 2026-09-14)

Cockpit is OCTYN's own internal system, in build and used while it is being built. The picture on this page is the working prototype with sample data in it, not a design.

## The situation

OCTYN runs around eighteen coding sessions at once across twenty-one codebases, as recorded on the work page on 2026-09-14. Every existing way of running those sessions is built for running one. There is a terminal, there is a conversation, and there is no answer at all to the only question that matters when there are eighteen of them: which one is stopped, waiting for a person, right now.

The failure is not dramatic. A session asks a question and then sits there. Nobody notices, because noticing means checking eighteen windows, and the cost is not a crash, it is an hour of nothing happening in a place nobody was looking.

## Why it was hard

The state a session is in is not a status field anybody publishes. It has to be worked out from what the session prints, and the categories that matter are not the ones a process reports. A session that is running and a session that has finished and gone idle look identical from the outside. A session that has asked a question and a session that has hit an error both look like a session that has stopped printing.

The second problem is that a summary of a terminal is useless on its own. The moment action is needed, the real thing is what is needed, with its colours and its control characters intact, and switching away from it at exactly the wrong moment defeats the point.

The third is that watching has to cost less than the thing being watched. A monitor that takes as much attention as the sessions it covers has not helped.

## What was built

One program that holds every session, and one screen over it. That program is bound to the local machine only, which is the whole security model: it runs on the machine the sessions run on and has no remote surface to reach.

The screen is three columns. On the left, projects, each showing how many of its sessions are running, how many exist and how many are waiting. In the middle, the session itself, in a real terminal rather than a rendering of one. On the right, the rail that is the actual point: one session in focus with why it stopped, then everything else waiting, then everything still running, then recent activity.

The naming is the part that took the thinking. A waiting session is tagged with what it is waiting for, and the tags are distinct: asked, meaning it wants an answer, and review, meaning it has finished something and wants a person to look. An error is a third thing again and takes the focus slot. The footer reduces the whole fleet to three counts, and the only one that is urgent is how many sessions need a person.

## What it does under load

Not measured. There is no timing instrumentation in the prototype, so there is no figure for how long a session sits waiting before it is picked up, which is the number this system exists to reduce and the obvious thing to record first.

What can be said with a date, from the capture taken on 2026-09-14: the prototype holds a sample fleet of seven sessions across four projects, with two running and four needing a person. The terminal pane in that capture is a mock, labelled as one in the capture itself; the real one is a full terminal. The load question for this design is not session count, it is bytes: a fleet of terminals all streaming at once is a lot of output to hold, and nothing here has been measured against that yet.

## What happens when it breaks

The honest answer, and the reason this is a write-up of something in build rather than something finished: the failure modes are understood and not all of them are handled.

The single program holding every session is the single point of failure, by design. If it dies, the sessions are separate processes and keep running; only the view over them is lost. That is the right way round, and it is why the program holds sessions instead of owning them.

A stale status is the failure that costs the most, because it is silent. A session shown as running when it has actually stopped and asked a question is worse to trust than no monitor at all, since it answers the question wrongly and gets believed anyway. Working out state from output is inherently a guess, and there is no confidence signal in the prototype yet.

Staying local removes a whole class of problems and adds one. Nothing is exposed and nothing needs a login, and there is also no way to see the fleet from a phone, which is where the person is when a session has been waiting for twenty minutes.

## Who maintains it, and what that costs in attention

The person whose sessions it watches, which is the correct incentive: a monitor kept by somebody who does not depend on it goes stale without anyone noticing.

Its steady-state cost is unusual in that this is the one internal system where neglect is visible immediately. If the status inference drifts, the person using it finds out within a day, because a session marked busy turns out to have been waiting since the morning.

## What changes when requirements change in six months

Configuration, no code: which projects are in the fleet.

A small code change: another waiting category, another column in the rail, another shortcut to jump between sessions. Session states are data, and adding one is adding a row to it.

A larger code change: supporting a second kind of session process. Everything here assumes one shape, and a second one means the state inference stops being a single implementation.

A rebuild: making it remote. Staying local is not a shortcut taken here; it is the reason the system needs no login, no encryption and no account. Putting the fleet on a phone means all three, and that is a different system.

## What we would do differently

Record the waiting time from the first commit. The entire argument for this system is that sessions sit idle unnoticed, and the prototype cannot yet show that figure going down.

Treat status inference as a first-class problem, not plumbing. It is the thing most likely to be quietly wrong, and it is currently the least defended part of the design.

And write down what a session state means before drawing the screen. The tags in the rail are the good part of this system, and they were arrived at by drawing the screen twice.

## Related

- [The Consult](https://octyn.co/consult)

Canonical: https://octyn.co/casestudies/cockpit