Skip to content

A session runs as an agent its profile offers - the plane resolves the default (build where offered, else the first offered) at create time and keeps it on the row, refuses a create naming an agent the profile lacks or on a profile that offers none, sends the row's agent on every activation including a wake, and parks a session whose pod will not run it as its agent instead of trying again; the clients send the default they show

Decision 979 · accepted · 2026-11-13 · issue #882

A profile whose spec.agents.allow named only its bundle's own agent could not start a session from the start screen, nor wake one (#882). The plane's offering was right: profiles.list's agents is the bundle's primaries and the built-ins, the profile's rule applied, then the grant (Decision 968), which is what the pod judges by. What went wrong is that nobody sent that agent. The start screens showed the profile's first agent and sent none unless one was named; the plane stored none and pushed none; and a pod given none runs its own default_agent, build, which the rule had taken away. A wake (restore_on_pod) never sent an agent at all, whatever the row held, so a session started with #agent was woken as build, refused, and left dormant with its epoch a step higher at every message.

Decision

The plane resolves the agent at create time. A create naming none gets the profile's default, build where the offering has it, as it always had, and else the offering's first, the bundle's own first primary. It is kept on the row like a named one, so the row holds what the session runs as from the start. A profile that offers no primary at all is refused at create time with invalid_params, field: "agent", as a create naming an agent the profile lacks already was; that refusal now carries field and agent beside the agents there are.

Every activation sends the row's agent. The first one, a waiting session's admission and a wake alike. A row from before this, with no agent, is sent the profile's default by the same rule, never left to the pod. The root replays a profile_switched from its log over it, and the row follows a switch from the pod's status reports, so the two agree.

A pod that will not run the session as its agent is final, not a blip. The worker answers {:not_on_profile, name} and {:unknown_agent, name} as invalid_params with reason: "agent_not_here" and the agent. The plane parks such a session read-only as it parks one whose workspace is gone (Decision 661), with failed_reason: "agent_not_here" on the row: a create answers invalid_params and keeps no row, a waiting session is parked rather than queued again, and a wake answers forbidden naming the agent, after which the next open is refused before any pod is asked and the epoch stays put. token.mint for a session that waited and was parked before it ever ran answers the same forbidden, so the casting screen that polls it says why instead of waiting for ever.

The clients send the default they show. Desktop and terminal pick build where the profile offers it, else its first agent (defaultProfileAgent, NewSession.default_agent/1), and send it; where profiles.list offers none they send none, show "its default", and the plane says why it cannot start one.

A profile scaled to zero is idle, not full. With no pod and nothing running a profile has capacity 0, which the screens read as a full house ("dev has 0 of 0 running"), and the auto-pick passed it over. profileRoom / NewSession.room/1 now say idle there, not full; the auto-pick counts it as having room, since a create starts a pod for it, and the profile picker tags it IDLE.

Governs: apps/troupe_plane/lib/troupe/plane/harness.ex, apps/troupe_worker/lib/troupe/worker/plane/commands.ex, clients/gui/packages/client/src/newSession.ts, clients/gui/apps/desktop/src/views/StartSession.tsx, clients/tui/lib/troupe/ui/new_session.ex, clients/tui/lib/troupe/ui/tui/new_session_page.ex