/claim-agent-ownership

name: claim-agent-ownership
scope: common
description: |
  Orchestrator skill for resolving multi-daemon binding contention. Use when you (the
  orchestrator) detect an `agent.binding.contested` sync event indicating two daemons
  are racing for the same agent — explicitly rebind ownership to a chosen target daemon
  so subsequent dispatches route deterministically. Implements Gap G-2-⑤ on top of the
  Wave 2-B2 `/api/im/agent-bindings/:agentImUserId/rebind` endpoint.
applies_to: [hermes, claude-code, openclaw, codex]
phaseModel:
  defaultPhase: tool_use
version: 1

Claim Agent Ownership

When two daemons (typically Mac Studio at home + a k8s pod) both run `agent.host.declare` for the same agent, the first one wins ownership and the second registers a **contested** binding. The user UI surfaces a "binding contested" badge and the cloud's `resolveAgentDaemonRoute` keeps routing dispatches to the original owner — but a human-driven or orchestrator-driven decision is needed to converge.

This skill is the **orchestrator's tool for that decision**. It calls the server's authoritative rebind endpoint, which atomically:

1. flips `im_agent_bindings.boundDaemonId` to the chosen target daemon 2. writes an audit row with `boundBy='user-explicit'` (or `'orchestrator'`) 3. returns the **in-flight task count** on the previous owner so the orchestrator can wait / drain before redirecting traffic 4. emits a sync event (`agent.binding.rebound`) so other daemons drop their hosting state for the agent

When to use

• A sync event with type `agent.binding.contested` arrives in your inbox.
• A user explicitly asks "the agent is bouncing between machines — pin it to my laptop".
• You (orchestrator) decide to migrate an agent off a misbehaving daemon (high error

rate, stale heartbeats, etc.) and a target is available.

• Devices panel shows >1 daemon claiming the same agent and the user requests

arbitration.

**Do not** use it for:

• Healthy single-daemon bindings (no contention — nothing to claim).
• Agents the orchestrator does not own / has no permission for (server rejects 403).
• Routing decisions that should be reversible at the chat-message level (use

`metadata.daemonId` overrides in single dispatches instead).

API

There is **no generic `cloud im get` / `cloud im post`** subcommand in the runtime CLI contract described here (`sdk/cloud/` and `sdk/prismer/`). A dedicated `cloud agent rebind` verb is not landed either. The skill calls the cloud HTTP endpoint directly via `curl` (or the equivalent fetch from the orchestrator's MCP runtime), authenticating with the daemon API key already present in the environment as `$PRISMER_API_KEY`:

Before a write, resolve the actual workspace, agent ID, target daemon ID and authorized identity from the current runtime. `aip-identity` is not a bundled prerequisite; use the available identity/read-only binding interface. Missing identity or unavailable endpoint is a stop condition, not permission to invent IDs or switch accounts. Confirm migration impact and drain in-flight work.

# Inspect the current bindings first.
curl -fsS \
  -H "Authorization: Bearer $PRISMER_API_KEY" \
  "$PRISMER_CLOUD_BASE/api/im/workspaces/<workspaceId>/agent-bindings"

# Issue the rebind. Requires workspace owner / active orchestrator / admin.
curl -fsS \
  -X POST \
  -H "Authorization: Bearer $PRISMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetDaemonId":"<daemonId>","targetDaemonKind":"local","reason":"<short reason>"}' \
  "$PRISMER_CLOUD_BASE/api/im/agent-bindings/<agentImUserId>/rebind"

`PRISMER_CLOUD_BASE` defaults to the cloud the daemon paired with (`https://prod.docbrew.cn` in prod, `http://127.0.0.1:3000` in local dev).

For pure-API use (orchestrator runtime, MCP tool, etc.), the underlying call is:

POST /api/im/agent-bindings/:agentImUserId/rebind
Authorization: Bearer <daemon api key>
Content-Type: application/json

{
  "targetDaemonId":   "daemon-mac-studio-01",   // required, must exist in workspace
  "targetDaemonKind": "local",                  // optional: 'k8s' | 'local' | 'edge'
  "targetDaemonLabel": "Mac Studio (home)",     // optional display label
  "reason":           "user prefers desktop daemon while on home network"
}

Successful response:

{
  "ok": true,
  "data": {
    "binding": {
      "agentImUserId":     "u_agent_ceo",
      "boundDaemonId":     "daemon-mac-studio-01",
      "boundDaemonKind":   "local",
      "boundDaemonLabel":  "Mac Studio (home)",
      "boundBy":           "user-explicit",
      "boundAt":           "2026-05-22T16:30:00.000Z"
    },
    "inFlightTaskCount":   3,
    "previousDaemonId":    "daemon-k8s-pod-7f4"
  }
}

Failure modes worth handling explicitly:

| Status | Code (in body) | Meaning | | --------------------- | ------------------------------- | -------------------------------------------------------------------- | | `400` | `target daemon ... not registered` | Target daemonId not in `im_containers` for this workspace. | | `400` / missing field | `targetDaemonId is required` | Body parse / missing required field — surface as developer error. | | `403` | `Forbidden` | Caller is not workspace owner / orchestrator / admin. | | `404` | `Agent not found ...` | Agent has no `im_agent_cards` row (deleted? wrong id?). | | `404` | `No binding row exists ...` | Agent never ran host.declare. Tell the daemon to declare first. | | `409` | `target daemon ... is stopped` | Target container has `stoppedAt` set — pick a different target. |

Workflow

1. **Subscribe to `agent.binding.contested` sync events.** The orchestrator's sync inbox delivers these out of band; the skill consumes them. 2. **Resolve the ta