Session roles and missions

Once you have more than a handful of agents in the Director, the hard question stops being "what is each one doing" and becomes "who is in charge of what." Session roles answer that at a glance. Every session on the Director carries a role - Standalone, Architect, Manager, or Worker - and related sessions can be attached to a named mission. You can read a busy fleet in one sweep: which sessions are solo, which one plans, which supervise, and which are heads-down doing the work.

The five roles

A role describes a session's place in a piece of work, not a different kind of agent. The same coding agent can be a Worker on one task and a Manager on another. The method has five roles; the first four are what DevThrottle records today, and they are the values the role flag accepts.

• Standalone. The default. A solo session that is not wired to any other - it is just working on its own, facing you. Every undeclared session starts here, and most of a casual fleet stays this way; a session spawned with a declared role - an Architect, or an explicit Worker - wears that role from birth instead.
• Architect. The session that settles the design and directs the rest. This is the one role DevThrottle can never work out for you - nothing in how sessions are wired says which one is the planner - so an Architect only exists because you declared one.
• Manager. The badge an undeclared session earns by supervising: it shows as a Manager while any live supervised session sits under it - whatever role that session itself wears - and loses the badge when the last one ends. A session that itself answers to a live Supervisor resolves as a Worker first, so in a chain the middle session wears the W, not the M.
• Worker. A session running work under a live supervisor. If a session is doing a job that a different session set up and is still watching, it shows as a Worker. That is the derived case; a declared Worker needs no Supervisor at all and stays a Worker until the declaration is cleared.
• Reviewer. A different session from the one that wrote the work, checking it before it lands. The role is agreed but not yet recordable: the role flag does not accept it, and no badge shows for it - today a Reviewer is staffed by a workflow, such as the one shipped in the catalog as standalone-with-review.

Roles are worked out for you

You do not tag every session by hand. An undeclared session starts as Standalone, and its role changes as the work connects up: one running work under a live Supervisor shows as a Worker, and an undeclared session with a live supervised session under it shows as a Manager, for as long as that is true. You can also declare any of the four recordable roles explicitly - at spawn with cc-devthrottle session spawn --role, or later with cc-devthrottle session role - and a declared role wins from birth, before any wiring is read: a declared Architect wears its badge without supervising anyone, and a declared Worker is a Worker with no live Supervisor, or none at all. The declaration sticks until you clear it by declaring none. That is why an Architect that hands work down stays an Architect rather than turning into a Manager. Architect is the one role that must be declared, because it can never be derived.

Two different edges connect sessions, and only one of them drives any of this. The Supervisor is the live relationship - it is what roles and colours are computed from, and it changes how the supervised session is displayed. The Parent is the historical fact of who started a session, and it changes nothing on screen. The two usually coincide, and they diverge when a session deliberately starts a human-facing peer: the peer has a Parent but no Supervisor.

A Worker never nags you

The role changes what the colours mean. A Standalone, Manager, or Architect that needs input turns red - it is facing you, so its red is your business. A Worker's red is its Supervisor's business - and the Supervisor need not be a Manager; a Worker can answer directly to an Architect. While the Supervisor is alive, a waiting Worker recedes to a quiet slate instead of red (the Cockpit's fleet-map legend calls this colour Sub-agent), and its Supervisor deals with it.

There is an escape hatch, and one deliberate exception to it. A Worker whose role was worked out from the wiring stops being a Worker when its supervising session dies, so anything it needs from a human turns red again rather than waiting silently on a Supervisor that will never answer. A Worker you declared explicitly is different: the declaration is sticky, so it keeps the role - and the quiet slate - even after its Supervisor exits, until you clear the role.

On the Director's session rail, the role shows as a single-letter badge - M for Manager, W for Worker, A for Architect, with the full name in the tooltip. Standalone shows no badge, so the common case stays quiet.

Missions: a name for related work

When several sessions serve one effort, create a mission. A mission is the undertaking itself - why the work exists, who is on it, and the tasks it breaks into - not a box that holds sessions. Sessions are attached to it separately: at spawn with --mission, or by inheritance, since a session spawned under a Supervisor joins that Supervisor's mission unless told otherwise. With the attachment in place, a whole line of work reads as one thing on the fleet map instead of a scatter of unrelated cards.

Why this matters

The point of DevThrottle is to run many agents without losing the thread. Roles and missions make the fleet legible: instead of a wall of identical sessions, you see a structure - the Architect that is steering, the Managers watching their Workers, and the missions that work belongs to. That is what lets you scale from one agent to a whole fleet and still know, at a glance, who needs you.

Where to go next

Roles sit on top of the session basics. If you have not yet, read session cards and states for how to read a single card, and starting and steering agents for how work gets going in the first place. To put roles to work on a real job, follow the roles tutorial.