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