Teams, workers, and sessions¶
A worker is a named AI team member. "Iris, senior backend engineer" is not a metaphor for a prompt file — she is an entity in Hadron, she is re-driven across dozens of coding sessions by whoever picks her up, and every one of those sessions is on the record with the human who drove it, the tool that ran it, and the path to the transcript.
This page explains the model — and the split at its heart: the persona (a reusable role, carried by an Agent) and the worker (the named individual, cast into one team).
Three sentences¶
- A persona is dressing on an
Agent — a role plus an identity
template. The template never names anyone: it uses
{{worker.name}}, filled for the worker at each bind. - A worker is a casting: an installed Agent cast into a team
App under a name. Iris is the
backend-engineerAgent, cast into theeng-teamApp asIris. Workers are the team's staff; names are unique per App, forever. - A worker session is the unit of work, and it is where the provenance lives — which worker, which human, which tool, which host, and where the transcript sits on disk. It is not your chat session: closing the conversation does not end it (why that matters).
The theater metaphor is load-bearing: the Agent is the role, the worker is the casting. One role can be cast twice in the same team (Iris and Henry, both backend engineers), and the same role can be cast under different names in different teams.
Why the persona is dressing, not the named thing¶
An earlier iteration of this model put the name on the Agent itself
(personaName, unique per owning org). That collapsed under its own
weight: locking a human name org-wide behind whichever team minted it
first does not scale past one team, and it welded the reusable part (the
role) to the local part (the name).
So the split is now explicit:
| Where | Field | What it holds |
|---|---|---|
| Agent | personaRole |
A free-string role with conventions — backend-engineer. Not an enum. |
| Agent | boot:source node |
The prompt template, with {{worker.name}} / {{worker.role}} placeholders, written in the Agent's system memory, then compiled and approved. One source serves the agent's own chats and every worker's briefing. |
| Worker | name |
The display name — Iris. Unique per App, case-insensitively, forever. |
| Worker | role |
The casting's role. It is the agent's personaRole and is never typed in: a cast cannot override it (WORKER_ROLE_OVERRIDE_REFUSED), and it changes only when the worker is moved to another agent (Changing the agent a worker casts). |
| Worker | signature, trailer |
The worker's signing templates. Amendable after casting (updateWorker); see Worker signature and trailer. There is no per-worker prompt field. The prompt a worker is served is chosen by pointer (its own, else its installed agent's, else the agent's; see Serving a boot prompt) and changes by compile and approve (Compile a boot prompt). |
| Worker | boot:workers:<workerId>:source node |
Per-worker individuality, written in the App's install memory, then compiled and approved. Editable after casting — identity is discovered through the work, so it is not sealed on day one. See Customize an installed agent and Compile a boot prompt. |
There is no prompt field on the Agent or the Worker: neither systemPrompt nor
promptOverride exists any more. The prompt lives in source nodes that are
compiled and approved.
A worker's resolved prompt — its boot briefing — is the compiled prompt it
is served (its own pointer, else its installed agent's, else the agent's; see
Serving a boot prompt), with the name and
role bound. The {{worker.name}} token is exact: {{ worker.name }} with spaces is
not substituted, and the older {{name}} / {{role}} print as written. The platform used to flag a template that never binds the
name (hasNamePlaceholder); that check was retired and the field now always
reads null, so look at the composed prompt before casting. A template that
never binds the name produces workers whose prompt never names them.
Where the model comes from — embodiment is session-level¶
An Agent carries a default AI configuration, but a worker driven from a
coding tool does not run on it. The worker is a name and a voice;
the embodiment — the LLM, the machine, the tool — belongs to the
session that drives it, recorded as llmModel / host / tool. This
is why Iris can be a Claude Code session on your laptop today and an
Opus-backed portal chat tomorrow without changing anything about Iris.
Why a team is an App¶
An App is already the runtime deployment: it authenticates, it scopes memory, it has members with roles, and it accumulates data. A team needs exactly those things.
Team App
├── Team Agent — its system memory holds the role definitions:
│ roles:<role> nodes (a definition per role)
├── Role Agents — ordinary Agents carrying persona dressing
├── Workers — the STAFF: named castings (Iris, Rufus, …)
│ └── each worker's working memory = its cross-session continuity
├── AppMember rows — the humans on the team
└── App-shared memory — what the team shares: group chat, worklog
- The install roster and the staff are different lists. The App's
roster says which role-agents are installed, by a physical
AppAgentrow or derived from an import; the workers say who is on staff. Casting requires the agent installed at cast time; the worker survives a later uninstall, because its name is bound to history. -
Role definitions are content. The
roles:<role>node in the Team Agent's system memory says a role exists and what it is for. It is a definition, not an allocation pool — sinceserver#1050it carries a description and nothing else. Once the App exists, prefer theteamRoles/createTeamRole/updateTeamRole/deleteTeamRolesurface over raw node writes — every one of those operations is App-addressed, so seeding the branch before install is still an ordinary node write.The name register is gone — server#1050
A role definition used to carry an ordered
data.namesregister, and a nameless cast allocated the next free entry. Since#1050a worker's name is chosen, never derived: it is mandatory at cast time (WORKER_NAME_REQUIRED), and casting reads no register and touches no system memory at all.The honest reading of that removal is worth keeping: the register was allocation bookkeeping, and per-App name uniqueness was always the thing that made a name permanent. Nothing about permanence changed when the register went. Any
data.namesleft on an existing role node is historical — neither read nor rewritten.- The App's shared memory is resolvable.
App.sharedMemoryanswers "what is this App's team space?" — the memory the team chat and worklog live in — so clients can default to it instead of asking you to name a memory. See Memory access for why the memory is the privacy boundary.
- The App's shared memory is resolvable.
Installed, and derived from an import¶
An agent can be installed in an App in two ways, and casting treats them the
same. The App's roster (App.appAgents) says which way, per entry, as
installMethod: ROW or DERIVED. The CLI shows them as installed and
derived, and as ? when the server withholds the answer (see
Withheld versus empty).
ROWis a physical install: anAppAgentrow, written when someone installs the agent, or installs a bundle that imports it as a required dependency.DERIVEDis no row at all. An agent that an installed agent of the same App imports directly, required or optional, counts as installed for casting. The roster entry names the importer.
The rules (cor:dmo:050:06 and
:11):
- A physical row wins, and the roster then reports
ROW. Derivation never recurses: an import of an import does not count, and the importer has to be installed itself. - It applies to an organization's App only. The App's organization needs its own usable license for the agent. That is an active grant or, for an agent of the App's own organization with no grant on file, no grant at all: a cast provisions the missing grant. A revoked or expired grant is never reactivated. The importer's grant is a witness for the import and is never borrowed as the organization's license.
- Casting by role prefers installed agents over derived ones. Within one
tier, two agents with the same role are ambiguous and the cast is refused
(
WORKER_AGENT_AMBIGUOUS), so two derived agents with one role need--agentto pick. - When two installed agents in the App import the same agent, the entry names the importer whose import took effect first. An import takes effect on the later of two dates: when the import was made and when its importer was installed. On a tie the earlier import wins, then the lower importer ID. Removing that import, or uninstalling that importer, moves the derivation to the other one. The agent stops counting as installed only when no installed agent in the App imports it any more.
- The derivation lasts only while the organization's license does. If the grant is revoked or expires, the agent stops counting as installed and can no longer be cast.
- Removing the last qualifying import ends the derivation and leaves existing workers alone. A worker is bound to its name and history, not to the install, as it is after any uninstall.
- Customizing a derived agent creates its install memory, and still writes no row. Uninstalling a derived entry succeeds and changes nothing, because there is no row. To stop an agent being castable, remove the import or uninstall the agent that imports it.
- An explicit install writes the row. The agent then stays installed after the import is removed.
installMethod and the importer are answered only to a caller who may read
every agent installed in the App. Otherwise both are null on every entry,
physical ones included, because answering per entry would reveal by
elimination which installs derive from an agent the caller cannot read. A
null is "not shown to you", never ROW.
To do it, see Cast an agent the Team Agent imports. The portal's Agents tab marks each agent Installed or Derived from its importer, and shows no mark when the server withholds that answer from you. Install on a derived agent is offered to anyone who can manage the App. The cast form lists installed agents first, then derived ones with their importer.
Casting, previewing, retiring¶
Casting is the one irreversible act in the feature, so it has a full lifecycle:
castWorkercreates the casting. The name is required (WORKER_NAME_REQUIRED) and binding it is an atomic claim: it either binds forever or refuses withWORKER_NAME_TAKEN. One attempt, no register walk — the uniqueness constraint itself is the allocation primitive, and there is no lease and no lock.castWorkerPreviewis the dry-run: the exact same resolution and refusals, up to but not including the writes. It confirms the name you are claiming is still free, and shows the composed boot briefing — reviewable before the name is permanent. The preview reserves nothing: a previewed name may be gone by the time you cast, by design.- A worker session at these doors. Casting, previewing, retiring and
deleting are refused to a worker session unless it carries an instruction or
holds its own
workers.staffgrant, and the holder's own staffing rights still apply. See Staffing and membership doors. retireWorkerends the casting. The worker stops authoring and takes no new worker sessions; the row — and its name — survive.deleteWorkerexists only for the never-used miscast: it refuses (WORKER_IN_USE) if any worker session was ever bound or the working memory holds content. Anything with history retires instead. It also needs an explicit attestation from the person asking: that they have verified no signed commit, trailer, PR, comment, review or published artifact elsewhere attributes work to the worker. The database cannot prove that, so when the history is known or uncertain, retire.
Changing the agent a worker casts¶
A worker's role follows its agent (cor:dmo:050:11). A cast takes the role of
the agent it names; a role passed beside an agent can only repeat that agent's
own role, and anything else is refused with WORKER_ROLE_OVERRIDE_REFUSED.
When a worker should do a different job, you do not recast it and lose the name.
changeWorkerAgent (a GraphQL mutation) moves the same
worker to another installed agent, and the role comes with the agent. The
worker's name, slug, URN, signature, trailer and reporting line stay, and every
past record stays: earlier sessions keep the agent and role they ran under. The
change is one transaction. It clears the worker's own boot-prompt pointer (it
named the old agent's compiled prompt), ends the old agent's generated tickers,
creates the new agent's, and records one worker.casting event (a worker first being cast into the team is recorded as worker.cast, a different event). It takes
effect at the worker's next bind: a session that is open when you change the agent finishes under the agent and role it was bound with (see What an open session keeps).
Only whoever manages the App can do this, as themselves, or a worker that
person holds, acting on their instruction. The call carries an instruction
claim, a typed pointer to where the holder told the worker to do it. The
platform records it and the holder answers for it; it does not check that the
instruction was given or was clear. For what a claim is, what is recorded and
what is not verified, see Acting on a holder's
instruction. The same rule applies to
changing a worker's signature or trailer (updateWorker), and to the seven
credential doors that list and revoke App keys and write grants (see App keys
— who lists, mints, revokes and rotates
them).
The staffing and member doors (casting, retiring, deleting and App membership) take an instruction too, and a worker can also hold its own grant for them; see Staffing and membership doors.
A worker session with no instruction, a host-launched session whatever it
claims, an App key, an impersonation and a run are all refused (FORBIDDEN),
and an instructed worker gets no more than its holder has. A refused change
changes nothing. The refusals are:
| Code | Meaning |
|---|---|
WORKER_RETIRED |
The worker is retired; its casting no longer changes. |
WORKER_AGENT_UNCHANGED |
The worker already casts that agent. |
WORKER_AGENT_HAS_NO_ROLE |
The new agent has no personaRole to change to. Give the agent one first. |
WORKER_CASTING_STALE |
The worker's agent changed while this change was in flight. Read it again and retry. |
The new agent must pass the same checks as a cast: the App is not uninstalled
(APP_UNINSTALLED), the agent is installed in the App
(WORKER_AGENT_NOT_INSTALLED), and the App holds the grants for it and for every
Agent its boot prompt includes from (AGENT_ORG_GRANT_INACTIVE,
AGENT_ORG_GRANT_REQUIRED, BOOT_PROMPT_GRANT_REQUIRED,
BOOT_PROMPT_INCLUDE_UNAVAILABLE).
Making the new agent's generated tickers can also refuse, and then nothing changes:
| Code | Meaning |
|---|---|
TICKER_LIMIT_REACHED |
The App is at its live-ticker limit. Delete a ticker, or ask whoever manages the App to raise the limit. |
TICKER_NAME_TAKEN |
A ticker the new agent would generate already has that name in the App. |
BAD_USER_INPUT |
The worker's name is too long to build a generated ticker name from. |
What an open session keeps¶
You do not have to end the worker's session first. A session that is open when
the agent changes keeps serving from the agent and role stamped on it at bind
(Session.agentId, Session.role) until that session ends, and the next bind
takes the new agent. Three things follow the session rather than the worker row:
- Register entries (which channels the worker takes part in).
- The boot briefing the session reads back.
- Task settings: the role the matcher offers tasks for,
uses_tasks, andreset_context_after_task.
Anyone who is not that session reads the live worker row: a manager, the portal and the roster show the new agent and role immediately. A session with no stamped role (a worker-less session) has no placement and falls back to the worker row.
A recovery read must pass the shared binding check
A reconnecting client that passes session explicitly gets its old placement
only if that session still passes the platform's one session-binding check:
open, not hard-expired, not dormant, the caller's own, never under
impersonation. A reconnect past the App's dormancy threshold therefore loses
its placement and is served the live worker row.
Who a worker reports to¶
A worker can record the one other worker it reports to. Ask an agent
"have Iris report to Marco" and it sets it; clearing it ("Iris reports to
nobody") is the same kind of request. The relation lives on the worker, the
casting, not on a session, so it survives rotation, a paused session and a
dormant team. It is informational: it shows up in the roster and worker reads
so you can see the team's structure, and nothing is refused because of it
beyond the task authority a worker has over the tasks of workers that report
to it (cor:agt:050:09). Who may change it is cor:agt:020:12.
The rules the server enforces:
- The target is another non-retired worker in the same App: never
itself, never a cycle. Each breach is refused with its own
WORKER_REPORTS_TO_*code. A worker from another App is not revealed to exist: naming one answers worker not found. - A worker that reports to nobody may be placed under a worker by that other worker claiming it for itself (only when one person holds both names; a name nobody holds counts as held by nobody), by the person who holds its name, or by whoever manages the App.
- Once a worker reports to someone, only the worker it reports to now (handing it over or clearing it is that worker's agreement) or whoever manages the App may change or clear it.
- Retiring a worker clears its own relation. Workers that report to it keep theirs and read as reporting to a retired worker: a stale claim that nothing clears automatically.
- Every change is a
worker.reports-toteam event. Setting the current value changes nothing.
For the command, see team worker set-reports-to.
Names are permanent — per App¶
Retiring a worker does not free its name. Deleting is only possible when
the worker never did anything. This is a consequence of the provenance
chain: Worker: Iris (backend-engineer) <hrn:worker:acme.com:eng-team:iris>
is sitting in merged commit messages and in years of chat history, and a
name that can be recycled is a name you cannot cite.
Uniqueness is scoped to the App — two teams can each have an Iris;
within one team, iris and Iris are the same claim, judged by the
database's own case folding so the answer never depends on the client's
locale. On a context-free surface (a PR, an org-wide list) the bare name
is therefore ambiguous, which is why those surfaces carry the
app-qualified compound: eng-team/Iris.
Sessions carry the provenance¶
Two different things are called a session¶
Before anything else, because the two are constantly confused and the confusion is expensive:
| Term | What it is | Who ends it |
|---|---|---|
| Worker session | The Hadron Session row binding a worker to the human driving it. This is what "taken" means, what a PR traces back to, and what the worklog attributes work to. |
An explicit end — and nothing else |
| Chat session | The conversation you are in: a Claude Desktop window, a Claude Code session, an IDE chat panel. | You, by closing or archiving it |
Ending a chat session does not end a worker session
They are unrelated lifecycles. Close your chat session for the day and the
worker session stays open — so the worker stays taken, and the next
person to bind it meets a WORKER_TAKEN takeover prompt with your name on
it, for a conversation you finished hours ago.
Nothing about closing a window suggests this, which is exactly why it needs saying. End the worker session explicitly when you're done working as the worker.
If you forget, nothing cleans up after you. A worker session has no
expiry, and going quiet does not end one
(hadron-server#1114).
The takeover prompt does stop: once the idle window passes the worker
stops reading as live, so WORKER_TAKEN no longer fires. Be careful what
you read into that — it clears the taken gate and nothing else. The
name stays held by you, so a
colleague still meets WORKER_HELD however long they wait, and force
does not reach it. What you get back is your own ability to re-bind
without a takeover prompt.
The session, meanwhile, stays open indefinitely with its handoff unwritten, and that is the part nobody gets back — see when a session goes quiet.
There is a third thing not to confuse with either: an agent chat — the
Chat entity, a stored conversation between an end user and an agent (see the
Chat API). It is deliberately not called a "chat
session".
Two habits follow, and this documentation keeps to them:
- "Chat session" is never shortened to "chat." In this product, "the chat" means the team chat — the group channel in the App. A sentence like "close the chat" reads as sensible and means two opposite things depending on which one the reader has in mind.
- "Team chat" always keeps the word "team." The portal's App page has one Chats tab holding every conversation the App has, and the entry inside it is still called "Team chat" — the tab names a container, not the thread. The rule is about the thread, and it has not moved: whenever you mean the team chat, say "team chat."
What the worker session records¶
A worker session binds the worker and the human together with the embodiment fields:
workerRefat session start binds the worker session to a worker. Accepts the worker's id, its URN (hrn:worker:<root>:<app-slug>:<slug>), or — within a known App — its name. The session'sagentIdis stamped with the casting's role-agent automatically.userIdis stamped from the caller — the human who drove the work, not the person who cast the worker months earlier.Session.workernests the casting on reads, so a session list can rendereng-team/Iriswithout extra round trips — including for retired workers, because retirement ends the casting, not the history.
"Taken" and informed takeover¶
A worker is in use iff a worker session bound to it is live — not ended, and driven inside its type's idle window. There is no engagement lease, and note that an open session is not automatically a live one: since hadron-server#1114 liveness is derived at read time rather than expressed by ending anything, so a session nobody has touched for a day stops blocking a bind while remaining open.
Takeover is informed and deliberate, enforced server-side: starting
a worker session as a taken worker refuses with the typed WORKER_TAKEN,
carrying who last drove it, when they were last seen, and the blocking
session id — everything a client needs for its takeover prompt. Passing
force: true proceeds; a silent takeover is not possible through any
surface. Two things make the worker untaken again: ending the worker
session, or simply nobody driving it for the length of the idle window.
What does not do it is closing your chat session — that leaves
the worker session open, and until the window passes the worker taken.
So a WORKER_TAKEN refusal is now stronger evidence than it used to
be. It no longer fires on a session somebody merely forgot to close;
it fires on one that has been driven recently. That is worth weighing
before you reach for force.
Takeover reaches taken and never held. The hold is checked first
and does not consult force at all, so binding a name held by someone else
refuses WORKER_HELD whichever way you ask, and the remedy is to cast your
own worker or have the name released. Untaken is not the same as available:
ending a session frees the session, never the name.
Taken and held are different states¶
Since #1050 availability is two questions, not one:
| Taken | Held | |
|---|---|---|
| What it says | a live worker session is bound | the name belongs to a person |
| Acquired by | session start |
the first bind — casting does not hold |
| Cleared by | ending that session, or the idle window passing | only releaseWorker |
| Whose question | your own worker | somebody else's |
The split exists because collapsing them was actively harmful. When availability was derived from session liveness, "is this worker free?" became a judgment about whether an idle driver was really gone — and an agent, following the documented procedure at every step, ended a mid-PR driver's session and bound as them. A hold is a fact, not a judgment: it survives session end, expiry, going idle, and a closed chat session.
Casting does not hold. A worker is born unheld and the first bind claims it. That is deliberate: the normal flow is a coordinator casting a roster that other people then pick up, and if the caster held every name, every one of those people would be blocked on a release they should never have needed.
Releasing is narrow. releaseWorker frees the hold and nothing else —
it does not retire the worker, does not free the name for a different
casting, and does not touch history. The name stays permanently allocated
to this casting; the worker's handoff notes and worklog travel with it to
whoever holds it next. Two principals may call it: the holder, who owes
nobody notice, or an App/org ADMIN force-releasing somebody else's — and
that second path posts to the team chat, naming who released what and
from whom, because the situation it answers is exactly the one where notice
was owed and there was no way to give it.
So the answer to "someone else has the worker I want" is to ask them to release it, or to cast your own — never to wait it out. A hold has no timeout, and nothing on the platform expires one.
The worklog is the join¶
A worker session and a work artifact are not one-to-one. A single PR can
span three worker sessions on two machines; a single worker session can
touch four PRs. So the artifact↔session join lives in the worklog, an append-only
record in the team App's shared memory: this session did this thing to
this artifact — pr merged acme/widgets#371, attributed to session
S and denormalizing the worker's name for display.
Two properties make it trustworthy as a ledger: it is append-only (a wrong entry is corrected by a newer entry), and it records external milestones only (calls into Hadron are already usage events). Lookups are equality matches on one canonical ref spelling per artifact; the grammar is in the work-ref contract.
Session.prNumber is display, not the record
A worker session still carries a prNumber, refreshed whenever a pr
milestone is recorded. It is a latest-wins convenience. Don't build
provenance on it — the worklog entry is the record.
The chain¶
FROM AN ARTIFACT FROM A NAME
worklog entry for acme/widgets#371 commit trailer: Worker: Iris (…) <…:eng-team:iris>
↓ ↓
every sessionId that touched it the App's worker named Iris
↓ ↓
└──────────→ Sessions ←─────────────┘
↓
userId, tool, host, llmModel, transcriptPath
↓
The transcript on disk
The left path answers "who wrote this PR?"; the right answers "what has Iris been doing?" The commit trailer survives a squash-merge, and it carries the app-qualified compound because a PR is a context-free surface.
The trailer is not hard-wired. Each worker has a signature and a trailer, stored as templates with defaults, that its boot briefing hands to the agent; an App manager can change them, and a change reaches the worker at its next bind. The platform supplies the text but cannot make an agent use it. The fields, variables, defaults and write rules are on Worker signature and trailer.
Who can read and write a session¶
Reading. The user a session is attributed to can always read it
(identity-scoped — never through
impersonation).
Org membership also grants read. The nested Session.worker shows every
reader the attribution scalars (the name, the App for the compound), but
the worker's working state — its resolved prompt and
working-memory id — stays behind the worker read gate and masks to null
for readers who are not App participants.
Writing. Only three principals can end or edit a session: the session's App as a pure App-key principal, the attributed user, or a platform admin. Org membership never writes, and a hybrid principal — a user calling through MCP with an active App selected — does not inherit App authority: the selection is a scope, not a credential.
Session binding is attribution, never authority. Both App-key and
user-credential callers can pin requests to a session with the
X-Hadron-Session header (an App key binds its own App's sessions; a
user binds sessions attributed to themself — no admin bypass, never
under impersonation). The binding's one effect is attribution: the work
heartbeats the session, which is what makes it read as being driven. It
never changes what the caller may read or write.
That header is a transport binding, which makes it a poor fit for the
desktop track: your worker session is created during the conversation by
hadron_start_session, long after the connection was opened, so it can never
appear in a header on that connection. You do not need it. Passing session
to a team tool is itself the heartbeat — see the note below.
When a session goes quiet
Going quiet no longer ends a session (hadron-server#1114). Silence is not evidence of abandonment — an agent you use once a year is not abandoned in month two — so the platform stopped inferring one from the other. What a quiet session loses is not its life but its liveness: how it is described.
Worker.hasLiveSession is derived at read time, never stored.
It is two conjuncts: the session has not ended, and it was
driven inside its type's idle window (24 hours by default). That
window is a deployment setting, not a platform constant, so the
number is a default rather than something to build on. Nothing is
written to express the answer, so a session that goes quiet for a
year and comes back is simply described as idle in the meantime, and
is still there when its driver returns.
Neither deadline is readable per session. Session.expiresAt on
the GraphQL Session type is the hard expiry and is nullable — null
for anything startSession created. The idle window is not
exposed for a given session at all, so there is no field that would
tell you when your worker stops reading as live. Keep it live by
driving it, not by watching a clock.
Heartbeats are session start, any authorized update, every usage
event attributed to the session — which is what the
X-Hadron-Session binding feeds — and, since
hadron-server#1081,
passing your session id to any team tool. That last one is the
one the desktop track actually runs on: reading the chat, posting to
it, listing workers or recording work all count as driving, so a
worker who never opens a pull request reads as live exactly as long
as one who does.
Ending is an act, never an inference. Three things end a session:
an explicit end, a newer session on the same worker replacing it, or a
hard expiresAt promised at session start. The server records which as
Session.endReason: ended, superseded or expired. A session that
ended before the field existed reads unknown; no cause is guessed for old
rows, and no ending actor is recorded.
The reaper
(hadron-server#930)
is still there and still runs, but since #1114 hard expiry is the
only rule it acts on. And startSession deliberately leaves
expiresAt null — so for a worker session, going quiet never closes
it: only an explicit end, or a newer session on the same worker, will. (Chatbot sessions differ:
startAgentSession stamps the expiry from the App's
sessionTimeoutSeconds, which is a promise made up front rather
than a guess about silence.)
What this costs you if you forget. Less recovers than you might
hope. Once the idle window passes, hasLiveSession goes false, and
that is the same predicate session start refuses WORKER_TAKEN on
— so the takeover prompt stops. That is the whole of what
changes. Since #1050 that gate only ever guarded a name already
yours, so what you recover is the ability to re-bind yourself
without force. The name does not free itself: it stays held until
you release it, and nobody else gets past WORKER_HELD by waiting.
And the handoff does not recover. The session stays open
forever with its closing note unwritten, and the next driver is told
the stint ended without one — shown the previous handoff as
history rather than as the current state of play. So they are not
misled; they are simply missing the stint that mattered most. That
asymmetry is the whole reason to end
deliberately, with a
handoff:
what you lose by forgetting is invisible from the outside, because
the outcome that is visible — the takeover prompt going quiet —
looks the same either way.
Two consequences worth knowing. Passing session is what keeps a
session reading as live, so a stint driven without it can look
abandoned mid-work — the same argument as attribution, from the
other end. And the heartbeat re-checks your current access each
time: if your membership of the App is revoked, the session stops
being kept alive even though it is still yours on paper.
Status¶
The Worker model and its platform surfaces are complete on the server (epic hadron-server#981):
| Piece | Where it stands |
|---|---|
| The Worker model — persona as dressing, workers as castings, per-App name permanence | Shipped (hadron-server#974). |
castWorker / retireWorker / deleteWorker / updateWorker, workers / worker reads |
Shipped, with CLI parity (hadron team worker cast, list, get, update). updateWorker amends the signature and trailer templates (hadron-server#1010, #2712); worker(ref:) also takes a worker name with appRef (hadron-server#1015). |
Compaction recovery: hadron team worker get (re-fetch the boot briefing, rendered live) + hadron team session whoami --check (your own open session) |
Shipped (hadron-server#1015/#1016 on the server; the commands in the CLI). Closes the gap where an agent that lost its context had no legitimate route back to its briefing or its session id. |
deleteTeamRole — retire a role |
Shipped (hadron-server#1002); unconditional since #1050. Superseding a role is create-the-successor, then delete the old one — transferTo went with the register it protected. |
castWorkerPreview — the reserves-nothing dry-run |
Shipped (hadron-server#964). |
teamRoles + createTeamRole / updateTeamRole — role definitions as a surface |
Shipped (hadron-server#960). |
Session binding: workerRef, server-enforced WORKER_TAKEN + force, Session.worker nested read |
Shipped (hadron-server#940/#980), CLI parity on hadron team session start --as. |
App.sharedMemory — the App → team-space hop |
Shipped (hadron-server#965). |
User-credential session heartbeat (X-Hadron-Session for user principals) |
Shipped (hadron-server#934). |
| Team chat + worklog platform operations | Shipped (hadron-server#939/#947). |
| Session reaper | Shipped (hadron-server#930), then narrowed to hard expiry alone (hadron-server#1114). It no longer ends a session for inactivity; liveness is derived at read time instead, so a quiet session is described as idle rather than closed. startSession sets no expiry, so nothing auto-ends a worker session. |
| CLI adoption of the Worker model | Shipped (hadron-cli#428). The team worker group, workerRef session binding, and the app-qualified Worker: commit trailer are all in. |
What's next¶
- Set up an AI team — build the team App, cast workers, and run an attributed coding session.
- Entity architecture — where Agents, Apps, Workers, and sessions sit relative to everything else.
- Work with your team coordinator — the team chat workers coordinate over, from the portal side.
- Authorization — the roles, grants, and guardrails the session rules sit inside.