jcardena.com › Blog › One Control Plane for Agent Sessions: Ownership, Not Copies
184 posts
EN ES

One Control Plane for Agent Sessions: Ownership, Not Copies

AI

When agent sessions outgrow editor windows, the failure is missing contracts. Machine, IDE, project group and session, one session contract, and a control plane that holds no state.

One Control Plane for Agent Sessions: Ownership, Not Copies

Published November 2026, dated to the month the work was done.

Unmanaged agent sessions fail the way unmanaged batch jobs fail. The work is real, but the ownership is not. If the project a session belongs to, the host it runs on and whether it is still alive exist only in a window layout, then closing a window quietly loses work.

Our team reached that limit as concurrent agent sessions spread across workstations and compute hosts. Sessions lived as terminals inside editor windows, a two-level model that held for a handful of sessions and failed as concurrency grew. The redesign gives the work four persisted levels, one session contract that treats local and remote the same, a strict rule about who owns the truth, and a separate control plane that steers everything and holds no session state.

Sessions insidewindowsNo project tierAdd project groupsOne sessioncontractResume where workstoppedOne estate view
From loose terminals to a governed estate

Where it started

The plan began from what the code and the store actually held, not from memory:

  • A window was a stored record: an id, a name, a color, a root folder and a saved layout.
  • A session was a record with its launch spec: which agent CLI, which folder, its status, and which window it belonged to.
  • Reopen last run already worked per window. On start, dead terminals were marked orphaned and could be relaunched with their resume flag.
  • Grouping was presentation only. The history panel grouped sessions by folder name at render time. Nothing was persisted, so the estate could not be observed or steered by project.
  • Remote sessions were second class. Remote files behaved like local files, but reopening a remote session after a restart did not.

The hierarchy

The target is four levels, each one persisted, none computed on the fly:

  • Machine: the host the session runs on, local or remote, treated the same.
  • IDE: a window with an id, a name and a color.
  • Project group: the unit of work, such as one data platform or one delivery stream.
  • Session: one agent CLI, with its conversation state and run history.

The key choice is that a group can span windows. People close, split and rearrange windows constantly. If the project lived inside a window, closing the window would lose the project. So the group is the durable container and the window is a view onto it. Each group names one primary window, so the default view is never ambiguous.

Folders still help. When a session starts in a known project folder, the app suggests a group, which can be accepted, renamed or changed. The folder is a suggestion, not a constraint.

Local equals remote

The keystone is one small session contract with six operations: create, list, attach, terminate, reopen and refresh. One implementation is local. The other talks to a session service on the remote host. The interface picks one based on where the session lives, and nothing else in the product checks local versus remote.

This is Governance-Driven Contract Design in miniature. The contract defines the guarantees, and every caller goes through the same door. A session on a remote compute host is managed exactly like one on the local workstation.

Who owns the truth

The design went through an adversarial review in two rounds: independent answers first, then a round aimed at breaking the draft. The second round changed the design.

The tempting move is to copy remote sessions into the local store so they look local. Then two stores claim to know whether a session is running. When they disagree, the control plane brings back work its owner already terminated, and operators stop trusting it. So the rule became:

Each machine owns its own sessions. The local store holds a reference, not a copy. Every change goes to the owner.

Each session also carries a generation number. Terminating a session advances it, so a stale reopen request from another window is ignored instead of bringing the session back.

The review also caught a scale risk. Terminal output and heartbeats must never go into the shared metadata store, or write contention appears long before the target scale. The store holds only durable metadata and desired state. High-volume data goes to per-session files and event streams.

One reviewer argued for the simpler model, one window per project. We kept the spanning model and wrote down what would reverse the decision: if projects almost never need more than one window in practice, collapse to the simpler model.

The control plane

The view over everything is a separate estate window, not a panel inside one IDE. It has no identity of its own, claims no window slot and recovers no sessions. It reads the state of every window and session from the service on each machine, and sends commands through the same control API: focus this window, open that project, start a new IDE for this group.

Because the machine services own the sessions, not the windows, the estate view cannot lock a running IDE or freeze a session. If the estate view hangs, the work keeps running. A default launch opens the estate view rather than guessing a window.

Resume has one more rule. When a group with many heavy sessions reopens, only the focused session resumes. The rest stay hibernated until selected. Staged recovery keeps a synchronized restart burst from exhausting the host.

CONTROL PLANEEstate viewControl APIWINDOWSIDE windowPrimary groupWORKProject groupsSessionsGeneration numberMACHINESLocal sessionproviderRemote sessionproviderPer-machine store
Machine, IDE, group and session under one control plane

How the build is governed

The build runs in six gated phases. Every change is additive: new tables and new columns with defaults, never a dropped or renamed column, so older code ignores what it does not know. A regression list of behaviors that already work, such as reopen last run, remote sessions and multiple windows not colliding, must pass after every phase.

The store changes and local project groups came first. They were then verified independently, from scratch: rebuild the code, exercise the running platform, and assert the store directly. They passed. Independent verification is also what tells a real failure from a false one. The remaining phases, the session contract, first-class remote sessions and the estate view, follow the same gates.

The test for this kind of system is simple. Close every interface, and the platform must still know what exists, who owns it and what may safely resume. Editors are fashion. The boundaries are the work. Every line holds.

JC
Juan Cardena
Enterprise AI & Agentic Systems Architect

Enterprise architect with 25 years across web, software, data, and AI. MIT CDAO ’25. Writing on agentic AI in production.