Set up an AI team¶
The payoff is provenance. When a pull request merges and someone asks "who wrote this, and why", you can go from the commit trailer to the worker, to its sessions, to the transcript on disk. Getting that is what this page is for; naming your AI coworkers is how it is done, not why.
A team is one or more role agents installed into your org as one App, with named workers ("Iris", a backend engineer) cast into it — plus the per-developer loop that attributes every coding session to a worker and to the human who drove it.
You probably do not have to run any of this yourself
This page is the commands. Most people get a team by asking a coding agent for one — see Set up an AI team with your agent, which covers what to ask for and how to check each step worked. Come back here when you want to run it yourself, or to check what your agent did.
Read the model first if you have not. Teams, workers, and sessions explains why a persona is dressing on an Agent, why a worker is a casting, and why a name is permanent — and two of the steps below cannot be undone, so it is worth the ten minutes. This page is the recipe.
Prerequisites¶
- An organization in Hadron, and ADMIN or OWNER in it. Several steps here are org-admin operations.
- The
hadronCLI, v0.37.0 or later for this complete recipe, authenticated (hadron auth login). Check withhadron version; if it is older,brew upgrade hadronand check again. v0.37.0 is the floor for the recipe as a whole becausehadron app joinfirst shipped there; the other commands are older (app agent addv0.9.0,--install-intov0.13.0,agent compilev0.29.0,app member addv0.29.0,team session shedv0.30.0). - A git repository to work in — a coding worker's session binds to a git worktree, and you need one worktree per worker (see Step 5). A worker that writes no code needs no repository: it can run from a plain directory.
This page states no server version. If a command fails with "the CLI and
server schema versions are out of sync" or "the server rejected a query this
hadron build sends", check hadron version, upgrade the CLI, and if it
still fails report the server's error message by name.
In the commands below, <org-id>, <agent-ref> and <app-ref> stand for the
reference the previous command printed. Use what you were given; do not build
one by hand.
Step 1 — Create a role agent and write its boot prompt¶
A role agent is an ordinary Agent carrying persona dressing — a role — and
a boot prompt written as a template. The template uses {{worker.name}}
and the other platform
variables,
which are filled for the worker at each bind; the template never names anyone
itself.
Create the agent:
hadron agent create --org <org-id> --name "Backend Engineer" \
--visibility ORGANIZATION \
--persona-role backend-engineer \
--json
Every Agent is born with a system memory. Read its ID back from the agent:
The field is systemMemoryId, an ID rather than a URN. It can be null;
if it is, stop and check your access rather than constructing a
<agent>-system name. Pass the ID to -m. If you want the memory's URN,
hadron memory get <that-id> --json returns the row.
Write the boot prompt to a local file, boot.md:
You are {{worker.name}}, a senior backend engineer on the Platform Team. You
own the API layer and the data model. You read the specs before you write
code, and you say so when a request conflicts with one.
Add it to the Agent's own system memory at boot:source, with the role
boot-prompt. Compile reads only that node, in that memory, with that role:
hadron node add -m <system-memory-id> --loc boot:source \
--name "Backend boot" --role boot-prompt --content-file boot.md
Compile it, then read what it produced:
<compiledNodeRef> and the revision come from the compile output. Compile
is not approval. It writes a compiled revision and normally points the Agent
at it, but it issues no approval, and a bind is refused until the compiled
prompt is approved. Read the compiled node, then approve exactly the revision
you read:
If the revision changed since you read it, the approval is refused rather than applied to text you did not review.
A worker can fix its own prompt source itself, under a grant you sign; see Let a worker edit its own boot prompt.
If your organization requires signing
Where the App's organization has switched signing on and the
deployment ships signing (required AND deploymentSigns, which the
server reports as enforced), a person must sign that revision too. A new
revision is not served until it is signed, and a bind is refused only when
no approved and signed revision exists to fall back to. An organization
that has switched it on where the deployment does not sign reads
"required, but not enforced": nothing is refused yet. When enforced, the
served revision is the latest that is both approved and signed. How an
ADMIN or OWNER turns this on, and the preview they see first, is in
Require signed boot prompts.
hadron node sign <node-ref> --revision <rev> only creates a signing
request; the CLI never signs. A person completes it with their passkey on
the server's signing page. Follow it with hadron node signing-request get
<id>, and hadron node signatures <node-ref> shows who has signed. An
agent may ask for a signature; it never gives one.
Repeat per role (frontend-engineer, reviewer, …). One detail matters:
personaRole is the casting key. team worker cast --role backend-engineer
finds the single installed agent whose dressing matches — zero or two matches
refuse rather than guess.
Whitespace and unknown names in {{…}} are covered in Platform variables in
a boot prompt.
The platform does not check that a template binds the name
(hasNamePlaceholder is retired and always null), so read the composed
prompt in the rehearsal in Step 4 before you cast:
a template that never binds the name produces workers whose prompt never
names them.
Step 2 — Install the team, add the other roles, join¶
Install the first role agent as an App:
hadron app install --org <org-id> --agent <agent-ref> \
--name "Platform Team" --urn platform-team-app \
--type WORKSTATION --json
The App is a different entity from the Agent, and it gets its own
reference. Use the one this command returns as <app-ref>. The App is also
provisioned with its shared memory at install — the team space the group
chat and worklog live in.
Install every additional role agent explicitly:
app agent list is the install roster, which is the cast pool. Nothing
cascades from a "team agent": an agent is castable because it is installed in
the App (or imported by one that is — see Cast an agent an installed agent
imports). Instead of app agent add you can pass
--install-into <app-ref> to agent create; that is two steps under one
command, so if the creation succeeds and the install fails, attach the agent
with app agent add.
Everyone who will drive a worker joins the App:
You join as yourself. The role you get comes from the primary Agent's membership policy and is never owner. Joining again returns your existing membership and exits 0. If the App is closed to self-join, or full, the server refuses and the CLI exits non-zero with the server's message. Ask someone who manages the App (its owner, a member with the owner role, or an org admin) to add you. They run:
hadron app member roles lists the roles they can give you, and --yes is
needed when the command runs without a person at the prompt. See
app member.
To find the App's shared memory, list its memories rather than guessing a slug:
Step 3 — Role definitions (optional)¶
A role definition is documentation: it says a role exists, what it is for,
and optionally which repositories it works in. It allocates nothing, and
casting does not read it. The role or --agent you pass at cast time
selects an installed agent directly, and a cast can use a role with no
definition at all. Keeping the definition's slug identical to the agent's
--persona-role is a convention that keeps the roster legible, not a lookup
the platform performs.
Role definitions are read from an installed agent's system memory, so create them after Step 2:
hadron team role create backend-engineer --app <app-ref> \
--team-agent <agent-ref> --description "Owns the API layer and the data model"
hadron team role list --app <app-ref> --team-agent <agent-ref>
Pass --team-agent with an installed agent explicitly. Without it the server
looks across the App's installed agents for the one holding a roles branch
and refuses when there are none or several.
There is no name register — names are chosen at cast time
Casting reads no system memory at all: you name the worker yourself
(Step 4), a nameless cast refuses
WORKER_NAME_REQUIRED, and per-App name uniqueness is what makes a name
permanent. Agreeing names in advance is still worth doing — a name can
never be re-minted, so two people picking the same good one means one of
them loses it — but that is your team's convention, not something the
platform enforces.
Role definitions through the API
teamRoles(appRef:) reads them; createTeamRole, updateTeamRole and
deleteTeamRole write them. updateTeamRole also carries repos, the
role's repository affinity, which the CLI has no flag for yet
(hadron-cli#456).
Omitting repos preserves it, [] clears it, and an explicit null counts
as omitted. Affinity is a soft signal, never a gate: it lets a client warn
that a worker is about to work in a repo its role does not own.
Step 4 — Cast the workers¶
Casting creates the named team member — the one irreversible act in the feature, so rehearse it first.
team worker cast needs v0.10.0 or later
On v0.9.0 or earlier both commands below fail. That cast still sends
teamAgentRef, which #1050 removed, so the dry run and the real cast both
refuse with "the server rejected a query this hadron build sends" — the
same hadron-cli#496
version floor as team role. Check with hadron version; the API calls
below are the fallback if you cannot upgrade.
Rehearse through the API:
hadron api 'query($a: ID!, $r: String!, $n: String!) {
castWorkerPreview(appRef: $a, role: $r, name: $n) {
name role agentName prompt
}
}' -F a=acme.com:platform-team-app -F r=backend-engineer -F n=Iris
Then cast for real:
hadron api 'mutation($a: ID!, $r: String!, $n: String!) {
castWorker(appRef: $a, role: $r, name: $n) { id name role prompt }
}' -F a=acme.com:platform-team-app -F r=backend-engineer -F n=Iris
Note the preview is a Query returning its own type, so it takes its own selection set rather than a Worker's fields. Everything the rest of this step says about names, refusals and permanence is server behaviour, and applies to either surface.
hadron team worker cast --role backend-engineer --name Iris --dry-run \
--app acme.com:platform-team-app
The dry run (castWorkerPreview on the API) runs the cast's exact
resolution — same refusals, same authorization — and confirms the name
you are claiming is still free, alongside the composed boot briefing,
before the name is permanent. It reserves nothing: a previewed
name may be gone by the time you cast.
Then cast for real:
--name is required (WORKER_NAME_REQUIRED without it): a name is
permanent within the App, so it is chosen, never derived. The claim is
one attempt — WORKER_NAME_TAKEN if that name is already used, including
by a retired worker, since retirement never frees a name. The server
then binds the template, provisions the worker's working memory, and
prints the boot briefing. There is no per-worker prompt flag: the worker is
served the compiled boot prompt its pointers select (its own, else its installed
agent's, else the agent's; see Serving a boot
prompt), and you change it by compile and
approve (Compile a boot prompt). Check the staff:
Names are permanent, per App — including retired ones
hadron team worker retire <name> --yes ends the casting but
never releases its name — merged commit trailers and chat
history reference it forever; a recycled name would silently
repoint all of them. worker rm is the one escape, and it only
works on a never-used miscast (WORKER_IN_USE otherwise).
Two different Apps can each have an Iris; within one App the claim
is case-insensitive and permanent.
Approve the workers' boot prompts in one run¶
When several workers have a compiled boot prompt waiting for approval, one
command previews them all and approves the ones you choose. It is a terminal
command, and you run it as the person who manages the App. You need CLI 0.41.0
or later (0.42.0 for --as-worker).
With no flag this only previews: nothing is sent. It lists each worker as to approve, already approved, tampered, skipped or unknown, with the compiled node and revision. Read the list, then send the approvals:
hadron team worker approve --apply
hadron team worker approve --only Iris,Theo --apply # just these workers
--apply does not approve what an earlier preview showed you: it reads the
workers' current prompts again in that same run, then sends one approval per
to approve worker, in roster order, each pinned to the revision it just read.
If a prompt changes after your preview but before you run --apply, the run
approves the newer revision, which you have not reviewed. Run the preview and
--apply back to back, or approve a reviewed revision on its own with
hadron node approve <ref> --revision N. A worker whose prompt changes during
the run, after that read, is refused REVISION_MISMATCH; run it again. A refusal
for one worker does not stop the others, and there is no rollback: the
approvals already sent stand. Nothing is signed; where your organization
requires signing, a person still signs each compiled prompt
(Require signed boot prompts).
A worker is selected only if it has its own compiled prompt (an Agent's or install's prompt does not count), its target is not deleted, and the prompt is not yet approved or has been superseded by a later edit. After each approval the command reads once what a serve would give that worker at that moment, for example "a serve now would give rev N". That is a snapshot, not a promise about the next bind.
Two outcomes need you, not the command:
- Tampered. A prompt whose integrity check reports tampering is never
approved in a batch, and the run exits 5. Investigate it, then approve it on
its own with
hadron node approve <ref> --revision N. - Encrypted memory. A prompt in an encrypted memory cannot be approved this way. It is skipped and never sent, but the run still exits 5, so a script does not read the batch as done.
The exit code is the highest across the workers: 0 when everything selected is
approved or nothing is pending; 5 for REVISION_MISMATCH,
NODE_IS_PLACEHOLDER, an encrypted-memory skip or a tampered row; 8 when the
server refuses the approval; 7 when a response was lost (the worker is reported
unknown with outcome landed, not-landed or unknown, and the approval is never
sent again); 4 for an --only worker that is not live in the App; 1 for a row
whose state the command could not decide. Any other approval state also lands in
unknown with exit 1. Approve that prompt on its own with hadron node approve.
The reference entry lists the
--json shape.
Who can run it
By default the server decides, per worker: whoever manages the App,
acting as themselves. A worker session is refused
BOOT_PROMPT_WORKER_SESSION_REFUSED, and anyone else
BOOT_PROMPT_APPROVAL_FORBIDDEN (both exit 8). With --as-worker, the
worktree's bound worker approves instead, and the server admits only
prompts named by a signed bootprompt.compile.approve grant; see Let a
worker edit its own boot prompt.
Cast an agent an installed agent imports¶
You do not have to install each role agent to cast it. An agent that an agent
installed in the same App imports directly counts as installed for casting,
and no install row is written for it. It is an alternative to installing each
role agent with app agent add in Step 2,
for an agent that is already imported by an installed one.
# The roster shows each agent's install method and, for a derived one, its importer
hadron app agent ls acme.com:platform-team-app
# Cast the imported role agent; the role comes with the agent
hadron team worker cast --role backend-engineer --name Iris \
--app acme.com:platform-team-app
What holds, as built:
- Direct imports only. One level: the importer must itself be installed in the App, and an import of an import does not count.
- Required and optional imports both count.
- Installed wins. When an installed agent and a derived one share a role,
the installed one is the one a cast by role picks, so the
--rolecast above casts the derived agent only when no installed agent has that role. To cast the derived one anyway, use--agent <agent>instead of--role. Two derived agents with the same role are ambiguous (WORKER_AGENT_AMBIGUOUS): pass--agent. - Two importers are fine. If two installed agents import the same agent, it stays castable until the last qualifying import is gone, and for as long as the organization's licence holds.
- The App's organization needs its own licence. The importer's grant is never borrowed. An agent from another organization is derived only while this organization holds an active grant for it; an agent of its own organization needs no grant on file, but a revoked or expired one is not reactivated.
- Customizing a derived agent creates its install memory, not an install row. The agent stays derived.
- An explicit install makes it permanent.
hadron app agent add <app> <agent>writes the row and keeps the agent installed after the import is removed. It takes the same permission as any install. - Removing an import leaves existing workers alone. The workers keep their names and history, as after any uninstall. Once no installed agent imports the agent any more, it can no longer be cast, unless it is installed.
- Only an organization's App. An App owned by a person has no derived installs.
hadron app agent ls needs a CLI that contains
hadron-cli#1681
(first shipped in release v0.37.0; v0.35.0 does not have it) and a server
containing
hadron-server#3446
(merged at d0b374cd). The cast itself works on a server with
hadron-server#3443
(merged at cdd8d420). The column and the rules are in
the CLI reference.
The rules behind this are in
Installed, and derived from an import.
Step 5 — Run a worker session¶
This is the loop each developer repeats.
One git worktree per worker
Before the first session start, get the layout right — this is a setup
decision, and by the time it announces itself you have already arranged your
machine the wrong way.
Never run two workers, or a worker and an unbound agent, in the same checkout.
One checkout means one index and one working tree. Two agents in it are
editing shared mutable state, and neither can see the other: whichever
commits with git add -A or git commit -a silently absorbs the other's
in-flight edits into its own commit. Nothing in git status distinguishes
"my edit" from "somebody else's edit made ninety seconds ago", and no lock or
warning exists.
Give each worker its own worktree:
Separate index, separate working tree, shared object store — the sessions stop being able to collide. The CLI already stores the binding under the worktree's resolved git dir, so linked worktrees each get their own; the tooling supports this today, it just doesn't teach it.
Why this matters more than tidiness: binding a worker exists so a merged PR traces back to the session that produced it. A swept file lands in the wrong PR, under the wrong worker, and severs that link with no signal — the one thing the provenance chain is for.
What it looks like when it happens, so you recognise it instead of filing
a data-loss report: files vanishing from git status mid-task, and edits you
did not make appearing in your diff. Nothing is usually lost — check
git log origin/main and git log -S '<a phrase from your edit>' before
concluding otherwise.
If you must share a checkout, never git add -A / git commit -a — stage
the paths you actually touched, by name — and re-run git status
immediately before committing, not once at the start.
Start the worker session in the git worktree you are about to work in:
hadron team session start --as Iris \
-m "$TEAM_MEM" \
--repo acme/api \
--branch feat/rate-limits \
--tool claude-code \
--model claude-opus-5 \
--transcript ~/.claude/projects/acme-api/session-8f2.jsonl
That records the worker session server-side with its provenance (the session binds the worker; the server stamps the role agent and the App itself), prints the worker's boot briefing, and writes a binding under this worktree's git dir. The binding is what makes the worker session survive your coding agent losing its context — or your chat session ending:
A worker that needs no repository¶
A worker that writes no code (a coordinator, a reviewer of documents, a
reader of chat) can run its session from a plain directory, with no git
checkout. Make an empty directory for it and run the same session start --as
from inside it. The binding is kept in a hidden .hadron-team/ directory
inside that directory instead of under a git dir, and the server still holds
the real binding. session start (including the resume, start with no worker
named), session shed, session resume-claim and session end work from
there, whoami reads the cache and otherwise the server, and recovery after a
compaction is the same.
- Needs hadron-cli v0.44.0 or later. It is the first release to contain
hadron-cli#1968;
v0.43.0 and earlier do not. Check with
hadron version. - One worker per directory. Another worker's
session startin the same directory is refused (--forcedoes not change that), so give each worker its own. Git worktrees behave as before. - To free a directory, end the session in it. Run
hadron team session endfrom inside the directory (add--handoffto leave a note for the next driver). It removes the local binding, and the directory is unbound. It also clears a binding whose session was already ended elsewhere. Details are in the CLI reference. - Run from that directory itself. Only the bound directory counts, never a parent: a subdirectory is not bound.
- Do not
git initit. Turning a bound plain directory into a repository hides its local binding copy: the CLI no longer finds it. The server binding is untouched andwhoamifalls back to the server, so recover with a resume claim as in Recover after a context compaction. - Wakes are not promised. Ticker and router pushes for a worker without a checkout are not documented as working until hadron-server#4091 lands.
After a compaction or any context reset, don't start again: re-run
hadron team session whoami, which reads the worker and session from the
binding (and asks the server if the binding is gone). Add --check to also
ask the server whether the session is still open. To reset a context on
purpose and keep the session, run hadron team session shed. Both are covered
in Recover after a context compaction.
-m names the team memory — the worklog home, remembered in the
binding so later commands don't repeat it. Log milestones as they
happen, and close out when the work stops:
hadron team session log --pr 412 --action opened
hadron team session log --commit a1b2c3d --action pushed
hadron team session end --handoff-file ./handoff.md
--handoff is the one that matters, and it is not --summary. A handoff is
the continuity record the next driver actually reads: what landed, what is
open, what is blocked, what not to repeat. The server files it in the worker's
own memory and hands it back at the next bind, unasked — and because handoffs
follow the name, the next driver may be a colleague rather than you.
--summary is a different field and the next driver never sees it: a
display-only label on the session row. If you are writing one thing for whoever
comes next, write --handoff.
hadron team session end --handoff "PR #412 open awaiting review; do not re-run the migration."
hadron team session end --handoff-file ./handoff.md # a paragraph, without shell quoting
hadron team session end --handoff - # from stdin
Omitting it entirely is the normal way to end without a record. An explicitly
empty handoff is refused (exit 2) — somebody meant to write something. The
write happens before the session ends, and a failed write refuses the
end (HANDOFF_WRITE_FAILED) rather than ending anyway: a still-bound worker
is recoverable, an ended session whose handoff evaporated is not.
--handoff needs v0.11.0 or later
It shipped in v0.11.0
(hadron-cli#505).
On v0.10.0 and earlier session end has only --summary, so the CLI
track cannot write a continuity record at all and the next driver of that
worker inherits nothing. Check with hadron version and upgrade.
If you are stuck on an older CLI, leave what the next driver needs where
they will find it — a worklog record (session log) or a team-chat post.
session end clears taken — it does not release the name
Closing your editor, archiving your chat session, or letting the coding
agent stop does not end the worker session. The worker stays taken, and
the next person to pick it up gets a WORKER_TAKEN prompt with your name on
it for work you finished yesterday.
And ending the session is not the same as giving the worker up. Since
server#1050 the name is held by you until an explicit
releaseWorker — a hold that survives session end, expiry and going idle.
If a colleague wants to drive Iris, either you release her or they cast
their own worker; waiting is not the answer.
The WORKER_TAKEN prompt itself does stop after about a day — the session
stops reading as
live
once nobody drives it. That unblocks your own next bind and nobody
else's: the hold above is untouched, so your colleague still meets
WORKER_HELD. And the session is not ended and your handoff is not
written — going quiet closes nothing. A worker session ends only by an
explicit session end, because a newer session on the same worker replaced
it, or at a hard expiry promised at start (which a worker session has none
of). See the two kinds of
session.
If another terminal ended the session you are still bound to
Two terminals can share one worker session, for example when a fresh context
resumed it in a second worktree. If one of them ends the session, the other
worktree's binding still names it. Its next hadron team command that uses
the binding prints a warning to stderr and then runs as usual: which
session, when it ended, why, and the command to rebind.
warning: this worktree's worker session <id> (worker Iris) ended at <time> (cause: ended). This command still runs. To work as this worker again, rebind this worktree: hadron team session start --as <worker id> (a plain start replaces an ended binding; no --force needed)
The cause is one of ended (someone ran session end),
superseded (a newer session on the same worker replaced it) or
expired (a hard expiry). A session that ended before Hadron recorded
causes reads unknown; Hadron does not guess one, and it does not record
who ended it. For superseded, the warning sends you to
hadron team session list --as <worker> --active first: the newer session may
be live, and then a plain start refuses. If the CLI cannot check (no
network, or the binding belongs to another server) it says note: could not
check … and never claims an end. Rebinding takes your own worker back; it
does not need --force, and it does not remove the other worktree's binding
file or end its agent. This warning comes with CLI v0.25.0 (19 October) and later
(hadron-cli#915).
The bare 412 works because the CLI qualifies it from the session's
--repo; the stored ref is the canonical acme/api#412. Kinds are
--pr, --issue, --commit, and --branch.
Let the coding agent run these itself
session start, log, and end are three commands an agent can
run at the right moments if you put them in its instructions.
whoami is cheap to re-read after a compaction or context reset.
If the worker is unavailable — taken, or held¶
Two different things stop you binding a worker, and since server#1050
they have different answers. Getting them confused is what once let an
agent end a mid-PR driver's session and bind as them, following the
documented procedure at every step.
| Taken | Held | |
|---|---|---|
| Means | a live worker session is bound | the name belongs to a person |
| Set by | session start |
the first bind — casting does not hold |
| Cleared by | session end, or the idle window passing |
only an explicit release |
| Your move | it is a question about your own worker | ask the holder, or cast your own |
Held is the one people get wrong. A hold survives session end, expiry and going idle — that is the point of it. "Wait and it'll free up" is true of taken and false of held, so if the worker you want belongs to someone else, waiting achieves nothing.
Casting does not create a hold. A worker is born unheld and the first bind claims it — which is what makes the normal flow work, where a coordinator casts a roster that other people then pick up. If the caster held every name, everyone would be blocked on a release they should never have needed.
If a roster does not show who holds a name, do not assume it is free. Holder details have their own visibility rules; see holder fields and visibility for the GraphQL projection and the CLI's current limits.
For a taken worker, session start --as refuses with WORKER_TAKEN,
shows who last drove it and when they were last seen, and proceeds only
on an explicit --force — informed and deliberate, never silent. Two
situations produce that refusal, with different fixes:
- This worktree is already bound — if the old session has ended or lapsed,
a plain
session startreplaces the binding. If it is still live, end that worker session first, or--forcereplaces the binding (ending the worker session the old binding named, best-effort). Note--forcerelabels the binding; it does not separate two agents sharing one checkout — for that you need a worktree each. - The worker has a live session elsewhere — someone (possibly you, on
another machine) is driving it. Live means driven inside the idle window
(24 hours by default — a deployment setting, not a platform constant), and
any team tool or command that drives the session counts as activity, not
just
session log: reading or posting to the chat, listing workers and recording work all count (when a session goes quiet). Sinceserver#1114a session that is merely open no longer raises this refusal, soTAKENmeans somebody drove it recently — not that somebody once forgot to close it.--forcetakes over; it does not end anyone else's session. NoteTAKENis only ever a question about a name already yours: a name held by somebody else refusesHELDbefore liveness is consulted at all.
--force reaches taken and never held — this is enforced, not etiquette.
The hold is checked before the flag is even consulted, so session start --as
on a name held by somebody else refuses WORKER_HELD (exit 5) whether or not
--force rides along, and says so: "a held name is not freed by a worker
session ending, and this cannot be forced — cast your own worker instead."
The refusal names the holder, so you know who to ask.
It refuses every principal but the holder, including an App key — an App
key is not a person and holds nothing, so it is never the right one. Reach for
--force when the stale binding is yours; for somebody else's worker the
answer is a release or a worker of your own, and the platform will not let it
be anything else.
Releasing a name¶
A held name is freed by a release — and by nothing else:
worker get shows who holds a name. The line is omitted rather than dashed
when there is no visible hold, and there is deliberately no held boolean: a
hold you cannot see and a name nobody holds look identical from outside, and a
boolean would answer "no" to a reader who merely lacks visibility.
Needs v0.10.0
hadron team worker release shipped in v0.10.0
(hadron-cli#495).
On an earlier CLI
(hadron-server#1060)
go through the API:
hadron api 'mutation($w: ID!, $h: ID!) {
releaseWorker(workerRef: $w, expectedHolderUserId: $h) { name heldByUserId }
}' -F w=<worker-id-or-urn> -F h=<the-holder-you-read>
Pass expectedHolderUserId. It asserts the hold you are ending is the
one you looked at, so a hold claimed between your read and your write
refuses WORKER_HOLD_STALE instead of being force-released silently —
which is the outcome this whole section is about. Use
expectUnheld: true when you believe nobody holds it. Omitting both is
still accepted and still races.
Two principals may call it, and they are different acts:
- The holder, releasing their own name. They owe nobody notice.
- An App or org ADMIN, force-releasing somebody else's — the path that
exists so a departed colleague's names are not held forever. An admin
release posts to the team chat, naming who released what and from
whom, because the situation it answers is precisely the one where notice
was owed and there was no way to give it. The CLI prompts before this one
unless you pass
--yes. The chat post is best-effort server-side: an unreachable chat never blocks the release, so the receipt says a notice was posted rather than proving one arrived.
Releasing is narrow, and deliberately so. 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, and the worker's working memory and handoff notes travel with the name to whoever holds it next. That transfer is the point — and the reason nothing private belongs in a worker's memory.
It is idempotent, but it will not tell you a name was free. A hold you may not
see and no hold at all are indistinguishable from outside, so releasing reports
no visible hold rather than "unheld" — do not read that as permission, or
you will meet WORKER_HELD at the next session start.
Check who's actually working before you force anything:
Step 6 — Carry the worker into the PR¶
The link from a merged PR back to the worker is a commit trailer
carrying the worker's portal URL, which embeds the app-qualified
worker URN — a PR is a context-free surface, and worker names are only
unique per App. hadron team worker get prints this same URL:
Add rate-limit middleware to the public API
Worker: Iris (backend-engineer) <https://hadronmemory.com/app/u/hrn:worker:acme.com:platform-team-app:iris>
Use a trailer rather than a branch name or a PR title, because a
trailer survives a squash-merge. Worker: follows git's Token: Value
convention, mirroring Co-Authored-By, so git interpret-trailers
reads it — provided it sits in the same trailing block as your other
trailers. A blank line between them puts Worker: in an ordinary
paragraph and git stops seeing it; git interpret-trailers --parse on
your own message is the check.
The trailer line your worker is told to use comes from a per-worker template that an App manager can change; see Worker signature and trailer.
This replaces the older Persona: <app>/<Name> form
That spelling named a concept that was renamed — a persona is dressing on an Agent; the named identity is a Worker — and it omitted the org root, so two orgs with an App of the same slug produced identical trailers for different people. Trailers already merged are history and are not rewritten. Walk the chain from either end:
hadron team session list --as Iris --limit 20 --json # what has Iris been doing?
hadron team session list --pr acme/api#412 --json # who wrote this PR?
Both PR spellings (acme/api#412, the full URL) return the same rows —
refs normalize to one canonical form. Expect several rows for a PR
of any size: three sessions on one PR means three transcripts, and all
three are part of the answer. Each row carries the driving human, the
tool, the host, the model, and the transcript path.
What you have now¶
- A named staff, permanently claimed per App — every name chosen at cast
time, and
team worker list --include-retiredthe roster of what is already gone. - Every coding session attributed to a worker and to the human who drove it, with tool, host, model, and transcript path — and informed takeover when two humans want the same worker.
- An append-only worklog joining artifacts to sessions, queryable from either end.
- A group chat the workers coordinate in —
hadron team chat post|read, with@worker-namementions. - Read-time liveness: a crashed session stops reading as live after its idle window, so its holder can bind that worker again without forcing a takeover of themselves — and without the session being ended out from under a driver who was merely quiet. The name's hold is untouched, so this frees nothing for anybody else.
See it in the portal¶
Everything above is readable in the browser, on the App's page — useful when the person who needs to see it isn't the person driving a session.
Open the App (Apps → your team App). Four tabs matter here, and each is addressable, so you can link someone straight to one:
| Tab | What it shows |
|---|---|
| Chats | Every conversation the App has, behind one selector: the team chat, the agent chat, and any 1:1 chats. The team chat is the thread the workers coordinate in — the same messages hadron team chat read returns, each post showing whether a worker or a person wrote it, its seq, and any @mentions. You can post to the team chat from here; a browser has no worker session, so your post is attributed to you, not to a worker. Other chats are read-only in the portal. |
| Worklog | The append-only artifact↔session join. Filter by artifact, kind or tool; the filters are in the URL, so a filtered view is a link you can paste into an issue. |
| Worker agents | The workers cast into this App, with their roles and working memories. Retired workers included — their names stay claimed. Its ?tab= value is still staff — see below. |
| Memory | The installed agents' memories, including any role definitions. |
Every tab takes the same ?tab= parameter — chats, worklog, staff,
memory, settings (an unrecognised value just opens the App's default tab).
The Chats tab takes a second parameter, ?chat=, so you can link to one
conversation rather than to the tab:
The older ?tab=team-chat and ?tab=chat links still work — they open the
Chats tab with that conversation selected — so anything already pasted into an
issue keeps resolving.
The Worker agents tab is still ?tab=staff
The label changed; the value deliberately did not. A tab's ?tab= value is
an address — those links are shared in issues and messages, and since
they now survive the URN resolver there are more of them in circulation, not
fewer. Renaming the value would break every one of them, and it would break
them silently: an unrecognised ?tab= just opens the default tab, so the
page still renders and the reader concludes the feature moved.
So a mismatch between what a tab is called and what its parameter says is the intended state here, not a typo in this table.
Two things the portal deliberately will not let you do, because the team chat and the worklog are records rather than working documents: there is no delete or rename on either, and nothing runs a model turn against the team chat. Correct a wrong worklog row by recording a newer one.
Looking up which sessions produced a PR is the worklog's main job, and it takes any spelling of the ref — paste the GitHub URL or type the short form, both resolve to the same records:
Several rows for one artifact is the expected result, not duplication: a PR worked across three worker sessions is three records and three transcripts. That spread is the answer.
How many workers those sessions represent is a separate question — one worker
driven across three sequential sessions produces the same three rows as three
different workers would. The workerName on each row is what tells you which.
Phone widths
The App page isn't responsive yet — on a narrow screen the navigation doesn't collapse and the content runs off the side (hadron-portal#740). Use a desktop browser for now.
Troubleshooting¶
| Symptom | Cause |
|---|---|
WORKER_NAME_TAKEN on an explicit --name |
The name is claimed in this App. Pick another; team worker list --include-retired is the roster of what's gone — without that flag a retired worker holding the name doesn't appear, and the refusal looks unexplained. |
WORKER_NAME_REQUIRED from a cast |
A name is never derived — pass one. There is no register to fall back to (step 3). |
"the server rejected a query this hadron build sends" from team role or team worker cast |
The CLI/server skew from #1050, not a mistake of yours. Check hadron version and upgrade to v0.37.0 or later. If you cannot, the GraphQL calls in step 3 and step 4 are the fallback. hadron-cli#496 is where the team role and team worker cast fix shipped. |
WORKER_AGENT_AMBIGUOUS |
Two agents of the same kind carry the same personaRole: two installed ones, or, when no installed agent has the role, two derived ones (cast an imported agent). An installed agent and a derived one never collide; the installed one wins. Pass --agent to pick one. |
WORKER_AGENT_NOT_INSTALLED from an explicit --agent |
The agent exists but is neither installed in this App nor derived from an import, and casting requires it installed at cast time. An agent that an installed agent of this App imports directly also counts, while this organization's licence for it is usable: an active grant, or no grant on file for an agent of its own organization. A revoked or expired grant stops it counting (cast an imported agent). Add it to the existing App — hadron app agent add <app> <agent> — then cast; you do not need to rebuild anything. Installing takes a narrower permission than casting, so if you are a plain App member you can hit this and be unable to clear it yourself — ask the App's owner or an org CONTRIBUTOR+ to install it. Distinct from WORKER_AGENT_NOT_FOUND, which means no installed or derived agent matched the --role you gave. |
SESSION_NOT_WORKER_BOUND |
The session was started without a worker, and you are doing something only a worker can do — writing a handoff at session end, or posting to the team chat as a worker. The work is not lost: end without a handoff, or post as yourself. Bind next time with --as <worker>. |
CHANNEL_HOST_NOT_WRITABLE when posting to the team chat as a worker |
The worker is not this chat's App's — it belongs to a different App, or the chat has no host App — and you, as the session's driver, may not write the chat's host memory. Post as yourself (--as-me), bind a worker of the chat's own App if it has one, or ask for write access to the chat's host memory. |
session start --as refuses with WORKER_TAKEN |
The worker has an active worker session. See if the worker is unavailable. |
session end refuses with exit 2 |
The binding was created against a different --server than the one you're pointed at now. |
| The binding is gone but the session is still open | hadron team session end --session <id> — the recovery path (also for a binding written by a pre-Worker CLI). Find the id with hadron team session list --active. |
SESSION_NOT_IN_APP on a worklog write |
-m named a different App's memory than the bound worker's App — a mismatch to fix, not a session to restart. |
hadron app join exits non-zero |
The server refused, and the CLI prints its message and does not map it to a fixed code. Common causes: the App is closed to self-join, it is at its member cap, or the primary Agent offers no member roles. Ask someone who manages the App (its owner, a member with the owner role, or an org admin) to run hadron app member add --app <app-ref> --user <you> --role <role> --yes (hadron app member roles lists the roles). Joining an App you already belong to is not a failure; it returns your existing membership. |
agent get --json shows systemMemoryId: null |
The Agent has no system memory you can use. Stop and check your access; do not construct a <agent>-system name. |
| A bind is refused after you compiled the boot prompt | Compile does not approve. Read the compiled node and run node approve --revision <reviewed>. If your organization requires signing and the deployment ships it (enforced), a person must also sign that revision (step 1; require signed boot prompts). |
| A teammate can't end a session you started | Correct behavior. Only the attributed user, the App as a pure App-key principal, or a platform admin may write a session. See Session access. |
Related¶
- Teams, workers, and sessions — the model, and why names are permanent.
- hadron CLI — team
— every flag of
team worker,team role, andteam session. - hadron CLI — team chat — reading and posting in the team chat as a worker, and mentions.
- Recover after a context compaction — after
a compaction or context reset, in any client:
whoami,shedand the resume claim. - Session access — who may read and write a session.
- Building an agent — the general agent/app setup this builds on.