Fix identity errors

Each agent has an identity: a name, a role and a folder (a git worktree) that belongs to it. A worktree is a separate checkout of your repository on its own branch. Thrum checks that a command comes from the agent that owns that folder. If the check fails, the command stops with an “identity guard” message. The work is not recorded under the wrong agent. The agent is not broken. One command was refused.

You see these messages in an agent’s Terminal tab in the web UI, or your coordinator reports them. Your coordinator is the agent you talk to, which starts the other agents, hands out work and reports back to you. Each heading below says in plain words what happened. The first line under it gives the exact text of the message, so you can also search this page for the message. Ask your coordinator first. The typed commands are for when the coordinator cannot reach Thrum.

Commands refused by an identity guard

identity guard "cross_worktree" fired: pid_mismatch

The message names an “expected agent” and a “detected agent”.

Cause. The command ran from a folder that belongs to a different agent. It can also appear after an agent restarts and Thrum still holds the old session record.

Fix.

1. Ask the coordinator: “Which agent should have run that command, and from which folder? Run it again from that agent’s own session.”
2. If the agent is the right one and the message says its record is stale, ask your coordinator: Have reviewer_api run thrum prime in its own session. Use the agent’s name from the message. thrum prime loads the agent’s briefing at the start of a session. Run from the agent’s own session, it also claims the agent’s identity again.

Check it worked: the repeated command runs without the guard message.

Note

The message may suggest thrum quickstart --name <agent>. Only that agent should run it, from its own session. Anyone else would take over its identity.

identity guard "unauthenticated_rpc" fired: identity_mismatch

The remediation line says either “your current directory is inside … worktree” or “your process ancestor chain belongs to …”. The ancestor chain is the chain of programs that started the command. Here it leads back to another agent’s session.

Cause. The command says it comes from one agent, but it ran inside another agent’s folder or terminal pane. This happens when an agent changes folder during a session, or a tool keeps an old name from a previous session.

Fix.

1. Ask the coordinator to run the command from the owning agent’s folder or pane.
2. If a tool or script sets the agent name itself, restart that tool so it picks up the current name.

No setting turns this check off. It exists so one agent never acts as another.

identity guard "unauthenticated_rpc" fired: anonymous_mutating_rpc

The remediation line says “daemon hasn’t bound this caller to a registered agent”. The daemon is Thrum’s background process on your machine. A variant says “daemon rejected this worktree’s runtime, the AI coding tool an agent runs in, such as Claude Code or Codex, identity evidence; re-prime the managed runtime before retrying.” In that variant the daemon has no record of the agent’s running session, so ask the agent to run thrum prime again in its own session.

Cause. The command ran from a folder where no registered agent lives (your home folder, for example), or the daemon restarted and has not yet matched this agent again.

Fix.

1. If the folder is an agent’s folder, ask your coordinator: Have reviewer_api run thrum prime in its own session. Use the agent’s name from the message. This lets the daemon match the agent to its folder again.
2. If it is not an agent’s folder, ask the coordinator to run the command from the right agent, or to create the agent first.

identity guard "unauthenticated_rpc" fired: owner_cwd_write_refused

Cause. You typed a command that changes state in a shell inside an agent’s folder (the repository root, for example). Thrum could tell whose folder it is but had no proof that a running agent sent the command, so it refused the change.

Fix. Ask your coordinator to make the change. Reading commands are not blocked.

identity guard "prime_ownership" fired: caller_not_topmost_runtime

The remediation line says “you appear to be running inside a sub-agent”.

Cause. A sub-agent (a helper that an agent starts inside its own session) tried to run thrum prime. The outer session owns the identity, not the helper.

Fix. Ask your coordinator to make sure the agent primes from its main session, not from a sub-agent inside it.

identity guard "daemon_writer_liveness" fired: subject_pid_dead

The remediation line says “daemon refusing to write to dead agent’s identity file”.

Cause. An agent’s session had already ended when something tried to update its identity. Thrum refuses so a stale request cannot revive a dead agent.

Fix.

1. Ask the coordinator to restart the agent. Check the Agents grid in the web UI for it.
2. If the message returns after the restart, ask the coordinator to restart the daemon (the background process Thrum runs on your machine). The typed form is thrum daemon restart.

Names that are taken or missing

identity guard "quickstart_name_collision" fired: name_held_by_live_foreign_pid

The remediation line reads "<name>" is registered to a different live agent — choose another --name.

Cause. You or the coordinator tried to register a new agent under a name that a running agent already holds.

Fix. Pick a different name. Ask the coordinator: “Which agents exist, and which name is free?” The Agents grid lists the names in use.

identity guard "quickstart_self_rename" fired: caller_already_owns_identity

Cause. An agent that already has an identity in this folder tried to register under a different name. Thrum will not drop the old name without a record.

Fix. Decide which you want. To keep the existing name, ask the coordinator to leave the agent as it is; the agent can run thrum prime to resume. To rename it on purpose, ask the coordinator to do the rename.

refusing to bind new agent "<name>" to the main repo

Cause. A new agent was registered from the repository’s main folder instead of its own worktree. A worktree is a second checkout of the repository, so each agent has its own files.

Fix. Ask the coordinator to create the agent in its own worktree. The typed form, which the message itself names, is thrum worktree create <name>.

role not specified: set THRUM_ROLE, use --role flag, or create identity file

Cause. The command ran where no agent is registered, so Thrum does not know who is asking. A variant says “no agent identities registered in this worktree”.

Fix. Ask the coordinator to create the agent for that folder. Run thrum whoami in the folder to see which identity, if any, Thrum finds there.

cannot auto-select identity: <n> identity files found in .thrum/identities/

The hint line says set THRUM_NAME=<name> to select one, or run from the correct worktree.

Cause. Several agents share one folder, and the command does not say which one is asking.

Fix. Ask your coordinator to run the command from the agent’s own worktree. If the agents must share a folder, ask it to set THRUM_NAME to the agent’s name.

identity guard "non_git_bootstrap" fired: not_a_git_repo

The message shows a “caller cwd” with no repository above it.

Cause. You ran thrum init or thrum daemon start outside a git repository. Thrum needs the repository to know whose work it is recording.

Fix. Change to the repository folder and run the command again. Check it worked: the command runs without the guard message. Check it worked: the command runs without the guard message.

Still stuck?

• Fix common errors: the daemon is not running, tmux is missing, a recipient is unknown. tmux keeps each agent running in its own terminal session.
• Fix sync problems: messages do not cross machines.
• Message your agents: how agents address each other.