docs(server): name the metadata gap when a handle-less agent is recreated on load

packages/server/src/server/agent/agent-loading.ts

@@ -132,6 +132,10 @@ export async function ensureAgentLoaded(
       if (!config) {
         throw new Error(`Agent ${agentId} references unavailable provider '${record.provider}'`);
       }
+      // Known gap: `record` was read before this create, and createAgent deletes the stored
+      // state outside the agent's lifecycle lane. A setMetadata that saves between the read and
+      // the delete is overwritten by this stale metadata. The fix is to read and delete the
+      // stored record inside the lane (createAgentInternal), which is a lifecycle change.
       snapshot = await deps.agentManager.createAgent(config, agentId, {
         labels: record.labels,
         metadata: record.metadata,